This delivery mechanism may be preferable if the customer leverages an underlying storage mechanism like AWS S3 from which URLs can be created, or if the URL to which the report must be sent could change with each delivered report.

The request pattern for pre-signed URL delivery follows roughly this pattern:

Human API will make a POST request of a customer endpoint using the request schema below; this request can support several different forms of authentication (HTTP Basic, OAuth2, static headers/tokens) as well as mTLS if needed
The customer will accept this request, and reply with an HTTP 201 along with the response schema below indicating successful creation of a pre-signed URL, and optionally the request method to use when delivering the report contents. A non-HTTP 201 response will be indicative of an error (whichever code is most appropriate - eg. 400 for a request with an invalid body, 401 for invalid authentication, etc.)
Human API will make the final request using the supplied pre-signed URL, HTTP method (if provided - POST by default), and relevant pre-configured authentication, headers, or mTLS support if needed; the mime type of the request will match the file type (JSON, PDF, Zip, etc.)
The customer’s response to being sent the report should include a 200-series HTTP status code - no parsing or further interpretation of the response body is performed by Human API

Should any of the above requests to the customer fail up to 5 retries will be made in quick succession. If Human API continues to encounter failed requests, up to 5 attempts of this retry process are performed over several hours after which if Human API has been unable to complete delivery, the affected order will be sent for triage by Human API’s technical support team.

Review the Request & Response schemas and samples below.

Request Schema (JSON schema)

`{
    "type": "object",
    "required": [
        "orderId",
        "clientUserId",
        "userId",
        "humanId",
        "clientId",
        "fileType"
    ],
    "properties": {
        "orderId": {
            "type": "string",
            "format": "uuid",
            "description": "A unique identifier for this HIP order"
        },
        "clientUserId": {
            "type": "string",
            "description": "A unique identifier for the enduser as supplied by the customer"
        },
        "userId": {
            "type": "string",
            "description": "A unique internal identifier for the enduser within the context of the customer's application"
        },
        "humanId": {
            "type": "string",
            "description": "A unique identifier for the enduser within the context of the customer's application"
        },
        "clientId": {
            "type": "string",
            "description": "The unique identifier for the customer's application"
        },
        "clientData": {
            "type": "object",
            "description": "Data submitted along with order, as provided by customer"
        },
        "fileType": {
            "type": "string",
            "enum": [
                "report"
            ],
            "description": "The type of file being sent"
        },
        "report": {
            "type": "object",
            "required": [
                "id",
                "name",
                "fileExtension",
                "filename",
                "uri"
            ],
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The unique identifier for the report being sent"
                },
                "name": {
                    "type": "string",
                    "enum": [
                        "aps",
                        "apidata",
                        "ccdraw",
                        "clinicalhistory",
                        "fhir",
                        "highlights",
                        "healthcheck",
                        "combined"
                    ],
                    "description": "The type of report being sent"
                },
                "baseReportNames": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "aps",
                            "apidata",
                            "ccdraw",
                            "clinicalhistory",
                            "fhir",
                            "highlights",
                            "healthcheck",
                            "combined"
                        ]
                    },
                    "description": "The types of reports contained within a combined report, if applicable"
                },
                "fileExtension": {
                    "type": "string",
                    "enum": [
                        "json",
                        "html",
                        "pdf",
                        "zip",
                        "pgp"
                    ],
                    "description": "The file extension of the report"
                },
                "filename": {
                    "type": "string",
                    "description": "The filename of the report (matching customer templating configuration)"
                },
                "uri": {
                    "type": "string",
                    "format": "uri",
                    "description": "A URI indicating from where the report could be requested in lieu of being sent"
                }
            },
            "description": "The report object, a collection of properties describing the report being sent"
        }
    }
}

Example Request

{
    "orderId": "408bfc70-6d19-11ee-823d-e96c578d4a5b",
    "clientUserId": "testUser1234",
    "userId": "1234567890abcdef12345678",
    "humanId": "9876543210abcdef9876543210abcdef",
    "clientId": "fedcba0123456789fedcba0123456789fedcba01",
    "fileType": "report",
    "report": {
        "id": "5c975b20-5eec-11ee-bb1a-f339bf15cab3",
        "name": "combined",
        "fileExtension": "pdf",
        "filename": "testUser1234.pdf",
        "baseReportNames": ["highlights", "clinicalhistory"],
        "uri": "https://admin.humanapi.co/api/v1/user/reports/5c975b20-5eec-11ee-bb1a-f339bf15cab3"
    }
}

Response Schema

{
    "type": "object",
    "required": [
        "presignedUri"
    ],
    "properties": {
        "presignedUri": {
            "type": "string",
            "format": "uri",
            "description": "The URI to which a request will be made to deliver the report or file in question"
        },
        "requestMethod": {
            "type": "string",
            "enum": [
                "post",
                "put"
            ],
            "default": "post",
            "description": "The HTTP method to use for the request"
        }
    }
}`

Example Response

{
    "presignedUri": "https://myshippable.url.com/a_specific_file.pdf?token=1234",
    "requestMethod": "put"
}