NAV Navbar
cURL Python

Introduction

The code samples for each API appear in this pane. When you point your mouse to a code sample, the Copy button appears, which allows you to copy that code block so you can paste it in your own code or command line.

alt text

Welcome to the Jumio AML Developer Portal! This section provides an overview of the tools available for working with Jumio Transaction Monitoring and the Jumio Investigation Manager. Note that some functionality described in this document might be unavailable depending on the scope of your license with Jumio; contact your Jumio Solutions Engineer if you have questions.

Sending data to Jumio

To begin, you send your data to the Jumio platform, either in batches using file-based data ingestion or in real time using the Data Ingestion API. For example, many customers send their historical data as CSV files and then use the APIs to send data in real time as JSON objects. You can use whichever approach works best for you; for assistance, consult your Jumio Solutions Engineer.

Creating and retrieving objects in the Jumio Investigation Manager

After you send your data to Jumio, the detection engine creates cases when it detects scenarios that need further review, such as suspicious activity, parties requiring identity verification, or parties with watchlist matches. Analysts then use the Jumio Investigation Manager to investigate and manage those cases. Developers can use the Investigator API to programmatically retrieve cases, upload documents, and create cases from an external system such as Salesforce if needed.

Subscribing to notifications

Jumio generates notifications for key events, such as when a transaction or party exceeds a certain threshold. You can subscribe to these notifications using the Webhooks API so that you can integrate them with a separate workflow in an external system. For example, if you want to be notified immediately if one of your customers violates an implemented policy, you could subscribe to the alert.created notification and write logic in your system to temporarily lock that user's account.

Handling errors

For information on handling errors in any of the Jumio AML APIs, see Error handling.

Enabling direct SAR filing

Jumio can file your Suspicious Activity Reports (SARs) directly with FinCEN. To enable this integration, see SAR filing integration.

What's new in this release

To see a history of the changes to this documentation, see Change log.

Beta features

Features marked as "beta" in this documentation are still being tested and may not be available in your Jumio environment.

Accessing the APIs

First, get your access token, replacing $CLIENT_KEY with the key Beam gave you and replacing $CUSTOMER with your company name. In these examples, we create variables to make subsequent API calls easier.

Jumio Enterprise customers:

AUTH_PATH=https://$CUSTOMER.api.beamtechnology.com:8888/token
TEST_PATH=https://$CUSTOMER.api.beamtechnology.com:8888/system/v1/test
BASE_PATH=https://$CUSTOMER.api.beamtechnology.com:8888
ACCESS_TOKEN=`curl -d "grant_type=client_credentials" -H "Authorization: Basic $CLIENT_KEY" $AUTH_PATH | tr '"' ' ' | awk '{print $4}'`
import requests
import json

# Set all all the variables you will use for your API calls
auth_path = https://$CUSTOMER.api.beamtechnology.com:8888/token
client_key = $CLIENT_KEY
test_path = https://$CUSTOMER.api.beamtechnology.com:8888/system/v1/test
base_path = https://$CUSTOMER.api.beamtechnology.com:8888

headers = {
    'Authorization': 'Basic {}'.format(client_key)
}

data = {
    'grant_type': 'client_credentials'
}

auth_response = requests.post(auth_path, headers=headers, data=data)

# Read token from auth response
auth_response_json = auth_response.json()
access_token = auth_response_json['access_token']

Jumio Express customers:

AUTH_PATH=https://express.api.beamtechnology.com:8888/token
TEST_PATH=https://express.api.beamtechnology.com:8888/$CUSTOMER/system/v1/test
BASE_PATH=https://express.api.beamtechnology.com:8888/$CUSTOMER
ACCESS_TOKEN=`curl -d "grant_type=client_credentials" -H "Authorization: Basic $CLIENT_KEY" $AUTH_PATH | tr '"' ' ' | awk '{print $4}'`
import requests
import json

# Set all the variables you will use for your API calls
auth_path = https://express.api.beamtechnology.com:8888/token
client_key = $CLIENT_KEY
test_path = https://express.api.beamtechnology.com:8888/$CUSTOMER/system/v1/test
base_path = https://express.api.beamtechnology.com:8888/$CUSTOMER

headers = {
    'Authorization': 'Basic {}'.format(client_key)
}

data = {
    'grant_type': 'client_credentials'
}

auth_response = requests.post(auth_path, headers=headers, data=data)

# Read token from auth response
auth_response_json = auth_response.json()
access_token = auth_response_json['access_token']

After receiving the token, test your access and look for the 204 status code indicating success.

curl -H "accept: */*" -v -H "Authorization: Bearer $ACCESS_TOKEN" $TEST_PATH
import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
}
response = requests.get(test_path, headers=headers)

# Print the status code to verify that it is a 204
print(response.status_code)

Before you start calling the APIs, you must obtain your Beam access token. Use the /token endpoint as shown in the examples on the right, replacing CLIENT_KEY with your unique client key provided to you by Jumio. If you have not yet received your client key, contact Support at support@jumio.com. By default, the access token expires in one hour; Jumio Support can change this for you if required.

After you receive your access token, use the test endpoint to verify access to the Jumio server as shown in the examples. If successful, the HTTP status code 204 is returned.

Base paths

You are now ready to use the APIs. Following are the base paths referenced in the examples throughout the documentation, where $CUSTOMER is your company name:

Jumio Enterprise base path:

https://$CUSTOMER.api.beamtechnology.com:8888

Jumio Express base path:

https://express.api.beamtechnology.com:8888/$CUSTOMER

After the base paths, you will use the following paths to access the APIs:

For example, to call the /parties endpoint in the Data Ingestion API, the URL for a Jumio Enterprise customer would be: https://$CUSTOMER.api.beamtechnology.com:8888/model/v1/parties

Data Ingestion API

Quick reference

After you gain access to the Data Ingestion API, you can use the following endpoints to send data to Jumio for processing and retrieve the data you've sent. For information on the full path to each endpoint, see Base paths.

Endpoint Description
POST /parties Create a party
PATCH /parties/:id Update a party
GET /parties/:id Get party details
POST /parties/:id/documents Add document metadata to a party
PUT /parties/:id/documents/:id/file Upload a document file for a party
GET /parties/:id/documents Get metadata for all documents linked to a party
GET /parties/:id/documents/:id/file Download a document file that is linked to a party
POST /accounts Create an account
PATCH /accounts/:id Update an account
GET /accounts/:id Get account details
POST /payment-sources Create a payment source
PATCH /payment-sources/:id Update a payment source
GET /payment-sources/:id Get payment source details
POST /transactions Create a transaction
GET /transactions/:id Get transaction details
POST /footprints Create a footprint

Overview

The Data Ingestion API is a public REST API that you use to integrate your data with Jumio so you can process transactions, parties, and accounts, detect suspicious activity, screen customers against watchlists and verify their identities, and investigate related data. When you call the API, you supply the IDs that the API uses to update existing data objects and to create new ones. The public API sends requests securely via SSL through a proxy URL to the internal services, which process the request and send the response back through the proxy URL to the public API, which returns the response to the caller. The API uses OAuth 2.0 to secure API access.

Data model

Jumio's internal data model revolves around the concepts of transactions, accounts, parties, payment sources, and footprints.

alt text

Example data models

Let's look at three different types of businesses and how their data is mapped to the Jumio data model.

Bank data model
Jumio entity Bank entity Comments
Party Account holder Usually one or more account holders for a given account
Account Account Usually checking or savings account but can also represent other forms, e.g., credit card
Transaction Transaction Either a deposit or withdrawal of cash (teller or ATM), check, direct-deposit, bill-payment, or internal account transfer
Payment Source Credit card, debit card, or wire Typically a bank-issued card linked to an account or pre-setup wire
Service data model
Jumio entity Service entity Comments
Party Account holder Usually one or more service holders for a given account
Account Service The service, which can be linked to multiple payment sources
Transaction Transaction A transfer to pay for the service or receive payment for the provided service
Payment Source Credit card, debit card, ACH account, Stripe, etc. Typically the payment method that allows parties to pay for services or pay out from received money
P2P data model
Jumio entity P2P entity Comments
Party Account holder Usually one or more account holders for a given account
Account Account The P2P account, which can be linked to multiple payment sources
Transaction Transaction A deposit, withdrawal, or internal account transfer
Payment Source Credit card, debit card, ACH account, Stripe, etc. Typically the payment method that allows parties to move funds in and out of the P2P ecosystem

How to...

These sections describe the APIs in detail and provide examples.

Create a party

Create a party like this:

import requests
import json

data = {
    "address": "100 Bush Street",
    "business": True,
    "citizenshipCountryIso": "US",
    "city": "San Francisco",
    "countryIso": "US",
    "custom": {
        "referrerPartyId": "1234"
    },
    "dob": "2020-02-15",
    "email": "foo.bar@domain.com",
    "fax": "+16694352341",
    "firstName": "Foo",
    "fullName": "Foo Bar",
    "gender": "m",
    "geoCode": {
        "city": "San Francisco",
        "countryIso": "US",
        "geoPoint": {
            "latitude": 0,
            "longitude": 0
        },
        "ipAddress": "64.79.119.82",
        "postal": "94105",
        "stateIso": "CA"
    },
    "group": "HQ",
    "landLine": "+16694352341",
    "lastName": "Bar",
    "merchantName": "Foo Bar",
    "middleName": "string",
    "mobile": "+16694352341",
    "occupation": "Software Engineer",
    "partyCreated": "2020-02-15T00:53:21.344Z",
    "partyId": "1234",
    "postal": "94111",
    "residenceCountryIso": "US",
    "role": "seller",
    "socialMedia": [
        "www.youtube.com/user/fooBarMe"
    ],
    "stateIso": "CA",
    "status": "active",
    "userName": "foobar",
    "verified": "unverified"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}
response = requests.post('{}/model/v1/parties'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/model/v1/parties -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -d '{
    "address": "100 Bush Street",
    "business": true,
    "citizenshipCountryIso": "US",
    "city": "San Francisco",
    "correlation": {
        "ssn_hash":"1q323425254"
    },
    "countryIso": "US",
    "custom": {
        "referrerPartyId": "1234"
    },
    "dob": "2020-02-15",
    "email": "foo.bar@domain.com",
    "fax": "+16694352341",
    "firstName": "John",
    "fullName": "",
    "gender": "m",
    "geoCode": {
        "city": "San Francisco",
        "countryIso": "US",
        "geoPoint": {
            "latitude": 0,
            "longitude": 0
        },
        "ipAddress": "64.79.119.82",
        "postal": "94105",
        "stateIso": "CA"
    },
    "group": "HQ",
    "landLine": "+16694352341",
    "lastName": "Adams",
    "merchantName": "Acme",
    "middleName": "Quincy",
    "mobile": "+16694352341",
    "occupation": "Attorney",
    "partyCreated": "2020-02-15T00:53:21.344Z",
    "partyId": "1234",
    "postal": "94111",
    "residenceCountryIso": "US",
    "role": "seller",
    "socialMedia": [
        "www.youtube.com/user/fooBarMe"
    ],
    "stateIso": "CA",
    "status": "active",
    "userName": "jadams",
    "verified": "unverified"
}'

The command returns JSON structured like this:

{
   "id": "1234",
   "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/parties/1234"
}

POST /parties

Parties are your users or customers that you are onboarding or are the participants in transactions who either send or receive money.

Party fields

Sample CSV party definition:

