Can I upload files over the API?

Yes! We support adding file attachments over the API.

The basic high level overview of how to use this API involves 3 steps an integrator must take:

1. Create an attachment token and pre-signed upload data

2. Upload the file to AWS S3 utilizing the provided pre-signed upload data provided in step 1.

3. Create or update a case/alert with the attachment token provided in step 1.

All requests to the Hummingbird API should include an Authorization header with your access token. For additional details on authorization and detailed specification for the API, refer to our API documentation.

1. Create an attachment token POST /attachments

The first step is to fetch an attachment token and details on where to upload your attachment file. The following is an example curl request. The only data required is the filename of the file you plan to upload and the mime_type of the file.

We do have restrictions on the types of files that are allowed to be uploaded. At this time, we allow:

• image/* , audio/*, and text/*file types

• application/pdf and application/zip files

• CSVs with a mime type of text/csv

• Excel (xlsx only) with a mime type of application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

• Files can be up to 100mb in size

curl -d '{"filename":"image.png", "mime_type":"image/png"}' -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer <ACCESS TOKEN>" -X POST <https://api.staging.hummingbird.co/attachments>

The response will include two attributes: token and upload. Here is an example response:

{
    "upload": {
        "method": "post",
        "url": "...",
        "fields": {
            "key": "...",
            "Content-Type": "image/png",
            "Expires": "Tue, 12 Jul 2022 15:43:12 GMT",
            "policy": "...",
            "x-amz-credential": "...",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-date": "...",
	    "x-amz-security-token": "..."
            "x-amz-signature": "..."
        }
    },
    "token": "gFDqw8ZStsTyai7qLQDTYq9N"
}

The upload data describes where/how to upload your attachment file to S3 while the token is to be used later when creating/update a case.

If you plan to include multiple attachment files on a case you will need to send a request to POST /attachments for each file you plan to attach. Keep each token and submit them all as part of your case data in step 3 below.

2. Uploading your attachment file to AWS S3

To upload a file to S3 you must send a multipart/form-data request using the data provided in the previous step.

From the response you received above in step 1 we have the portion that represents your upload:

{
        "method": "post",
        "url": "<https://s3.us-west-2.amazonaws.com/hummingbird.transient-attachments.development>",
        "fields": {
            "key": "...",
            "Content-Type": "image/png",
            "Expires": "Tue, 12 Jul 2022 15:43:12 GMT",
            "policy": "...",
            "x-amz-credential": "...",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-date": "...",
	    "x-amz-security-token": "..."
            "x-amz-signature": "..."
        }
}

We use this data to build our multipart/form-data request. Note the attributes nested under fields are the form fields to be included in the request. All fields are required to be submitted along with a the file.

Please note that the content-type of the request should be multipart/form-data. This is different than the ‘Content-Type’ form field data provided.

curl --location --request POST '<URL>' \\
-H "Content-Type: multipart/form-data" \\
-H "Accept: application/json" \\
--form 'key="..."' \\
--form 'Expires="Thu, 21 Jul 2022 18:50:32 GMT"' \\
--form 'Content-Type="application/pdf"' \\
--form 'policy="redacted"' \\
--form 'x-amz-credential="..."' \\
--form 'x-amz-algorithm="AWS4-HMAC-SHA256"' \\
--form 'x-amz-date="20220721T184032Z"' \\
--form 'x-amz-signature="redacted"' \\
--form 'x-amz-security-token="redacted"' \\
--form 'file=@"/path/to/your/file/image.png"'

Upon a successful upload we are now good to create/update a case.

3. Create/Update a case with an attachment

Case

Now it is time to put the attachment token we received in step 1 to use. Using or cases API we can now submit our attachment(s) to be included on our case.

Here is an abbreviated example payload to POST /cases with an attachment:

{ 
  "case": { 
    "name": "Case 123", 
    "id": "123",
    "type": "filing",
    "bank_accounts":[...],
    "individuals":[...],    
    "institutions": [...],
    "attachments": [
      {
        "token": "gFDqw8ZStsTyai7qLQDTYq9N"
      }
    ],
    "filings": [...]		
  } 
}

Up to 10 attachments can be uploaded to a case in this manner. The same attachments format can be used when updating a case.

Alert

You can use a similar format to upload an alert, include attachment token in the data section of the alert payload

Here is an example payload that can be submitted to POST /alerts

{
  "alerts": [
    {
      "id": "alert-id",
      "rule": "alert-rule",
      "triggered_at": "2099-04-25T22:11:24.925339Z"
    }
  ],
  "workflow": "triage",
  "data": {
    "individuals": [...],
    "transactions": [...]
    "attachments":[
        {
            "token" : "gFDqw8ZStsTyai7qLQDTYq9N"
        },
        {
            "token" : "gFDqw8ZStsTyai7qLPEUXr10O"
        }
    ]
  }
}

Up to 10 attachments can be included with each call to the Alert API.

Fetching Attachments From a Case

You can also pull attachment files from a case to download to your own system of record. To fetch attachment data along with a pre-signed url enabling you to download the file, make a request to GET /cases/{case_token}/attachments. The same attachment data is included when fetching an a case as well (GET /cases/{case_token}).

An example response is as follows:

{
    "attachments": [
        {
            "token": "FimZ1xUCskiqnKbGETMcmUqt",
            "filename": "image.png",
            "createdAt": "2022-07-15T14:51:40.919Z",
            "updatedAt": "2022-07-15T14:51:40.919Z",
            "contentType": "image/png"
            "url": "..."
        }
    ],
    "success": true
}

Frequently Asked Questions

How can I test these APIs?

We recommend testing in your Sandbox environment. Remember that Sandbox is only designed for use with fake data, and no PII should be sent.

What is the lifespan of the pre-signed URLs?

10 minutes

Can I upload multiple files using the same attachment S3 url and upload data?

You will need to request a new attachment token/upload data (step 1 above) for each file you wish to upload and attach to a case. AWS S3 will allow you to upload multiple files using the same upload data (assuming it hasn’t expired). If you upload more than one file using the same upload data, older uploaded files will be overwritten and only the last file you uploaded will be added to the case.

Can I attach the same file to multiple cases?

An attachment token can only be used once to associate a file with an attachment on a case. If you want to upload the same file to multiple cases you will need to request a new attachment token and upload the file to S3 for each case.

Why do I need to create three separate requests in order to attach a file through API?

At this time, we want to avoid having files transiting our backend to be uploaded. Very large files could potentially cause performance issues. With that, we're currently utilizing AWS S3's file upload capabilities which handles upload, retry, and chunking efficiently.