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
  • Introduction
  • Technical Implementation
  • POST /alert_uploads
  • Client-Side Encryption
  • PUT /alert_uploads/{token}/complete
  • GET /alert_uploads/{token}
  • Frequently Asked Questions
  • Resources

Was this helpful?

  1. Hummingbird API

How do I upload larger Alerts data via API?

PreviousSupported Mime TypesNextPlatform Administration

Last updated 2 years ago

Was this helpful?

Introduction

Larger alerts (>2MB) can be sent to Hummingbird via the Alerts Upload API.

The Alerts Upload API will involve a 4-step client flow:

  1. Client requests an upload URL by calling the POST /alert_uploads endpoint.

  2. Client uploads the encrypted alerts data to the provided URL.

  3. Client notifies Hummingbird that the upload has been completed by calling the PUT /alerts_uploads/{token}/complete endpoint

  4. Client polls for the outcome of upload by calling the GET /alert_uploads/{token} endpoint

Technical Implementation

POST /alert_uploads

This is the first API endpoint called to begin the Alerts Upload process.

Authentication for this endpoint is the same as all of the Hummingbird API.

The request body should be an empty JSON object.

The response format will be a JSON object with the following format:

{
 "success": true,
 "alert_upload": {
   "token": "ZxiJDeAVWmDUaa7iDJLGArCJ",
   "upload": {
     "method": "post",
     "url": "https://s3.us-west-2.amazonaws.com/hummingbird....",
     "fields": {
       ...
     }
   },
   "encryption": {
     "version": 1,
     "public_key": {
       "id": "FVczGR6DDoKYHSY2LpiG6XGQ",
       "key": "-----BEGIN PUBLIC KEY-----..."
     }
   }
 }
}

Client-Side Encryption

Encrypted Format

The encrypted content is formatted as follows:

<JSON header>\0<encrypted payload>

The format for the JSON encryption metadata varies depending on the version of encryption scheme used, and is described in more detail below. At a minimum, the header will contain a “version” key.

Version 1

This encryption scheme implements a simple sealed envelope using RSA-4096 (PKCS1) for key wrapping and AES-256-GCM for data encryption. A random session AES key and initialization vector are generated for each message.

The RSA public key used for key wrapping is provided in the API response in the first step for convenience. This is a long-lived key, and may also be shared or verified out-of-band, or hard-coded in the client depending on your desired security posture.

The public key id is a unique identifier for the public key. It is used during decryption to locate the appropriate private key and facilitate key rotation.

The format for the version 1 encryption metadata header is:

{
 "version": 1,
 "key_id": "hb-123",
 "encrypted_session_key": "base64(aes session key)",
 "iv": "base64(iv)",
 "auth_tag": "base64(auth_tag)"
}

Upload to S3

After the content is encrypted it should be uploaded to S3 using the pre-signed URL and fields obtained from the first API call. This should use an HTTP POST. See AWS documentation for more details about this.

Total upload size is limited to 10MB in order to protect the user experience for your investigators who ultimately may have to manually review all of the uploaded data. Please reach out to our customer success team if this limit is too restrictive.

Pre-signed URLs will have very short validity and should be used immediately after retrieval.

Tip: Ensure that the Content-Type is multipart/form-data, and that the form data includes everything provided in ‘upload.fields’, in addition to the encrypted envelope as ‘file’.

An example curl request to upload data to S3:

curl --location --request POST 'https://s3.us-west-2.amazonaws.com/hummingbird.XXX' \
--form 'key="alert_uploads/XX"' \
--form 'acl="private"' \
--form 'x-amz-meta-hb-organization-token="XXX"' \
--form 'x-amz-meta-hb-key-id="XXX"' \
--form 'policy="XXX"' \
--form 'x-amz-credential="XXX"' \
--form 'x-amz-algorithm="XXX"' \
--form 'x-amz-date="XXX"' \
--form 'x-amz-security-token="XXX"' \
--form 'x-amz-signature="XXX"' \
--form 'file=@"/tmp/encrypted_envelope"'

PUT /alert_uploads/{token}/complete

Notify Hummingbird that the upload has been completed. Send an empty JSON object {}. Use the token obtained from the response to the initial GET request.

Hummingbird will synchronously verify that the uploaded file exists in S3 and enqueue for further processing. No other verification or processing will occur as a result of this call.

The response will be in the same format as the response to GET /alert_uploads/{token} described next.

GET /alert_uploads/{token}

This endpoint can be polled for the results of the upload.

Alerts processing takes place asynchronously and we occasionally receive high volumes in short periods of time which can lead to temporarily longer queuing times. Please be mindful of this when polling this endpoint if you find that the alerts processing times vary. We generally aim to process alerts within 24 hours, though most alerts are processed within an hour.

This endpoint returns the overall status of the alert, an error message if one occurred, as well as an array of AlertFetchResponse objects, the same response typically provided by the GET /alerts/{token} endpoint on a per-alert basis. The array of alerts will remain EMPTY until ALL alerts in the upload have been processed, and the status is either PROCESSED or ERROR.

The response format is as follows:

{
 "success": true,
 "alert_upload": {
   "token": "Hn4JsTGbMTy2nmJEDokwZArf",
   "updated_at": "2021-11-12T19:11:37.889Z",
   "created_at": "2021-11-12T19:11:36.948Z",
   "alert_processing_started_at": null,
   "failed_at": null,
   "error_message": null,
   "status": "PENDING|PROCESSING|PROCESSED|PROCESSING_ERROR|UPLOAD_ERROR",
   "alerts": [AlertFetchResponse, ... ]
 }
}

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?

5 minutes

Is the RSA public key the same for all customers?

It is not. A separate 4096 bit RSA key is generated for each customer.

How is the S3 bucket secured?

Data is encrypted with S3 server-side encryption in addition to the client side encryption described above. All objects are ‘private’ and versioned by default. S3 bucket configurations are regularly inspected as part of security audits and penetration testing. Is there a rate limiting on the polling endpoint? Not at this time.

How long does alert processing take?

We process alerts asynchronously, so processing times vary. We aim to process all alerts within 24 hours, though most alerts are processed within an hour.

Resources

The JSON body to be uploaded is the same as a request body sent to the synchronous . The payload must be encrypted client-side before upload using the public key returned from the initial API call and uploaded to the URI provided in that same response.

A JSON-formatted encryption metadata header is followed by a NULL byte which is followed by the encrypted payload in binary.

The following example code implements the version 1 encryption scheme in Ruby, using OpenSSL. The encrypt() method outputs the full content which is to be uploaded using the pre-signed URL. See .

POST /alerts endpoint
AlertRequest
this Github Gist
Hummingbird API documentation
End-to-End Example in Python
Example Encryption in Ruby
Example Encryption in Golang