group,partyId,partyCreated,status,role,userName,merchantName,business,occupation,firstName,middleName,lastName,fullName,address,city,postal,stateIso,countryIso,residenceCountryIso,citizenshipCountryIso,email,landLine,mobile,fax,dob,gender,verified,socialMedia,custom.referrerPartyId
NY Division,1234,2018-09-29T01:10:38.922Z,active,seller,jadams,Acme,false,Attorney,John,Quincy,Adams,,"100 Bush Street, Suite #1710",San Francisco,94104,CA,US,DE,ES,foo.bar@domain.com,,+442012345678,,2019-01-01,m,unverified,['https://www.youtube.com/user/zoobarme','https://www.facebook.com/ZooBarMe/'],1234
Field name Type Size or format Default Description Example values
partyId
(Required)
string 128 null A unique identifier for the party 1234
partyCreated
(Required)
string ISO8601 Zulu null Date and time when the user signed up 2019-09-04T04:16:28.138Z
userName string 255 null Customer-specific user name jadams
partyModified string ISO8601 Zulu Jumio's internal modified field Date and time when the user was modified. If you do not provide this field, Beam's internal modified field value is used. 2019-09-04T04:16:28.138Z
group string 128 Name of customer A predefined group name. Grouping allows you to divide your data set into customer-specific groups, divisions, or departments so that rules (and subsequently monitoring) can be applied to certain groups. The available group names are specific to your company. If you specify a group name that is not on the preconfigured list, this field will default to your company name. See also Filter fields. HQ, NY Office, SF Division
type string 128 null Identifies the party type so that rules can target specific types of parties. See also Filter fields. High Net Worth, Foreign
code string 128 null Similar to type, but the value is a code instead of words to identify the party. See also Filter fields. 0101SDU
category string 128 null Similar to type, this value identifies the party category to enable rules to target specific categories of parties. See also Filter fields. Employee, Customer
role string 255 TBD If not supplied, Jumio will determine the default based on the customer-defined default and (if desired) transaction direction, e.g., pay in vs. pay out. This value cannot be overridden by API call after it is initially set. Sender, Receiver, Both
correlation object 4096 null JSON object containing one or more key-value pairs that will link together the parties that you want to monitor as a single entity. For example, if a party has driver's licenses in two different states, you could specify both of those licenses so that if there's another party with one or both of those same licenses in its correlation field, those two parties will be treated as the same party during monitoring and detection. "correlation": {
  "ca_dl": "a1b2c34d",
  "nv_dl": "z1y2x3wd"
}
accountId string 128 null Adds the party to an existing account that is already owned by another party. 1234
merchantName string 255 null If the party is a business, the business name Jumio
business boolean FALSE Indicates whether this is a business true, false
occupation string 255 null Occupation or type of business Attorney
firstName string 128 null The party's first name John
middleName string 128 null The party's middle name Quincy
lastName string 128 null The party's last name Adams
fullName string 384 TBD Some customers only have full name. If fullName is null, Jumio will autopopulate it by concatenating first, middle, and last name John Quincy Adams
address string 512 null 847 Sansome Street
city string 255 null San Francisco
postal string 12 null 94111
stateIso string ISO3166-2 null The party's state CA
countryIso string ISO3166-1 null The party's country US
residenceCountryIso string ISO3166-1 null The party's country of residence DE
citizenshipCountryIso string ISO3166-1 null The party's country of citizenship ES
email string 255 null The party's email address foo.bar@domain.com
landline string 20 null The party's landline phone number +16694352341
mobile string 20 null The party's mobile phone number +16694352341
fax string 20 null The party's fax number +16694352341
dob string ISO8601 Zulu null Date of birth in format YYYY-MM-DD 2019-01-01
gender string 1 null The party's gender m, f
socialMedia array 1024 null Links to social media or websites https://www.linkedin/zoobarme
verified string 128 null Customer-specific interpretation of whether the party is verified. Jumio may also leverage this value for the customer verification process. unverified, pending, verified
status string 128 null Customer-specific party status active, suspended, closed
geoCode.ipAddress string 50 null The geoCode fields allow you to specify the party's location. The IP address can be IPv4 or IPv6. 64.79.119.82
2001:0db8:85a3:0000:...
geoCode.geoPoint
.latitude
number 3,7 null The latitude coordinate 37.5305464
geoCode.geoPoint
.longitude
number 3,7 null The longitude coordinate -122.0818591
geoCode.city string 255 null The city San Francisco
geoCode.postal string 12 null The postal code 94111
geoCode.stateIso string ISO3166-2 null The state CA
geoCode.countryIso string ISO3166-1 null The country US
custom object 4096 null JSON object to support customer-specific fields {
  "referrerPartyId": "1234"
}

Success HTTP status response code

201 (Successfully posted party)

Update a party

Update specific fields in a party like this:

curl -X PATCH $BASE_PATH/model/v1/parties/1234 -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "email": mynewemailaccount@gmail.com
}'
import requests
headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}
data = {
  "email": {
    "value": mynewemailaccount@gmail.com
  }
}
response = requests.patch('{}/model/v1/parties/1234'.format(base_path), headers=headers, data=json.dumps(data))

PATCH /parties/:id

This API allows you to update specific party fields. You could also use POST to send updated data for a party, but with POST you must send all of the fields again or the omitted fields will be deleted. With PATCH, you only need to send the field you are updating.

Success HTTP status response code

200 (Successfully updated party)

Get party details

Get party details like this:

curl -X GET $BASE_PATH/model/v1/parties/1234 -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'
import requests

base_path = BASE_PATH
headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/model/v1/parties/1234'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)

The above command returns JSON structured like this:

{
  "partyId":"1234",
  "partyCreated":"2020-02-15T00:53:21.344Z",
  "partyModified":"2020-02-17T23:13:37.855Z",
  "accountIds":[],
  "status":"active",
  "type":null,
  "code":null,
  "category":null,
  "role":"seller",
  "userName":"foobar",
  "merchantName":"Foo Bar",
  "business":true,
  "occupation":"Software Engineer",
  "firstName":"Foo",
  "middleName":"string",
  "lastName":"Bar",
  "fullName":"Foo Bar",
  "address":"100 Bush Street",
  "city":"San Francisco",
  "postal":"94111",
  "stateIso":"CA",
  "countryIso":"US",
  "residenceCountryIso":"US",
  "citizenshipCountryIso":"US",
  "email":"foo.bar@domain.com",
  "landLine":"+16694352341",
  "mobile":"+16694352341",
  "fax":"+16694352341",
  "dob":"2020-02-15",
  "gender":"m",
  "socialMedia":[
    "www.youtube.com/user/fooBarMe"
  ],
  "verified":"unverified",
  "group":"HQ",
  "geoCode":{
    "ipAddress":"64.79.119.82",
    "countryIso":"US",
    "stateIso":"CA",
    "city":"San Francisco",
    "postal":"94105",
    "geoPoint":{
      "latitude":0.0,
      "longitude":0.0
    }
  },
  "custom":{}
}

GET /parties/:id

This API allows you to retrieve details of a specific party. For information on the fields it returns, see Party fields.

Success HTTP status response code

200 (Successfully retrieved party)

Upload party documents

First, upload the metadata:

import requests
import json

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

data = {
  "documentId": "1234",
  "obtained": "2018-09-29",
  "verified": "unverified",
  "type": "Drivers License",
  "group": "Proof of Identity",
  "description": "Description",
  "custom": {}
}

response = requests.post('{}/model/v1/parties/5678/documents'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/model/v1/parties/5678/documents' -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -d '{
  "documentId": "1234",
  "obtained": "2018-09-29",
  "verified": "unverified",
  "type": "Drivers License",
  "group": "Proof of Identity",
  "description": "Description",
  "custom": {}
}'

The above command returns JSON structured like this:

{
  "id": "1234",
  "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/parties/5678/documents/1234",
  "fileUrl": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/parties/5678/documents/1234/file"
}

Next, upload the actual document file, replacing @path/to/local/file with the file's source location:

import requests

headers = {
    'Authorization': 'Bearer $ACCESS_TOKEN',
    'Content-Type': 'multipart/form-data',
}

files = {
    'data': ('path/to/local/file', open('path/to/local/file', 'rb')),
}

response = requests.put('{}/model/v1/parties/5678/documents/1234/file'.format(base_path), headers=headers, files=files)
curl -X PUT $BASE_PATH/model/v1/parties/5678/documents/1234/file -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: multipart/form-data' -F 'data=@path/to/local/file' 

After you have created a party, you can upload documents (such as proof of identity) and associate them with that party. This is a two-step process: first upload metadata about the document, and then upload the document file itself.

Upload the metadata

POST /parties/:id/documents

This API uploads the metadata that describes the document you are going to upload in the next step. In the URL, you pass in the ID of the party that will be linked to the document.

Upload the document file

PUT /parties/:id/documents/:id/file

This API uploads the actual document from the source location you specify. The API URL is the same as the file URL that was returned when you uploaded the metadata in the previous step.

Party document metadata fields

Sample CSV metadata definition:

documentId,obtained,verified,type,group,description
1234,2018-09-29,unverified,Drivers License,Proof of Identity,Description
Field name Type Size or format Default Description Example values
documentId string 128 Autogenerated if not supplied External unique identifier for the document 1234
obtained string ISO8601 Zulu null Date the document was obtained before uploading to Jumio in the format YYYY-MM-DD 2018-09-29
verified string 128 null Information about the document verification unverified, pending, verified
type string 128 null Document type. See also Filter fields. Passport
group string 128 null Document group. See also Filter fields. Proof of Identity
description string 128 null Document description Anything related to the document
custom object 4096 null JSON object to support customer-specific fields {
  "confidential" : true,
  "result: "passed"
}

Success HTTP status response codes

Get party document metadata

To retrieve metadata for all uploaded documents for a given party:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/model/v1/parties/5678/documents'.format(base_path), headers=headers)

# Print response data
print(json_response)
curl -X GET $BASE_PATH/model/v1/parties/5678/documents -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

Sample response:

[
 {
  "documentId": "1234",
  "partyId": "5678",
  "obtained": "2018-09-29",
  "filename": "test.png",
  "type": "Drivers License 1",
  "group": "Proof of Identity",
  "hash": "7959d9f54e0fb54de8dab87ac6aca4d0",
  "description": "Description",
  "custom": {}
 },
 {
   "documentId": "6ee01ad0",
   "partyId": "5678",
   "obtained": "2010-01-01",
   "filename": "test.png",
   "type": "Drivers License 2",
   "group": "Proof of Identity",
   "hash": "54n459f54e0fb54de8dab87ac6aca4d0",
   "description": "Description",
   "custom": {}
 }
]

To retrieve metadata for a specific document:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/model/v1/parties/5678/documents/1234'.format(base_path), headers=headers)

# Print response data
print(json_response)
curl -X GET $BASE_PATH/model/v1/parties/5678/documents/1234 -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

Sample response:

{
 "documentId": "1234",
 "partyId": "5678",
 "obtained": "2018-09-29",
 "filename": "test.png",
 "type": "Drivers License 1",
 "group": "Proof of Identity",
 "hash": "7959d9f54e0fb54de8dab87ac6aca4d0",
 "description": "Description",
 "custom": {}
}

GET /parties/:id/documents
GET /parties/:id/documents/:id

These APIs retrieve the metadata of documents that are linked to the given party. You can retrieve the metadata for all documents linked to this party or just the specified document. For a description of the metadata fields, see Party document metadata fields.

Success HTTP status response code

200 (Successfully retrieved document metadata)

Get a document file

To retrieve a specific document file:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/model/v1/parties/5678/documents/1234/file'.format(base_path), headers=headers)
curl -X GET $BASE_PATH/model/v1/parties/5678/documents/1234/file -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

GET /parties/:id/documents/:id/file

This API retrieves a document file that is linked to a party.

Success HTTP status response code

200 (Successfully retrieved document file)

Create an account

Create an account like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

data = {
  "accountId": "1234",
  "accountCreated": "2018-09-29T01:10:38.922Z",
  "partyIds": [
    "1234",
    "5678"
  ],
  "status": "active",
  "number": "31452624235",
  "type": "remittance",
  "name": "Money Transfer",
  "balance": {
    "currency": "USD",
    "value": 2.99
  },
  "description": "Cash from either ACH or CARD",
  "custom": {}
}

response = requests.post('{}/model/v1/accounts'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/model/v1/accounts -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
   "accountId": "1234",
   "accountCreated": "2018-09-29T01:10:38.922Z",
   "partyIds": [
      "1234",
      "5678"
   ],
   "status": "active",
   "number": "31452624235",
   "type": "remittance",
   "name": "Money Transfer",
   "balance": {
      "currency": "USD",
      "value": 2.99
   },
   "description": "Cash from either ACH or CARD",
   "custom": {}
}'

The POST command returns JSON structured like this:

{
   "id": "1234",
   "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/accounts/1234"
}

POST /accounts

An account is the party's account, such as the account in which the transaction took place or the account your customer is opening at your firm. When you add an account, you must specify the party or parties who own it, so be sure to add the relevant parties with the /parties API before adding the account.

Account fields

Sample CSV account definition:

accountId,accountCreated,partyIds,status,number,type,name,balance.currency,balance.value,description,custom
1234,2018-09-29T01:10:38.922Z,['1234','5678'],active,31452624235,remittance,Money Transfer,USD,2.99,Cash from either ACH or CARD,
Field name Type Size or Format Default Description Example values
accountId
(Required)
string 128 null A unique identifier for the account 12345678
accountCreated
(Required)
string ISO8601 Zulu null Time account was opened 2019-09-04T04:16:28.138Z
partyIds
(Required)
array of strings 128 (each string) null The party or parties that own this account. If specifying more than one party, separate each value with a comma and double quotes and enclose the array in square brackets. The first party in the array will be considered the primary party, so that when a transaction occurs in this account and no party is specified for that transaction, the primary party will be the party linked to that transaction by default. ["1234"] ["1234", "5678"]
type string 128 null Identifies the account type so that rules can target specific types of accounts Checking, Savings, Credit Card
accountModified string ISO8601 Zulu Jumio's internal modified field Time account was modified. If you do not provide this field, Jumio's internal modified field value is used. 2019-09-04T04:16:28.138Z
code string 128 null Similar to type, but the value is a code instead of words to describe the account 0101SDU
category string 128 null Similar to type, this value identifies the account category to enable rules to target specific categories of accounts Joint Checking, Visa
primaryPartyId string 128 partyId If more than one party is specified to own an account, a primary party can be set. It defaults to the first party linked to an account. 5678
correlation object 4096 null JSON object containing one or more key-value pairs that will link together the accounts that you want to monitor as a single entity. "correlation": {
  "field_1": "a1b2c34d",
  "field_2": "z1y2x3wd"
}
number string 128 null Customer-facing account number 75f1fe70-4766-11e8-b871-623ae1d2d5e0
name string 128 null The name of this account Money Transfer
balance.value number 19,4 null Allows you to set the account balance, such as during transaction ingestion. If you are continuously changing the balance, it is recommended to suppress history generation as described in Making fine-grained modifications. 235.412
balance.currency string ISO4217 null If you specify the account balance in a different currency from the account's default currency, enter the currency here USD
referenceBalanceValue number 19,4 balance.value If you specify the account balance in a different currency, also provide the balance in the account's default currency here.
description string 512 null Any descriptive text that is available Sam's checking account, Guitar lessons by Amay
status string 36 null Customer-specific account status active, suspended, closed
geoCode.ipAddress string 50 null The geoCode fields allow you to specify the account's location. The IP address can be IPv4 or IPv6. 64.79.119.82
2001:0db8:85a3:0000:0...
geoCode.geoPoint
.latitude
number 3,7 null The latitude coordinate 37.5305464
geoCode.geoPoint
.longitude
number 3,7 null The longitude coordinate -122.0818591
geoCode.city string 255 null The city
geoCode.postal string 12 null The postal code
geoCode.stateIso string ISO3166-2 null The state
geoCode.countryIso string ISO3166-1 null The country
custom object 4096 null JSON object to support customer-specific fields {
  "referrerPartyId": "1234"
}

Success HTTP status response code

201 (Successfully posted account)

Update an account

Update specific fields in an account like this:

curl -X PATCH $BASE_PATH/model/v1/accounts/1234?history=false -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "balance.value": 12.3
}'
import requests
headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}
data = {
  "balance": {
    "value": 12.3
  }
}
response = requests.patch('{}/model/v1/accounts/1234?history=false'.format(base_path), headers=headers, data=json.dumps(data))

