Hummingbird Help Center
  • General
    • Adding additional data to a review (Custom Fields)
    • What is Hummingbird?
    • How do I send feedback or get answers to my questions about Hummingbird?
    • How do I sign-in to Hummingbird for the first time?
    • What are the Hummingbird APIs?
    • What is Hummingbird’s onboarding process?
    • What’s Hummingbird’s data retention policy?
    • What’s Hummingbird’s security and data management policy?
    • Which browser is Hummingbird compatible with?
    • Which features should I highlight during an audit? What should I present to the regulators?
  • Analytics
    • How can I export data from an Analytics table?
    • Where can I see a summary of all my cases over time?
    • Where can I see a summary of all the stats associated with my cases?
    • Where can I see my team's workload and analyze the time it takes to complete reviews?
  • Case Management
    • How can I add tags to cases?
    • Can I delete cases that were created by accident?
    • Can I make changes to a case that’s already been submitted for approval?
    • Can I set ongoing monitoring/reminders for certain cases? Where can I find these cases?
    • How can I add an approver in within a review?
    • How can I assign a review to a team member?
    • How can I change the assignee name on a completed review?
    • How can I configure workflows in Hummingbird?
    • How can I confirm that a file has successfully been imported in Hummingbird?
    • How can I create a new case?
    • How can I create triggers for a case?
    • How can I filter my cases by review type?
    • How can I reorder existing columns or add columns on my dashboard?
    • How can I see time-sensitive (high priority) cases?
    • How can I verify that the cyber event indicators have been imported correctly?
    • How can I view details of a case or work on a case?
    • How can I view and manage Subject data?
    • How can I see all Profiles associated with my cases?
    • How do I complete a review (from start to finish)?
    • How do I manually import data into Hummingbird?
    • How does the timestamp work in Hummingbird?
    • How can I download case files?
    • How should I manage case names in Hummingbird?
  • Collaboration
    • Are comments included in SAR filings or other reports?
    • How can I alert a team member to a case?
    • How can I manage a joint SAR?
    • Where can I find my in-app notifications?
    • Where can I leave comments for team members in Hummingbird?
    • How can I add formatting to my Narratives?
    • Where can I manage my email notifications?
  • Data Integrations
    • How should I integrate transaction monitoring alerts? What’s the recommended data flow?
    • Reporting Credit Card Numbers on SAR Forms
    • What are the minimum data requirements for importing transactions?
    • Why did Hummingbird reject my file import? Why did my file fail to import?
    • When importing data to existing cases, how are locked cases handled?
  • Features
    • Batch Filings w/ FinCEN
    • Case File Attachments
    • Case Pinning
    • Enhanced Dashboard Filtering
    • CRM Entity Merging
      • Expectations
      • API Interaction
      • Upcoming work
    • CRM Profile Attachments
    • CRM Relationships (including beneficial owners)
    • Queue Assignments
    • Quick Links
    • Tag Management
    • Traceable Filings
    • Can I lock the information in a case?
    • Can I add custom suspicious activities to the Activities task?
    • Can I configure surveys within a workflow?
    • How can I add information to a case?
    • How can I remove a Profile from a case?
    • How can I update information for an entity?
    • How can I visualize the connections among all the entities within a case?
    • How can I visualize the location of each of the entities associated with a case?
    • How will the information in my case map to fields in Suspicious Activity Reports (SARs)?
    • What are narrative templates and where I can manage them in Hummingbird?
    • How do I manage transactions?
    • Would I get notified when a subject is involved in another case?
    • Hummingbird AI: Security & Privacy Overview
  • Hummingbird API
    • How do I generate API keys?
    • How do I get started with Hummingbird’s API integration?
    • Is there a limit on the size of API calls?
    • What’s the difference between the Alerts API and the Case API?
    • Where can I get more information about why an API call failed?
    • Can I upload files over the API?
      • Supported Mime Types
    • How do I upload larger Alerts data via API?
  • Platform Administration
    • Can Hummingbird auto-assign reviews to my teammates?
    • Can I remove certain data imports or clear out the entire import history in my sandbox or production
    • How Do I Export My Organization's History?
    • How can I switch between organizations I’m assigned to?
    • How can I view or change information about my team or organization?
    • How are Filing Institutions and Financial Institutions related?
    • How do badges (roles & permissions) work in Hummingbird?
    • How do I access my Hummingbird sandbox or production environment?
    • How do I switch the integration from sandbox to production at launch?
    • How does the out of office functionality work in Hummingbird?
    • How should I configure my firewall settings?
    • What’s the difference between the Organization tab and the Filing Institution tab in Settings?
    • Where can I check the system status of the Hummingbird platform?
    • Where can I manage my account information?
    • Where can I see a history of user activity in Hummingbird?
    • Where can I see a list of released features within the Hummingbird platform?
  • Reporting
    • Does Hummingbird guarantee that SAR filings won’t receive warnings or be rejected?
    • How can I flag transactions? How can I view the list of flagged transactions as part of the SAR?
    • How do I connect Hummingbird to FinCEN?
    • How does FinCEN process SAR filings? How long does it typically take to process these filings?
    • How does Hummingbird manage connectivity to FinCEN?
    • What happens if I mistakenly resubmit a SAR filing that has already been sent to FinCEN?
    • What is the Hummingbird SAR Filing API?
    • Where can I download a case data summary report?
    • Why are validation errors preventing me from closing out or submitting a case?
    • Does FinCEN support Unicode characters?
    • Why aren’t the dates of birth for subjects populating in the FinCEN SAR PDF?
  • User Administration
    • How can I add users to my sandbox or production accounts?
    • How can I remove users from my sandbox or production accounts?
    • How can I reset my password?
    • Password Policy
    • How do I set up two-factor authentication?
    • Do you support Single Sign-On?
    • Enabling Directory Sync (SCIM) for Hummingbird
  • Notices
    • Planned Maintenance Schedule
Powered by GitBook
On this page
  • 1. Create an attachment token POST /attachments
  • 2. Uploading your attachment file to AWS S3
  • 3. Create/Update a case with an attachment
  • Frequently Asked Questions

Was this helpful?

  1. Hummingbird API

Can I upload files over the API?

PreviousWhere can I get more information about why an API call failed?NextSupported Mime Types

Last updated 4 months ago

Was this helpful?

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 .

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

  • Most Office files (Outlook, Excel, Word, PowerPoint)

  • And many more - for the full list see Supported Mime Types

  • 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.

API documentation