PATCH /accounts/:id

This API allows you to update specific account fields. You could also use POST to send updated data for an account, but with POST you must send all of the fields again or the omitted fields will be deleted. With PATCH, you only need to send the field you are updating. If you are just updating the account balance, you will probably want to suppress a history entry from being created as described in Fine-grained modifications.

Success HTTP status response code

200 (Successfully updated account)

Get account details

Get account details like this:

curl -X GET $BASE_PATH/model/v1/accounts/1234 -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'
import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/model/v1/accounts/1234'.format(base_path), headers=headers)

# Print response data
print(json_response)

The above command returns JSON structured like this:

{
  "accountId": "1234",
  "accountCreated": "2018-09-29T01:10:38.922Z",
  "accountModified":"2020-02-18T20:58:33.349Z",
  "partyIds": ["1234", "5678"]
  "status": "active",
  "number": "31452624235",
  "type": "remittance",
  "code":null,
  "category":null,
  "name": "Money Transfer",
  "balance":{
    "value":2.9900,
    "currency":"USD"
  },  
  "referenceBalanceValue":null,
  "description": "Cash from either ACH or CARD",
  "geoCode":null,
  "custom": {}
}

GET /accounts/:id

This API allows you to retrieve details of a specific account. For information on the fields it returns, see Account fields.

Success HTTP status response code

200 (Successfully retrieved account)

Create a payment source

Create a payment source like this:

# Card
import requests
import json

data = {
  "paymentSourceId": "1111",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "hash": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "issuingCountryIso" : "US",
  "method": "card",
  "methodType": "visa",
  "bin": "123456",
  "last4": "1234"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# ACH option 1
import requests
import json

data = {
  "paymentSourceId": "2222",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "ach",
  "methodType": "checking",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "routingNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# ACH option 2
import requests
import json

data = {
  "paymentSourceId": "3333",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "ach",
  "methodType": "checking",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "routingNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# Cash
import requests
import json

data = {
  "paymentSourceId": "4444",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "cash",
  "methodType": "teller",
  "network": "Metrobank",
  "networkId": "1235",
  "name": "PALAWAN PAWNSHOP - Pawnshop - ALBAY-DARAGA",
  "location": "283 T. Perez St., Daraga, Albay L/M",
  "issuingCountryIso" : "PH"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# Marketplace payment through wallet, e.g., Stripe, Dwolla, Braintree, PayPal, Square
import requests
import json

data = {
  "paymentSourceId": "5555",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "wallet",
  "methodType": "marketplace",
  "network": "Stripe",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# P2P
import requests
import json

data = {
  "paymentSourceId": "6666",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "p2p",
  "methodType": "account",
  "accountId": "1234"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/payment-sources'.format(base_path), headers=headers, data=json.dumps(data))
# Card
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "1111",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "hash": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "issuingCountryIso" : "US",
  "method": "card",
  "methodType": "visa",
  "bin": "123456",
  "last4": "1234"
}'
# ACH option 1
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "2222",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "ach",
  "methodType": "checking",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "routingNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
}'
# ACH option 2
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "3333",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "ach",
  "methodType": "checking",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "routingNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0"
}'
# Cash
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "4444",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "cash",
  "methodType": "teller",
  "network": "Metrobank",
  "networkId": "1235",
  "name": "PALAWAN PAWNSHOP - Pawnshop - ALBAY-DARAGA",
  "location": "283 T. Perez St., Daraga, Albay L/M",
  "issuingCountryIso" : "PH"
}'
# Marketplace payment through wallet, e.g., Stripe, Dwolla, Braintree, PayPal, Square
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "5555",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "wallet",
  "methodType": "marketplace",
  "network": "Stripe",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0"
}'

# P2P
curl -X POST $BASE_PATH/model/v1/payment-sources -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "paymentSourceId": "6666",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "p2p",
  "methodType": "account",
  "accountId": "1234"
}'

The above commands returns JSON structured like this:

{
   "id": "1111",
   "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/payment-sources/1111"
}

POST /payment-sources

A payment source is the instrument used by parties to transfer funds into or out of accounts via transactions. For example, when a buyer uses a credit card to purchase an item from a seller in an online marketplace, that credit card is the payment source that transfers funds between the two marketplace accounts.

Not all accounts and transactions are associated with payment sources. For example, in banking transactions where a debit card is used, there might not be the concept of a payment source in cases where the debit card represents the account itself rather than an external source of funds associated with an account. To learn more about payment sources and whether you need them in your data model, contact your Jumio Solutions Engineer.

Payment source fields

Sample CSV payment source definition:

paymentSourceId,paymentSourceCreated,partyId,status,hash,issuingCountryIso,method,methodType,bin,last4
4567,2018-09-29T01:10:38.922Z,4567,active,75f1fe70-4766-11e8-b871-623ae1d2d5e0,US,card,visa,123456,1234

All payment sources require the following fields:

paymentSourceId, paymentSourceCreated, partyId, method

Additionally, all payment sources require one of the following fields or combinations of fields:

Field name Type Size or Format Default Description Example values
paymentSourceId
(Required)
string 128 null A unique identifier for the payment source 12345678
paymentSourceCreated
(Required)
string ISO8601 Zulu null Time the payment source was added 2019-09-04T04:16:28.138Z
partyId
(Required)
string 128 null Party owning this payment source 1234
method string 128 null Customer-specific payment method card, ach, cash, wallet, p2p
paymentSourceModified string ISO8601 Zulu Jumio's internal modified field Time the payment source was modified. If you do not provide this field, Jumio's internal modified field value is used. 2019-09-04T04:16:28.138Z
methodType string 128 null Further identifies the method to enable rules to target specific types of payment sources visa, master, checking, savings, teller, marketplace
type string 128 null Identifies the payment source type so that rules can target specific types of payment sources travel rewards card
code string 128 null Similar to type, but the value is a code instead of words to describe the payment source
category string 128 null Similar to type, this value identifies the payment source category to enable rules to target specific categories of payment sources personal, corporate
hash string 128 null A unique value that should allow you to identify duplicates
issuingCountryIso string ISO3166-1 null Issuing country US
bin string 6 null Credit card bin code
last4 string 4 null Last four digits of bank account or credit card number
accountNumber string 128 null Bank account or credit card number
routingNumber string 128 null Bank account routing number
name string 255 null Any descriptive name, e.g., the name of the business offering cash pickup PALAWAN PAWNSHOP - Pawnshop - ALBAY-DARAGA
network string 128 null Payout network Metrobank, Stripe, Dwolla, Braintree, PayPal, Square
networkId string 128 null Payout network ID if applicable
location string 255 null E.g., address of cash pickup 283 T. Perez St., Daraga, Albay L/M
accountId string 128 null Can be used to link Jumio accounts. Usually used to support P2P intra payments. Can also be used to support bank model to link cards to accounts.
correlation object 4096 null JSON object containing one or more key-value pairs that will link together the payment sources that you want to monitor as a single entity. "correlation": {
  "field_1": "a1b2c34d",
  "field_2": "z1y2x3wd"
}
status string 128 null Customer-specific payment source status active, suspended, closed
geoCode.ipAddress string 50 null The geoCode fields allow you to specify the payment source's location. The IP address can be IPv4 or IPv6. 64.79.119.82 2001:0db8:85a3:0000:...
geoCode.geoPoint
.latitude
number 3,7 null The latitude coordinate 37.5305464
geoCode.geoPoint
.longitude
number 3,7 null The longitude coordinate -122.0818591
geoCode.city string 255 null The city
geoCode.postal string 12 null The postal code
geoCode.stateIso string ISO3166-2 null The state
geoCode.countryIso string ISO3166-1 null The country
custom object 4096 null JSON object to support customer-specific fields

Success HTTP status response code

201 (Successfully posted payment source)

Update a payment source

Update specific fields in a payment source like this:

curl -X PATCH $BASE_PATH/model/v1/payment-sources/1234 -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "status": suspended
}'
import requests
headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}
data = {
  "status": "suspended"
}

response = requests.patch('{}/model/v1/payment-sources/1234'.format(base_path), headers=headers, data=json.dumps(data))

PATCH /payment-sources/:id

This API allows you to update specific payment source fields. You could also use POST to send updated data for a payment, but with POST you must send all of the fields again or the omitted fields will be deleted. With PATCH, you only need to send the field you are updating.

Success HTTP status response code

200 (Successfully updated payment source)

Get payment source details

Get payment source details like this:

curl -X GET $BASE_PATH/model/v1/payment-sources/1111 -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'
import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/model/v1/payment-sources/1111', headers=headers)

# Print response data
print(json_response)

The above command returns JSON structured like this:

{
  "paymentSourceId": "1111",
  "paymentSourceCreated": "2018-09-29T01:10:38.922Z",
  "partyId": "1234",
  "status": "active",
  "method": "ach",
  "methodType": "checking",
  "accountNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "routingNumber": "75f1fe70-4766-11e8-b871-623ae1d2d5e0"
}

GET /payment-sources/:id

This API allows you to retrieve details of a specific payment source. For information on the fields it returns, see Payment source fields.

Success HTTP status response code

200 (Successfully retrieved payment source)

Create a transaction

Create a transaction like this:

# Service payment

import requests
import json

data = {
  "transactionId": "1111",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "funded",
  "type": "cash",
  "amount": {
    "value": 4152,
    "currency": "USD"
  },
  "payDirection": "IN",
  "paymentSourceId": "1111"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/transactions'.format(base_path), headers=headers, data=json.dumps(data))
# MSB transfer

import requests
import json

data = {
  "transactionId": "2222",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "disbursed",
  "type": "cash",
  "amount": {
    "value": 123.54,
    "currency": "USD"
  },
  "payDirection": "OUT",
  "paymentSourceId": "1111"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/transactions'.format(base_path), headers=headers, data=json.dumps(data))
# Bank deposit

import requests
import json

data = {
  "transactionId": "3333",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "completed",
  "amount": {
    "value": 1345,
    "currency": "USD"
  },
  "type": "Deposit",
  "category": "Payroll",
  "payDirection": "IN",
  "description": "Insperity"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/transactions'.format(base_path), headers=headers, data=json.dumps(data))
# P2P

import requests
import json

data = {
  "transactionId": "4444",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "amount": {
    "value": 123.54,
    "currency": "USD"
  },
  "type": "intra-network",
  "payDirection": "OUT",
  "paymentSourceId": "1111",
  "correlation": {
    "counterTransactionLinkingId": "CS5678"
  }
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/model/v1/transactions'.format(base_path), headers=headers, data=json.dumps(data))
# Service payment
curl -X POST $BASE_PATH/model/v1/transactions -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "transactionId": "1111",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "funded",
  "type": "cash",
  "amount": {
    "value": 4152,
    "currency": "USD"
  },
  "payDirection": "IN",
  "paymentSourceId": "1111"
}'
# MSB transfer
curl -X POST $BASE_PATH/model/v1/transactions -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type:�application/json" -d '{
  "transactionId": "2222",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "disbursed",
  "type": "cash",
  "amount": {
    "value": 123.54,
    "currency": "USD"
  },
  "payDirection": "OUT",
  "paymentSourceId": "1111"
}'
# Bank deposit
curl -X POST $BASE_PATH/model/v1/transactions -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "transactionId": "3333",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "completed",
  "amount": {
    "value": 1345,
    "currency": "USD"
  },
  "type": "Deposit",
  "category": "Payroll",
  "payDirection": "IN",
  "description": "Insperity"
}'
# P2P
curl -X POST $BASE_PATH/model/v1/transactions -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "transactionId": "4444",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "amount": {
    "value": 123.54,
    "currency": "USD"
  },
  "type": "intra-network",
  "payDirection": "OUT",
  "paymentSourceId": "1111",
  "correlation": {
    "counterTransactionLinkingId": "CS5678"
  }
}'

Change the status like this:

curl -X PUT $BASE_PATH/model/v1/transactions/1111?status=pending -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"
import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.put('{}/model/v1/transactions/1111?status=pending'.format(base_path), headers=headers)

The POST commands return JSON structured like this:

{
   "id": "4567",
   "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/transactions/4567"
}

POST /transactions

A transaction represents an exchange of money into or out of an account. A transaction can optionally specify the payment source, such as the credit card that was used to provide the funds.

Updating the transaction status

To update a transaction's status, use /transactions/:transactionId?status=:status, where :status is the new status you want to set for the transaction. The API can be configured to accept only predefined status values and further ensure that the status moves forward in a predefined status order. In addition, you can configure a status to trigger monitoring. For example, you can define the valid transaction status values as status = { initiated, pending, created } and specify that created will trigger monitoring for transactions with that status. For assistance with these configurations, please contact your Jumio Solutions Engineer.

Transaction fields

Sample CSV transaction definition:

transactionId,transactionCreated,accountId,status,type,amount.value,amount.currency,payDirection,paymentSourceId
1234,2018-09-29T01:10:38.922Z,1234,funded,cash,4152,USD,in,12345
Field name Type Size or Format Default Description Example values
transactionId
(Required)
string 128 null Unique identifier of the transaction 1234
transactionCreated
(Required)
string ISO8601 Zulu null Time when the transaction occurred 2018-09-29T01:10:38.922Z
accountId string 128 null Account against which the transaction is processed. This field is required unless your environment is configured to allow accountless transactions, in which case you can specify the partyId instead of the accountId. If accountless transactions are disabled in your environment, you must always specify the accountId.
amount.value
(Required)
positive number 19,4 null Price, or in some cases minimum price, e.g., $1000 membership. Always enter a positive number and use the payDirection field to indicate whether the amount is paid into or out of the account. 23.4565, 2.5
amount.currency string ISO4217 USD Currency of the base price USD, BYC
exchangeRate number 19,4 1 Reference exchange rate against internal base currency (such as USD). Provide either the exchangeRate or the referenceAmountValue but not both. 0.54
referenceAmountValue number 19,4 amount.value Reference amount using internal base currency. Provide either the exchangeRate or the referenceAmountValue but not both. 23.453
payDirection
(Required)
string 128 null Whether the payment source used for this transaction is paying in ("IN") or paying out ("OUT") to/from the account IN, OUT
type string 128 null Describes the type of transaction. For example, a payroll autodeposit could have the category Payroll and the type Deposit. This enables rules to target specific types of transactions. Cash, Check, Bill Pay, Deposit, Withdrawal
code string 128 null Similar to type, but the value is a code instead of words to describe the transaction 0101SDU
category string 128 null Similar to type, this value identifies the transaction category to enable rules to target specific categories of transactions Payroll, Utility
transactionModified string ISO8601 Zulu Jumio's internal modified field Time when the transaction status was modified. If you do not provide this field, Jumio's internal modified field value is used. 2018-09-29T01:10:38.922Z
processor string 128 null In cases where multiple payment processors are available, this field identifies the entity that processed the payment in this transaction Wells Fargo
invoiceNumber string 128 null Customer-facing invoice number B1235676
correlation object 4096 null JSON object containing one or more key-value pairs that will link related transactions that you want to treat as a single transaction during monitoring and detection. If you have a pay in/pay out pair of transactions you want to treat as a single transaction, use the key counterTransactionLinkingId in the second transaction to specify the ID of the first transaction in the pair (the pay direction of each is determined by the payDirection field). "correlation": {
  "counterTransactionLinkingId": "1234"
}
status string 128 null Customer-specific transaction status. This can be free-form or pre-configured to enforce valid values and order. created, pending, settled, failed
paymentSourceId string 128 null Payment source, if any, used to pay into or out of account
partyId string 128 primary party of account Party that authorized the transaction. By default, the primary party on the account is used. If accountless transactions are enabled in your environment and you do not specify the accountId, you must specify the partyId explicitly.
description string 512 null Any descriptive text that is available Insperity, Verizon #13415
geoCode.ipAddress string 50 null The geoCode fields allow you to specify the transaction's location. The IP address can be IPv4 or IPv6. 64.79.119.82 2001:0db8:85a3:0000:...
geoCode.geoPoint
.latitude
number 3,7 null The latitude coordinate 37.5305464
geoCode.geoPoint
.longitude
number 3,7 null The longitude coordinate -122.0818591
geoCode.city string 255 null The city
geoCode.postal string 12 null The postal code
geoCode.stateIso string ISO3166-2 null The state
geoCode.countryIso string ISO3166-1 null The country
custom object 4096 null JSON object to support customer-specific fields

Success HTTP status response code

201 (Successfully posted transaction)

Get transaction details

Get transaction details like this:

curl -X GET $BASE_PATH/model/v1/transactions/1111 -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'
import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/model/v1/transactions/1111'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)

The above command returns JSON structured like this:

{
  "transactionId": "1234",
  "transactionCreated": "2018-09-29T01:10:38.922Z",
  "accountId": "1234",
  "status": "funded",
  "amount": {
    "value": 4152,
    "currency": "USD"
  },
  "payDirection": "IN",
  "paymentSourceId": "12345"
}

GET /transactions/:id

This API allows you to retrieve details of a specific transaction. For information on the fields it returns, see Transaction fields.

Success HTTP status response code

200 (Successfully retrieved transaction)

Create a footprint

Create a footprint like this:

import requests
import json

data = {
  "footprintCreated": "2018-04-29T18:33:45.661Z",
  "source": "custom",
  "sourceContextId": "4321",
  "context": "PARTY",
  "contextId": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "event": "create-user",
  "type": "geo",
  "format": "json",
  "description": "User created",
  "data": {
    "ipAddress": "127.0.0.1",
    "userAgent": "Mozilla, rewrwer24234",
    "sessionId": "315b99069b631b427b0c0feaea20e8154e576c9f3447c88582694f9e6ed5a3fb"
  }
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}
response = requests.post('{}/model/v1/footprints'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/model/v1/footprints -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "footprintCreated": "2018-04-29T18:33:45.661Z",
  "source": "custom",
  "sourceContextId": "4321",
  "context": "PARTY",
  "contextId": "75f1fe70-4766-11e8-b871-623ae1d2d5e0",
  "event": "create-user",
  "type": "geo",
  "format": "json",
  "description": "User created",
  "data": {
    "ipAddress": "127.0.0.1",
    "userAgent": "Mozilla, rewrwer24234",
    "sessionId": "315b99069b631b427b0c0feaea20e8154e576c9f3447c88582694f9e6ed5a3fb"
  }
}'

POST /footprints

A footprint is an event or insight at a particular point in time, typically tracked through a party. An example is an IP address and session ID from a login event, a risk score imported from a third-party vendor, or a match from a watchlist. Footprints provide additional intelligence that can be used as data points in rules and can enhance monitoring and detection.

Footprint fields

Sample CSV footprint definition:

footprintCreated,source,sourceContextId,context,contextId,event,type,format,description,data.ipAddress,data.userAgent,data.sessionId
2018-04-29T18:33:45.661Z,custom,4321,party,75f1fe70-4766-11e8-b871-623ae1d2d5e0,create-user,geo,json,,127.0.0.1,"Mozilla, rewrwer24234",315b99069b631b427b0c0feaea20e8154e576c9f3447c88582694f9e6ed5a3fb
Field name Type Size or Format Default Description Example values
footprintCreated
(Required)
string ISO8601 Zulu null Time when footprint event was taken 2019-09-04T04:16:28.138Z
source
(Required)
string 128 null The data source where the footprint came from. Could be custom or a third-party vendor. MaxMind
context
(Required)
string 128 null The context for which this footprint was created PAYMENT_SOURCE, ACCOUNT, PARTY, TRANSACTION
sourceContextId
(Required)
string 128 null The ID for the context entity, such as the party ID if the context is PARTY 1234
event
(Required)
string 128 null The name of the actual event. Used to hold third-party integration name if applicable. This is case-insensitive. IDology, create-account
data
(Required)
object TBD null The actual footprint data sent to Jumio. The size will be determined as part of the integration. {
  "ipAddress":
  "127.0.0.1",
  "isp": "Verizon",
  "country": "US"
}
group string 128 Name of customer Grouping allows you to divide the data set into customer-specific groups, divisions, or departments. With this concept, rules (and subsequently monitoring) can be applied to certain groups. HQ, NY Office, SF Division
type string 128 null Further classifies the event to enable rules to target specific types of footprints minFraud, geoIp
format string 128 json The format of the actual data json, xml
description string 512 null Can be used to provide additional information if desired 127.0.0.1

Success HTTP status response code

204 (Successfully posted footprint)

Advanced topics

Linking entities

Parties, accounts, payment sources, and transactions support a correlation object that allows you to specify key-value pairs that link those entities together so that they are treated as a single entity during monitoring and detection. For example, if a party has driver's licenses in two different states, you could specify both of those licenses so that if there's another party with one or both of those same licenses in its correlation object, those two parties will be treated as the same party during monitoring and detection. This object uses OR logic, so if another entity has ANY of the same key-value pairs as the current entity, they will be linked.

In transactions, the correlation object also supports the reserved key counterTransactionLinkingId, which allows you to connect a pair of pay in/pay out transactions that make up a single transaction (the pay direction of each is determined by the payDirection field). To use this key, set counterTransactionLinkingId in the second transaction to the ID of the first transaction. Jumio will then automatically populate the counterTransactionLinkingId in the first transaction with the ID of the second transaction in the pair.

For example, if a money transfer is made up of a debit transaction and a credit transaction, the debit transaction is created first, followed by the credit transaction. When the credit transaction is created, the debit transaction's ID is known because the debit transaction was created first, so you can populate the credit transaction's counterTransactionLinkingId with the debit transaction's ID. When Jumio sees the debit's ID specified in the credit's counterTransactionLinkingId, it goes to that debit transaction and populates its own counterTransactionLinkingId with the credit transaction's ID so that the two transactions now point to each other through the counterTransactionLinkingId key. In other words, the flow works like this:

  1. Create debit transaction.
  2. Create credit transaction and populate its counterTransactionLinkingId key with the debit transaction's ID.
  3. Jumio populates the debit transaction's counterTransactionLinkingId key with the credit transaction's ID.

Note that you should only use the correlation object to treat two entities as the same entity. If you want to group similar entities together, see Filter fields below.

Filter fields

When you create rules, you will want to target specific types of parties, transactions, etc. For example, the aggregated data field TM_REFERENCE_TOTAL_AMOUNT_TRANSACTIONS_CASH_GT_10000_OUT_LAST_7_DAYS applies only to cash transactions and ignores non-cash transactions. To enable rules to perform this filtering, there are special fields you can populate on parties, accounts, transactions, and payment sources:

For details on which of these filter fields are available for the different types of objects and how to populate them, see the field descriptions for each API in the How to... section.

You can also map multiple values to a single value to simplify filtering. For example, if you want a particular rule to monitor quasi-cash transactions, you could map the values "gift card", "money order", and "check" to "QUASI_CASH" and then just specify "QUASI_CASH" in the rule to pick up transactions with any of those three types. For assistance with creating the mapping configuration, please contact your Jumio Solutions Engineer.

Custom objects

All APIs other than /footprints support a "custom" object in which you can supply any additional data fields you want to include in the profile of a party, account, etc. For example, if you want to include a custom ID when you create a party, you could specify it like this:

"custom": {
  "referrerPartyId": "1234"
}


You can also use the custom object on parties to encrypt sensitive data.

Note that custom objects represent static data that describes the entity, whereas footprints represent events and insights that change over time.

Encrypting sensitive data

When creating a party, you can use the party's custom object to send sensitive data such as social security numbers to Jumio. To instruct Jumio to encrypt a field inside the custom object, name the field in camel case and append it with BeamEncrypted, e.g., fullSsnBeamEncrypted. Jumio encrypts fields that follow this naming convention inside the custom object before saving them to the database. Note that encrypted fields will not be retrieved when you get a party's details.

Multicurrency

When you update the balance of an account, if it's in a different currency from the default currency in your Jumio instance, you must specify the currency using the balance.currency field and also specify the account balance in your system's default currency so that rules can be applied correctly. For example, if your default currency is USD, and you want to update the balance of a German account, you would specify the account balance in euros using the balance.value and balance.currency fields and set the referenceBalanceBalance field to the account balance in USD.

Similarly, if a transaction is in a foreign currency, you would use the amount.value and amount.currency fields to specify the transaction amount. You would then either specify the amount in the default currency using the referenceAmountValue field, or you could specify the exchange rate in the exchangeRate field to have Jumio automatically calculate the default currency value for you.

Geolocation

Jumio data objects include geoCode fields that can contain data about the object's location. These fields are helpful for tracking changes in a party's movement over time and for creating rules that flag activity based on the location, such as when a party's address is in New York but their IP address is in Paris during one transaction and is in London ten minutes later.

If you want to enhance your geoCode location data, such as creating coordinates from a party's IP address, we can use services like MaxMind to generate coordinates for you based on the data you provide. We can also automatically populate the city, state, postal code, and country from the latitude/longitude coordinates you provide. If you would like to enable these features, please contact your Jumio Solutions Engineer.

Fine-grained modifications

Parties, accounts, and payment sources create history entries for every true data change. For fine-grained data modifications, you can use PATCH instead of POST, and you can supply a parameter to suppress history entries, e.g., PATCH /accounts/1234?history=false

An example use case is updating the account balance whenever a new transaction is added. You probably don't need to create a history entry for each balance update, so in this case you would use PATCH with history set to false.

Ingesting historical data

We recommend that you upload at least 12 months of historical data before you start using Jumio. You can use the Data Ingestion API to ingest historical data prior to activating the live data pipeline. If your historical data is too large for API ingestion or is stored in a different format (such as CSV) from the current data that will be fed through the API, you can use File-based data ingestion instead.

File-based data ingestion

This example shows how to verify your connection to the SFTP server using an SFTP command line interface on Linux. Replace USER_ID with the user ID that Jumio sent you.

$ sftp -i ~/.ssh/user_key.pem USER_ID@sftp.beamtechnology.com
Connected to sftp.beamtechnology.com.
sftp> exit

In addition to the Data Ingestion API, Jumio provides an SFTP data ingestion server that allows you to send your data as CSV files to Jumio. Many customers use SFTP to send their historical data as CSV files when they are first bootstrapping Jumio, and then they use the Data Ingestion API for real-time data ingestion after that. Other customers, however, do not require real-time integration and prefer to continue using SFTP to send their data in daily batch files. And some customers prefer to use the Data Ingestion API for both bootstrapping and ongoing data ingestion. You can mix and match the API and file-based approach to suit your needs. Note that if you need to upload footprint data, you must use the Data Ingestion API.

Using the SFTP server, you transfer the data directly into your private, encrypted object storage space in our secure cloud on Amazon AWS. If you do not want to use direct file transfer, Jumio can accept an encrypted hard drive of data and will upload it into the Jumio platform for you; for more information, contact your Jumio Solutions Engineer.

Data dependencies

When you upload your data, Jumio must process your data in a specific order because of dependencies among the different objects. For example, an account must be linked to an existing party, so if there's a problem processing your party data, Jumio cannot process your account data until the party data is fixed.

Setup

To get started with direct file transfer, provide your Jumio Solutions Engineer with the following information:

After receiving this information, Jumio will set up your SFTP account and give you your account name (e.g., acme@sftp.beamtechnology.com). You can then use any SFTP client to connect and upload your data.

File format

Sample CSV file:

accountId,accountCreated,partyIds,status,number,type,name,balance.currency,balance.value,description,custom
1234,2018-09-29T01:10:38.922Z,['1234','5678'],active,31452624235,remittance,Money Transfer,USD,2.99,Cash from either ACH or CARD,

Your CSV files must adhere to these conventions:

To see examples of CSV files for each type of entity, go to the field descriptions in the Data Ingestion API topics above. For instance, go to Party fields to see an example of a party object defined in a CSV file (the CSV appears in the example pane to the right of the field descriptions, below the other examples). The headers and data types to be included in the CSV files are exactly the same as specified in the Data Ingestion API topics.

File naming and locations

When you create your CSV files, you must follow specific syntax for their names and locations. The directory structure allows Jumio to determine the type of data the file contains as well as its status. The structure and syntax must be as follows:

ingestion/uploaded/{YYYY-MM-DD}/{YYYY-MM-DD-HH-MM-SS}_{ENTITY_TYPE}.csv

The date directory {YYYY-MM-DD} denotes the batch day that the data is a part of. The datetime at the beginning of the CSV file name {YYYY-MM-DD-HH-MM-SS} denotes when the file was created. This is meant for tracking purposes if multiple files need to be uploaded for the same day's batch in case of failures.

For example:

ingestion/uploaded/2020-03-31/2020-03-31-09-22-36_parties.csv

The timestamp information in the filename should reflect the approximate time when the file is going to be uploaded. It does not have to be exact; it is simply a way to differentiate between files in case you need to upload a revised version of it later in that same batch.

Upload process

This example shows how customer Acme would connect to the Jumio file server and upload data. They use the ls command to check the contents of the remote server and the lls command to check the contents of the local server. The 2020_03_30 folder on the local server contains the four data files they want to upload, so they use the mput command to upload this folder and its files. After verifying that the folder uploaded successfully, Acme uploads the UPLOAD_COMPLETED file, which triggers the batch processing.

$ sftp -i ~/.ssh/user_key.pem acme@sftp.beamtechnology.com
Connected to sftp.beamtechnology.com.
sftp> pwd
Remote working directory: /sftp-acme-beamtechnology-com
sftp> cd ingestion/uploaded
sftp> pwd
Remote working directory: /sftp-acme-beamtechnology-com/ingestion/uploaded
sftp> ls
2020-03-29
sftp> lls
2020-03-29  2020-03-30 UPLOAD_COMPLETED
sftp> mput -r 2020-03-30
Uploading 2020-03-30/ to /sftp-acme-beamtechnology-com/ingestion/uploaded/2020-03-30
Entering 2020-03-30/
2020-03-30/2020-03-30-15-10-10_payment_sources.csv                                                                                                                                                    100%  474   305.4KB/s   00:00
2020-03-30/2020-03-30-10-10-01_parties.csv                                                                                                                                                            100%  474   331.0KB/s   00:00
2020-03-30/2020-03-30-15-40-01_accounts.csv                                                                                                                                                           100%  474   334.1KB/s   00:00
2020-03-30/2020-03-30-15-33-01_transactions.csv
sftp> ls
2020-03-29  2020_03_30
sftp> mput UPLOAD_COMPLETED 2020-03-30
Uploading UPLOAD_COMPLETED to /sftp-acme-beamtechnology-com/ingestion/uploaded/2020-03-30/UPLOAD_COMPLETED
UPLOAD_COMPLETED
sftp> ls 2020-03-30
2020-03-30/2020-03-30-10-10-01_parties.csv   2020-03-30/2020-03-30-15-10-10_payment_sources.csv        
2020-03-30/2020-03-30-15-33-01_transactions.csv   2020-03-30/2020-03-30-15-40-01_accounts.csv
2020-03-30/UPLOAD_COMPLETED
sftp> exit

This section describes the process for sending daily batches of data to Jumio via SFTP and how to handle any failures that may occur. The general workflow looks like this: alt text

  1. Each day, send four CSV files containing your parties, accounts, payment sources, and transactions using the naming conventions described in the previous section.
  2. If a file fails as it is being uploaded, the entire file will be rejected, and the SFTP server will send a notification that the file failed to upload. Try to upload the file again.
  3. Once the files are all uploaded successfully, send a 0-byte status file named UPLOAD_COMPLETED (e.g., ingestion/uploaded/2020-03-31/UPLOAD_COMPLETED) to indicate that this batch load is complete.
  4. The Jumio server will now begin processing the files in the following order: parties, accounts, payment sources, and transactions. After processing is complete, the files are moved to an ingestion/processed/ directory.
  5. Go to AWS and check your ingestion folder to make sure the data was all processed correctly:
    • If the processing was successful, the system renames UPLOAD_COMPLETED to PROCESSING_SUCCEEDED and moves the uploaded CSV files to the ingestion/succeeded/{YYYY-MM-DD}/ folder.
    • If any records failed to be ingested, the system renames UPLOAD_COMPLETED to PROCESSING_FAILED and creates files corresponding to each failed CSV file under ingestion/failed/{YYYY-MM-DD}. These files contain only the rows that failed to load. There will also be a failure response file describing the failure for each record in the corresponding CSV file. If a CSV could not be read at all because the file is corrupted or formatted improperly, the system creates a text file instead of a CSV that describes the error.
  6. Correct all failed records in the ingestion/failed/{YYYY-MM-DD} folder, rename them with a later datetime ({YYYY-MM-DD-HH-MM-SS}) than the original filename, and then upload them to the same ingestion/uploaded/{YYYY-MM-DD} folder where you originally sent this batch. Make sure these correct files only contain the rows that failed. Do not upload data that was already successfully processed in this batch.
  7. After the corrected files are all uploaded successfully, send a 0-byte status file named UPLOAD_COMPLETED again.
  8. Verify that UPLOAD_COMPLETED has been renamed to PROCESSING_SUCCEEDED and that no new files have been created under the ingestion/failed folder. If there are new failures, repeat the last two steps to correct them.
  9. Optionally, verify that the new data is available by searching for one or two of the new records in the Data Explorer or by sending GET commands from the Data Ingestion API. For example, you might retrieve one or two transactions and also make sure their related parties and accounts are correct.

Example

Sample directory structure:

ingestion/
├── failed
│   └── 2020-03-30
│       └── 2020-03-30-10-49-16_accounts.csv
├── processed
│   ├── 2020-03-29
│   │   ├── 2020-03-29-09-15-40_parties.csv
│   │   ├── 2020-03-29-11-03-53_accounts.csv
│   │   ├── 2020-03-29-12-02-00_payment_sources.csv
│   │   └── 2020-03-29-15-33-01_transactions.csv
│   └── 2020-03-30
│       ├── 2020-03-30-09-18-32_parties.csv
│       └── 2020-03-30-10-49-16_accounts.csv
├── succeeded
│   ├── 2020-03-29
│   │   ├── 2020-03-29-09-15-40_parties.csv
│   │   ├── 2020-03-29-11-03-53_accounts.csv
│   │   ├── 2020-03-29-12-02-00_payment_sources.csv
│   │   └── 2020-03-29-15-33-01_transactions.csv
│   └── 2020-03-30
│       ├── 2020-03-30-09-18-32_parties.csv
│       └── 2020-03-30-10-49-16_accounts.csv
└── uploaded
    ├── 2020-03-29
    │   └── PROCESSING_SUCCEEDED
    ├── 2020-03-30
    │   ├── 2020-03-30-11-33-59_payment_sources.csv
    │   ├── 2020-03-31-13-45-45_transactions.csv
    │   └── PROCESSING_FAILED
    └── 2020-03-31
        ├── 2020-03-31-09-22-36_parties.csv
        ├── 2020-03-31-10-03-33_accounts.csv
        ├── 2020-03-31-11-25-10_payment_sources.csv
        ├── 2020-03-31-13-26-43_transactions.csv
        └── UPLOAD_COMPLETED

The example directory structure on the right illustrates the results of the following scenario:

  1. Data is loaded over the course of three days from March 29 to March 31, 2020.
  2. Data on March 29, 2020 is all successfully processed, and all uploaded files are moved from uploaded to processed with the successfully loaded data also written to the succeeded directory. The UPLOAD_COMPLETED status file in the uploaded directory is replaced with a PROCESSING_SUCCEEDED file to reflect this state.
  3. Party data on March 30, 2020 is all successfully processed, but some account records fail to process. Party and account files are moved from the uploaded directory to processed, as they have both been processed. Files representing the accounts file are created under both the succeeded and failed directories and contain the account records that succeeded and failed processing respectively. The payment source and transaction files remain in the uploaded directory, because processing halted when the account processing failed. The UPLOAD_COMPLETED status file in the uploaded directory is replaced with a PROCESSING_FAILED file to reflect this state.
  4. Data on March 31, 2020 was loaded to the server successfully and ready for processing, but processing for this data will not begin until all previously loaded data is fixed and processed.

Investigator API

Quick reference

After you gain access to the Investigator API, you can use the following endpoints to create and retrieve Jumio Investigation Manager objects. For information on the full path to each endpoint, see Base paths.

Endpoint Description
POST /cases Create a case
GET /cases/:id Get information on a case
GET /monitoring-results/parties/:id Get party monitoring results
GET /monitoring-results/transactions/:id Get transaction monitoring results

Overview

The Investigator API is a public REST API that allows you to work with cases and monitoring results from your code. The API sends requests securely via SSL through a proxy URL to the internal services, which process the request and send the response back through through the proxy URL to the public API, which returns the response to the caller. The API uses OAuth 2.0 to secure API access.

How to...

These sections describe the APIs in detail and provide examples.

Create a case

Create a case like this:

import requests
import json

data = {
  "source": "SalesForce",
  "category": "Money Laundering",
  "description": "",
  "parties": [
    {
      "id": "1234",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "accounts": [
    {
      "id": "5678",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "paymentSources": [
    {
      "id": "9876",
    }
  ],
  "transactions": [
    {
      "id": "4321",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ]
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/investigator/v1/cases'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/investigator/v1/cases -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -d '{
  "source": "SalesForce",
  "category": "Money Laundering",
  "description": "",
  "parties": [
    {
      "id": "1234",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "accounts": [
    {
      "id": "5678",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "paymentSources": [
    {
      "id": "9876",
    }
  ],
  "transactions": [
    {
      "id": "4321",
      "labels": [
        "TF",
        "AML"
      ]
    }
  ]
}'

The command returns JSON structured like this:

{
   "id": "446dd380-5236-11e8-8d2b-8c8590c29eaa",
   "url": "https://CUSTOMER.api.beamtechnology.com:8888/investigator/v1/cases/446dd380-5236-11e8-8d2b-8c8590c29eaa"
}

POST /cases

This API allows you to create a case using the details you specify in the request body.

Fields

Success HTTP status response code

201 (Successfully created case)

Get information on a case

Get information on a case like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/investigator/v1/cases/446dd380-5236-11e8-8d2b-8c8590c29eaa'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)
curl -X GET $BASE_PATH/investigator/v1/cases/446dd380-5236-11e8-8d2b-8c8590c29eaa -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

{
  "source": "SalesForce",
  "category": "Money Laundering",
  "description": "",
  "parties": [
    {
      "id": "1234",
      "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/parties/1234"
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "accounts": [
    {
      "id": "5678",
      "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/accounts/5678"
      "labels": [
        "TF",
        "AML"
      ]
    }
  ],
  "paymentSources": [
    {
      "id": "9876",
      "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/payment-sources/9876"
    }
  ],
  "transactions": [
    {
      "id": "4321",
      "url": "https://CUSTOMER.api.beamtechnology.com:8888/model/v1/transactions/4321"
      "labels": [
        "TF",
        "AML"
      ]
    }
  ]
}

GET /cases/:id

This API allows you to retrieve details about a specific case.

Success HTTP status response code

200 (Successfully retrieved case details)

Get party monitoring results

Get monitoring results for a party like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/investigator/v1/monitoring-results/party/524df300-334d-11ea-8d79-0242ac110004'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)
curl -X GET $BASE_PATH/investigator/v1/monitoring-results/party/524df300-334d-11ea-8d79-0242ac110004' -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

{
  "created": "2020-01-10T02:02:58.021Z",
  "score": 30,
  "labels": [],
  "categories": [
    "Dormant Party",
    "Watchlist",
    "Onboarding"
  ],
  "actions": [
    "Block Customer"
  ],
  "monitoringId": "524df300-334d-11ea-8d79-0242ac110004",
  "transactionId": "eac43410-333d-11ea-8d79-0242ac110004",
  "caseId": "55eafa08-334d-11ea-b4ae-0242ac110003"
  "alerts": [
    {
      "id": "f51f1ce0-333d-11ea-8d79-0242ac110004",
      "name": "Sanctions screening",
      "category": "Watchlist",
      "labels": [],
      "actions": [ "Block Customer" ]
    },
    {
      "id": "f5077630-333d-11ea-8d79-0242ac110004",
      "name": "On-boarding",
      "category": "Onboarding",
      "labels": [],
      "actions": []
    },
    {
      "id": "f5026d20-333d-11ea-8d79-0242ac110004",
      "name": "Idology for dormant parties",
      "category": "Dormant Party",
      "labels": [],
      "actions": []
    }
  ]
}

GET /monitoring-results/parties/:id

This API allows you to retrieve the monitoring results for a specific party.

Success HTTP status response code

200 (Successfully retrieved monitoring details)

Get transaction monitoring results

Get monitoring results for a transaction like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/investigator/v1/monitoring-results/transactions/524df300-334d-11ea-8d79-0242ac110004'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)
curl -X GET '$BASE_PATH/investigator/v1/monitoring-results/transactions/524df300-334d-11ea-8d79-0242ac110008' -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

{
  "created": "2020-01-10T02:02:58.021Z",
  "score": 30,
  "labels": [],
  "categories": [
    "Money Laundering"
  ],
  "actions": [],
  "monitoringId": "524df300-334d-11ea-8d79-0242ac110008",
  "transactionId": "eac43410-333d-11ea-8d79-0242ac110004",
  "caseId": "55eafa08-334d-11ea-b4ae-0242ac110003"
  "alerts": [
    {
      "id": "f51f1ce0-333d-11ea-8d79-0242ac110004",
      "name": "Structuring",
      "category": "Money Laundering",
      "labels": [ "AML", "Structuring" ],
      "actions": []
    }
  ]
}

GET /monitoring-results/transactions/:id

This API allows you to retrieve the monitoring results for a specific transaction.

Success HTTP status response code

200 (Successfully retrieved monitoring details)

Webhooks API

Quick reference

After you gain access to the Webhooks API, you can use the following endpoints to work with subscriptions. For information on the full path to each endpoint, see Base paths.

Endpoint Description
GET /settings Get your signature key
POST /subscriptions Create a subscription
GET /subscriptions Get all your subscriptions
GET /subscriptions/:id Get information on a subscription
PUT /subscriptions/:id Update a subscription

Overview

The Webhooks API is a public REST API that you can use to subscribe to events in the Jumio system, such as when cases are created. Webhooks allow you to receive notifications in a push model instead of having to repeatedly poll the Jumio system for new events from your code. You can use a notification's event content to take action on cases and monitoring results using the Investigator APIs.

Jumio generates notifications when events occur at key points in the data flow:

alt text

  1. Alert Created: As data is ingested by Jumio, the monitoring engine runs rules on the data in real time. If a rule flags a particular transaction or other entity (e.g., if a transaction exceeds a certain monetary threshold), the monitoring engine creates an alert and passes the entity to the detection engine for further analysis. At this point, the alert.created notification is generated.

  2. Case Created: The detection engine periodically analyzes all the entities that were flagged by the monitoring engine so that it can spot patterns and trends that might indicate suspicious activity. When it detects activity that needs investigation by an analyst, it creates a case in the Jumio Investigation Manager, and the case.created notification is generated.

  3. Case Closed: After your analysts have resolved and closed a case, the case.closed notification is generated.

If you want to pull these notifications into an external system so they can integrate with a separate workflow, you can subscribe to one or more of the notifications using the Webhooks API.

For example, if you want to be notified immediately if one of your customers violates an implemented policy, you could subscribe to the alert.created notification and write logic in your system to temporarily lock that user's account. You could also use the case.created notification to display in your workforce management software all the cases that were created that day to make sure you are balancing the workload among your analysts. Lastly, you could subscribe to the case.closed notification and write logic to unlock the user's account as soon as they have been cleared by your analysts.

The public API sends your subscription request securely via SSL through a proxy URL to the internal subscription service, which processes the request and subscribes you to the specified event. Once the subscription is active, notifications are sent through the proxy URL to the public API, which sends the notification as a response with a JSON payload to your preconfigured return URL. The return URL must be a publicly available, secure (HTTPS) endpoint for that URL that can handle the webhook payloads. The API uses OAuth 2.0 to secure API access.

How to...

These sections describe the APIs in detail and provide examples.

Get your signature key

Get your signature key like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json',
}

response = requests.get('{}/webhooks/v1/settings'.format(base_path), headers=headers)
curl -X GET $BASE_PATH/webhooks/v1/settings -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

{
  "signatureKey": "fio4REVBn56trloj43dr"
}

GET /settings

This API allows you to obtain a signature key that can be used to verify incoming messages sent by Jumio. For more information, see Security. Note that the signature key is different from the client key you use to access the API.

Success HTTP status response code

200 (Successfully retrieved signature key)

Create a subscription

Create a subscription like this:

import requests
import json

data = {
    "webhookUrl":"https://jumiocustomer.com/events/cases",
    "events": ["case.created","case.closed"],
    "status": "active"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.post('{}/webhooks/v1/subscriptions'.format(base_path), headers=headers, data=json.dumps(data))
curl -X POST $BASE_PATH/webhooks/v1/subscriptions -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -d'{
    "webhookUrl":"https://jumiocustomer.com/events/cases",
    "events": ["case.created","case.closed"],
    "status": "active"
}'

The command returns JSON structured like this:

{
  "id": "446dd380-5236-11e8-8d2b-8c8590c29eaa",
  "created": "2019-11-20T18:12:33.020Z",
  "modified": "2019-11-20T18:12:33.020Z",
  "webhookUrl": "https://customer.com/events/cases",
  "events": ["case.created","case.closed"],
  "status": "active"
}

POST /subscriptions

This API allows you to subscribe to the event type(s) you specify in the request body.

Fields

Success HTTP status response code

201 (Successfully created subscription)

Get all subscriptions

Get a list of subscriptions like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/webhooks/v1/subscriptions'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)
curl -X GET $BASE_PATH/webhooks/v1/subscriptions -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

[
  {
    "id": "bfcb799f-764a-49ee-b7b4-61bc659d967e",
    "created": "2019-11-20T18:12:33.020Z",
    "modified": "2019-11-20T18:12:33.020Z",
    "webhookUrl": "https://customer.com/events/cases/closed",
    "events": ["case.closed"],
    "status": "active"
  },
  {
    "id": "7e34234b-95fc-45e2-b831-1c4c8e585230",
    "created": "2019-11-21T18:12:33.020Z",
    "modified": "2019-11-21T18:12:33.020Z",
    "webhookUrl": "https://customer.com/events/cases/created",
    "events": ["case.created"],
    "status": "inactive"
  }
]

GET /subscriptions

This API allows you to retrieve details for all the subscriptions you created, such as the type of events they send notifications for and the URL where the notifications are sent.

Success HTTP status response code

200 (Successfully retrieved subscriptions)

Get information on a subscription

Get info on a subscription like this:

import requests

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.get('{}/webhooks/v1/subscriptions/446dd380-5236-11e8-8d2b-8c8590c29eaa'.format(base_path), headers=headers)
json_response = response.json()

# Print response data
print(json_response)
curl -X GET $BASE_PATH/webhooks/v1/subscriptions/446dd380-5236-11e8-8d2b-8c8590c29eaa -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json'

The command returns JSON structured like this:

{
  "id": "446dd380-5236-11e8-8d2b-8c8590c29eaa",
  "created": "2019-11-20T18:12:33.020Z",
  "modified": "2019-11-20T18:12:33.020Z",
  "webhookUrl": "https://customer.com/events/cases",
  "events": ["case.created","case.closed"],
  "status": "active"
}

GET /subscriptions/:id

This API allows you to retrieve details about a specific subscription you created.

Success HTTP status response code

200 (Successfully retrieved subscription)

Update a subscription

Update a subscription like this:

import requests
import json

data = {
    "status": "inactive"
}

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'Content-Type': 'application/json'
}

response = requests.put('{}/webhooks/v1/subscriptions/446dd380-5236-11e8-8d2b-8c8590c29ea'.format(base_path), headers=headers, data=json.dumps(data))
curl -X PUT $BASE_PATH/webhooks/v1/subscriptions/446dd380-5236-11e8-8d2b-8c8590c29eaa -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -d'{
    "status": "inactive"
}'

The command returns JSON structured like this:

{
  "id": "446dd380-5236-11e8-8d2b-8c8590c29eaa",
  "created": "2019-11-20T18:12:33.020Z",
  "modified": "2019-11-20T18:15:45.050Z",
  "webhookUrl": "https://customer.com/events/cases",
  "events": ["case.created","case.closed"],
  "status": "inactive"
}

PUT /subscriptions/:id

This API allows you to update a subscription you previously created and set the status flag to active or inactive.

Fields

Success HTTP status response code

200 (Successfully retrieved subscription)

Notifications

Notifications look like this:

{
  "id": "9b215c60-5db5-11ea-a901-36d1a99ec94c",
  "created": "2020-03-04T01:15:16.135Z",
  "modified": "2020-03-04T01:15:16.249Z",
  "attempt": 1,
  "event": {
    "name": "case.created",
    "occurred": "2020-03-04T01:15:15.704Z",
    "content": {
      "caseId": "957e5650-5db5-11ea-a901-36d1a99ec94c",
      "caseUrl": "https://customer.api.beamtechnology.com/investigator/v1/cases/957e5650-5db5-11ea-a901-36d1a99ec94c"
    }
  }
}

Notifications are sent to the URL you specified with the webhooksUrl field when you created the subscription.

Following is more information on the notification fields. Note that the following rules apply for the date fields:

  1. event.occurred is when the actual event occurred. It is always older than or equal to created.
  2. created is when the notification was first sent. It is always older than or equal to modified.
Field name Type Size or format Description Example
id string 36 A unique identifier for the notification 446dd380-5236-11e8-8d2b-8c8590c29eaa
created string ISO8601 Zulu Date and time of first attempt to notify customer about the event 2018-09-29T01:10:38.922Z
modified string ISO8601 Zulu Date and time of final attempt to notify customer about the event 2018-09-29T01:10:38.922Z
attempt number null How many attempts it took to successfully sent the event 3
event.name string 64 The type of event that occurred case.created
event.occurred string ISO8601 Zulu Date and time when the event occurred and the notification was triggered 2018-09-29T01:10:38.922Z
event.content string 4096 JSON payload representing event-specific information (see Event content below) {
  "caseId": "957e5650-5db5-11ea-a901-36d1a99ec94c",
  "caseUrl": "https://customer.api.beamtechnology.com/investigator/v1/cases/957e5650-5db5-11ea-a901-36d1a99ec94c"
}

Event content

Alert created:

    "content": {
      "monitoringId": "524df300-334d-11ea-8d79-0242ac110008",
      "monitoringUrl": "https://customer.api.beamtechnology.com/investigator/v1/monitoring-results/transactions/524df300-334d-11ea-8d79-0242ac110008",
    }

Case created or closed:

    "content": {
      "caseId": "957e5650-5db5-11ea-a901-36d1a99ec94c",
      "caseUrl": "https://customer.api.beamtechnology.com/investigator/v1/cases/957e5650-5db5-11ea-a901-36d1a99ec94c"
    }

When you receive notifications, following are the fields that are returned within the event.content field for each type of event. You can use this content with the Investigator APIs to get more information about the cases and monitoring results. For example, when you get a notification that a case has been created, you can use the case ID that's included in the notification to look up details on that case using GET /cases/:id.

alert.created
case.created
case.closed

Security

Each notification contains an X-Beam-Signature header you can use to verify that the notification came from Jumio and not from a third party impersonating Jumio. To verify the signature, get your signature key, use this key to get a SHA-256 hash of the unparsed notification body, and then compare the resulting hash with the value of the X-Beam-Signature.

In addition, Jumio will provide you with IP addresses of the Jumio notifications servers. You should whitelist these IP addresses to ensure notifications reach you unhindered.

Error handling

Fixing data ingestion errors

When sending your data to Jumio, either through the Data Ingestion API or the file-based data ingestion server, it is very important to check for errors. For example, after uploading your data through SFTP, check the ingestion/failed directory in AWS after processing has completed to make sure there are no failed files. If you use the Data Ingestion API, be sure to capture and handle any errors that are returned. If you do not fix data ingestion failures, you may not be sending all your intended data to Jumio, which could affect your compliance with AML regulations.

HTTP status codes

Following are some of the generic HTTP status codes returned by the Jumio AML APIs when there is an error:

Some HTTP status codes may lead to more detailed JSON error responses to help with error resolution. For example:

{
   "status": 400,
   "code": 1004,
   "time": "2018-05-12T00:13:34.471Z",
   "message": "Missing firstName",
   "moreInfo": "https://beamtechnology.io",
   "traceId": "4f4e85b0-5579-11e8-8eff-8aa0fc600898"
}


The fields in these detailed responses are as follows:

Additionally, each API call returns a URL for the object that you added or updated. You can provide this URL to Jumio Support to help troubleshoot issues.

SAR filing integration

Overview

Jumio can file your Suspicious Activity Reports (SARs) directly with FinCEN. To enable this integration, you take the following steps:

  1. Set up a BSA E-filing account (if you do not already have one) on the FinCEN website.

  2. Provide Jumio with your Filing Organization (FO) Enrollment Code. Jumio will use this code to request your Secure Data Transfer Mode (SDTM) account from FinCEN. Note that FinCEN can take up to 8 weeks to create your SDTM production account. Once the account is ready, they will send you a transmitter control code.

  3. Provide Jumio with your Filing Institution information and Financial Institution information as described below, including information on all the branches, that will appear on the SAR form. Jumio will use this to pre-populate your SAR forms so your analysts don't have to fill this in each time they create a SAR.

  4. Provide Jumio with your transmitter information as described below, such as the organization and filing officer's details as well as the transmitter control code that FinCEN sends to you once your SDTM account is ready.

The rest of this guide describes the filing institution, financial institutions/branches, and transmitter fields in detail. The examples are in JSON, but you can send the information to Jumio in whatever format works best for you. For example, you could fill in the filing and financial institutions fields in the SAR PDF provided by FinCEN (available when you log in to your BSA E-filing account) and email it along with the values for the transmitter fields to your Jumio Solutions Engineer. For complete information on the fields, see the FinCEN SAR Schema Guide.

Filing institution fields

Example of the filing institution information provided in JSON format:

{
  "alternateName": "Beam",
  "alternateNameTypeCode": "DBA",
  "cityText": "San Francisco",
  "clearingBrokerSecurities": false,
  "contactOfficePartyFullName": "Beam",
  "contactOfficePhoneNumber": "40304384888",
  "contactOfficePhoneNumberExtension": "100",
  "countryCodeIso": "US",
  "cpoCTA": false,
  "executionOnlyBrokerSecurities": false,
  "filerLegalName": "Beam Solutions",
  "futuresCommissionMerchant": false,
  "holdingCompany": false,
  "identificationNumberText": "1221323123",
  "identificationTypeCode": "CRD",
  "introducingBrokerCommodity": false,
  "introducingBrokerSecurities": false,
  "investmentAdviser": false,
  "investmentCompany": false,
  "organizationClassificationType": "Securities_Futures",
  "primaryRegulatorTypeCode": "IRS",
  "retailForeignExchangeDealer": false,
  "selfClearingBrokerSecurities": false,
  "sroFutures": false,
  "sroSecurities": false,
  "stateCodeIso": "CA",
  "streetAddressText": "559 Clyde Ave",
  "subsidiaryOfFinancialBankHoldingCompany": false,
  "tinNumberText": "1221323123",
  "tinTypeCode": "SSN_ITIN",
  "zipCode": "94043"
}

The filing institution fields describe the firm that is filing the SAR form (your firm).

Field Description Corresponding JSON field
Filer name
(Required)
The legal name of the filing institution filerLegalName
Primary federal regulator
(Required)
The code of the regulator that has primary responsibility:
  • CFTC: Commodities Futures Trading Commission
  • FRP: Federal Reserve Board
  • FDIC: Federal Deposit Insurance Corporation
  • IRS: Internal Revenue Service
  • NCUA: National Credit Union Administration
  • OCC: Office of the Comptroller of the Currency
  • SEC: Securities and Exchange Commission
primaryRegulatorTypeCode
TIN
(Required)
The Taxpayer Identification Number (TIN), either U.S. or foreign tinNumberText
TIN type
(Required)
The type of TIN:
  • EIN
  • SSN_ITIN
  • Foreign
tinTypeCode
Type of financial institution
(Required)
The type that best describes the filing institution:
  • Casino_Card_club
  • Depository_institution
  • Housing_GSE
  • Insurance_company
  • Loan_or_Finance_Company
  • MSB
  • Securities_Futures
If none of these types is applicable, enter a description in the otherOrganizationClassificationType field. (The Other option on the SAR form will be selected automatically when you provide this description.)
organizationClassificationType or otherOrganizationClassificationType
Type of Securities and Futures institution or individual filing this report If the type of filing institution is Securities_Futures, you must specify true for the relevant Securities and Futures institution type(s) shown below and specify false for all other types. (Use the actual field names shown on the right.)
  • Clearing broker - securities
  • CPO/CTA
  • Futures Commission Merchant
  • Holding company
  • Introducing broker - commodities
  • Introducing broker - securities
  • Investment Adviser
  • Investment company
  • Retail foreign exchange dealer
  • SRO Futures
  • SRO Securities
  • Subsidiary of financial/bank holding company
If you want to specify Other on the SAR form, enter a description in the otherTypeOfSecuritiesAndFutures field. (The Other box on the SAR form will be checked automatically when you provide this description.)
Specify true or false for each field. For example:
"clearingBrokerSecurities": true,
"cpoCTA": false,
"excutionOnlyBrokerSecurities": false,
"futuresCommissionMerchant": false,
"holdingCompany": false,
"introducingBrokerCommodity": false,
"introducingBrokerSecurities": false,
"investmentAdviser": false,
"investmentCompany": false,
"retailForeignExchangeDealer": false,
"selfClearingBrokerSecurities": false,
"sroFutures": false,
"sroSecurities": false,
"subsidiaryOfFinancialBankHoldingCompany":
false,

To specify Other, enter a description in the following field:
"otherTypeOfSecuritiesAndFutures":
"description"
Filing institution identification number and code The identification number and one of the following type codes:
  • CRD: Central Registration Depository number
  • IARD: Investment Adviser Registration Depository number
  • NFA: National Futures Association number
  • RSSD: Research Statistics Supervision Discount number
  • SEC: Securities and Exchange Commission number
identificationNumberText and identificationTypeCode, one of CRD, IARD, NFA, RSSD, or SEC
Address
(Required)
Street address of the filing institution streetAddressText
City
(Required)
The city of the filing institution cityText
State code
(Required)
The state code of the filing institution, such as CA for California stateCodeIso
ZIP/Postal code
(Required)
The ZIP or postal code for the filing institution zipCode
Country code
(Required)
The two-letter ISO country code of the filing institution countryCodeIso
Alternative name If the filing institution or individual uses an alternative name that is different from their legal entity name, enter the alternative name and the type code (AKA for individuals or trade names, DBA for entities) alternateName and alternateNameTypeCode,
either AKA or DBA
Contact office party full name
(Required)
The name of the filing institution contact office where additional information about the FinCEN SAR or supporting documentation can be requested contactOfficePartyFullName
Contact office phone number
(Required)
Filing institution contact office phone number including area code contactOfficePhoneNumber
Contact office phone number extension Extension, if any contactOfficePhoneNumberExtension

Financial institution fields

Example of the financial institution provided in JSON format:

{
  "alternateName": "Beam",
  "alternateNameTypeCode": "DBA",
  "cityText": "Mountain View",
  "clearingBrokerSecurities": false,
  "countryCodeIso": "US",
  "cpoCTA": false,
  "executionOnlyBrokerSecurities": false,
  "financialInstitutionLegalName": "Beam Solutions",
  "futuresCommissionMerchant": false,
  "holdingCompany": false,
  "identificationNumberText": "1221323123",
  "identificationTypeCode": "CRD",
  "introductionBrokerCommission": false,
  "investmentAdviser": false,
  "investmentCompany": false,
  "organizationClassificationType": "Casino_Card_club",
  "primaryRegulatorTypeCode": "IRS",
  "retailForeignExchangeDealer": false,
  "selfClearingBrokerSecurities": false,
  "sroFutures": false,
  "sroSecurities": false,
  "stateCodeIso": "CA",
  "streetAddressText": "559 Clyde Ave",
  "subsidiaryOfFinancialBankHoldingCompany": false,
  "tinNumberText": "1221323123",
  "tinTypeCode": "SSN_ITIN",
  "typeOfGamingInstitution": "State_casino",
  "zipCode": "94043",
  "financialInstitutionBranches": [
    {
      "branchReferrerId": "AG45-SanFrancisco-Branch",
      "cityText": "San Francisco",
      "countryCodeIso": "US",
      "rssdNumber": "121232",
      "stateCodeIso": "CA",
      "streetAddressText": "100 Bush Street",
      "zipCode": "94043"
    }
  ]
}

The financial institution fields describe each financial institution where suspicious activity occurred. If an institution has multiple branches, you will enter those in the financialInstitutionBranches field.

Field Description Corresponding JSON field
Legal name of financial institution
(Required)
The legal name of the financial institution financialInstitutionLegalName
Primary federal regulator
(Required)
The code of the regulator that has primary responsibility:
  • CFTC: Commodities Futures Trading Commission
  • FRP: Federal Reserve Board
  • FDIC: Federal Deposit Insurance Corporation
  • IRS: Internal Revenue Service
  • NCUA: National Credit Union Administration
  • OCC: Office of the Comptroller of the Currency
  • SEC: Securities and Exchange Commission
primaryRegulatorTypeCode
TIN
(Required)
The Taxpayer Identification Number (TIN), either U.S. or foreign tinNumberText
TIN type
(Required)
The type of TIN:
  • EIN
  • SSN_ITIN
  • Foreign
tinTypeCode
Type of financial institution
(Required)
The type that best describes the finanical institution:
  • Casino_Card_club
  • Depository_institution
  • Housing_GSE
  • Insurance_company
  • Loan_or_Finance_Company
  • MSB
  • Securities_Futures
If none of these types is applicable, enter a description in the otherOrganizationClassificationType field. (The Other option on the SAR form will be selected automatically when you provide this description.)
organizationClassificationType or otherOrganizationClassificationType
Type of gaming institution If the type of financial institution is Casino_Card_club, you must specify one of the following types:
  • State_casino
  • Tribal_casino
  • Card_club
typeOfGamingInstitution
Type of Securities and Futures institution or individual If the type of finanical institution is Securities_Futures, you must specify true for the relevant Securities and Futures institution type(s) shown below and specify false for all other types. (Use the actual field names shown on the right.)
  • Clearing broker - securities
  • CPO/CTA
  • Futures Commission Merchant
  • Holding company
  • Introducing broker - commodities
  • Introducing broker - securities
  • Investment Adviser
  • Investment company
  • Retail foreign exchange dealer
  • SRO Futures
  • SRO Securities
  • Subsidiary of financial/bank holding company
If you want to specify Other on the SAR form, enter a description in the
otherTypeOfSecuritiesAndFutures field. (The Other box on the SAR form will be checked automatically when you provide this description.)
Specify true or false for each field. For example:
"clearingBrokerSecurities": true,
"cpoCTA": false,
"excutionOnlyBrokerSecurities": false,
"futuresCommissionMerchant": false,
"holdingCompany": false,
"introducingBrokerCommodity": false,
"introducingBrokerSecurities": false,
"investmentAdviser": false,
"investmentCompany": false,
"retailForeignExchangeDealer": false,
"selfClearingBrokerSecurities": false,
"sroFutures": false,
"sroSecurities": false,
"subsidiaryOfFinancialBankHoldingCompany":
false,

To specify Other, enter a description in the following field:
"otherTypeOfSecuritiesAndFutures":
"description"
Financial institution identification number and code The identification number and one of the following type codes:
  • CRD: Central Registration Depository number
  • IARD: Investment Adviser Registration Depository number
  • NFA: National Futures Association number
  • RSSD: Research Statistics Supervision Discount number
  • SEC: Securities and Exchange Commission number
identificationNumberText and identificationTypeCode, one of CRD, IARD, NFA, RSSD, or SEC
Address
(Required)
Street address of the financial institution streetAddressText
City
(Required)
The city of the filing institution cityText
State code
(Required)
The state code of the financial institution, such as CA for California stateCodeIso
ZIP/Postal code
(Required)
The ZIP or postal code for the financial institution zipCode
Country code
(Required)
The two-letter ISO country code of the financial institution countryCodeIso
Alternative name If the financial institution or individual uses an alternative name that is different from their legal entity name, enter the alternative name and the type code (AKA for individuals or trade names, DBA for entities) alternateName and alternateNameTypeCode,
either AKA or DBA
Financial institution branches The branches of this financial institution, if any (see below for details) financialInstitutionBranches

Financial institution branch fields

When providing the financial institution information, enter its branches in the financialInstitutionBranches array with the following fields for each branch (if there are no branches, leave these fields blank):

Field Description Corresponding JSON field
Address Street address of the branch streetAddressText
City The city of the branch cityText
State code The state code of the branch, such as CA for California stateCodeIso
ZIP/Postal code The ZIP or postal code of the branch zipCode
Country code The two-letter ISO country code of the branch countryCodeIso
RSSD number The Research Statistics Supervision Discount (RSSD) number for the branch rssdNumber
Branch referrer ID The internal ID or name used to reference the branch branchReferrerId

Transmitter fields

Example of the transmitter information in JSON format:

{
  "city": "Tysons Corner",
  "countryCodeIso": "US",
  "phoneNumber": "6194760276",
  "stateCodeIso": "VA",
  "streetAddress": "987 Rocky Road",
  "taxpayerIdentificationTin": "458985215",
  "transmitterContactPartyFullName": "Transmitter contact legal name",
  "transmitterControlCodeTcc": "TBSATEST",
  "transmitterFullName": "Beam",
  "zipCode": "87598"
}

The transmitter fields provide information about your organization, filing officer, and transmitter control code. The fields are typically the same as the filing institution fields.

Field Description Corresponding JSON field
Address
(Required)
Your organization's street address streetAddressText
City
(Required)
Your organization's city cityText
State code
(Required)
Your organization's state code, such as CA for California stateCodeIso
ZIP/Postal code
(Required)
Your organization's ZIP or postal code zipCode
Country code
(Required)
Your organization's two-letter ISO country code countryCodeIso
Phone number
(Required)
Your organization's phone number phoneNumber
TIN
(Required)
Your organization's taxpayer identification number taxpayerIdentificationTin
Transmitter contact full name
(Required)
Your transmitter contact person's legal name (e.g., the filing officer) transmitterContactPartyFullName
Transmitter's full name
(Required)
Your organization's full legal name transmitterFullName
Transmitter control code
(Required)
Your organization's transmitter control code, which you can obtain from FinCEN after we have established your connection with them. transmitterControlCodeTcc

Change log

This section describes the key changes made to this documentation over time.

October 27, 2021

August 10, 2021

March 5, 2021

January 25, 2021

December 10, 2020

December 2, 2020

November 12, 2020

November 2, 2020

October 13, 2020

August 27, 2020

August 24, 2020

August 4, 2020

July 20, 2020

July 8, 2020

June 2, 2020

May 29, 2020

May 4, 2020

May 1, 2020

April 27, 2020

April 2, 2020

March 31, 2020

March 12, 2020