Prepared Data

Prepared data is used to upload values for data fields that are required by a capability or risk signal in a workflow, but are not extracted from another credential such as an ID or Document. For example, many Risk Signals may be called using standalone workflows that do not include other capabilities such as Extraction, and do not require any other credentials. In these cases, the data required by the risk signal is first uploaded as prepared data, using the REST API. Using prepared data is only supported by the REST APIs for Credential Acquisition integration channel.

When your API request to create or update an account specifies a workflow that supports uploading prepared data the response body will include a credential object with a category value of DATA and a api.parts.prepared_data URL to the parametrized endpoint for uploading the data. The object also includes the api.token value for authorizing the upload request.

      "credentials": [
         ...
         {
            "id": "be032ae5-07ea-417b-b7e5-9ef6c3e68132",
            "category": "DATA",
            "label": "DATA",
            "allowedChannels": [
               "API"
            ],
            "api": {
               "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOQ4CMQxA0bukxlI2JzYdoqLlBomXboACCRDi7gxzA9qv99_Bnod72IfUIyOXxrn1EnZhiJx07T5NFZWgmHaoiAgzJQes0-NI3hTtxzdcErWRWgeVLFALKUxhAuvMRHlibLzih9s_XM7mq15ex-tyG5fXL21_F1KJ7FATGtTcHZh8giUfGHXOnGP4fAHVKVVI4wAAAA.IADgEkiZhlQkGbG3N-u-FNO7ECPzS2dJ9qLkOJG7WMaTDGemnWsk57iGZugFN-0VrT2U9L0m3UzqscTPJw__Yw",
               "parts": {
                  "prepared_data": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069/credentials/be032ae5-07ea-417b-b7e5-9ef6c3e68132/parts/PREPARED_DATA"
               },
               "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069"
            }
         }
         ...

 

 

See also:

Depending on the workflow, uploading prepared data may be either optional or mandatory. Also, specific fields and values may be either optional or mandatory.

Example Prepared Data Upload Request Body

Prepared data is uploaded by making a POST request to the prepared_data URL from the account response. The request uses Bearer Token authentication with the token from the account response.

The body of the request is a JSON object with the desired or required values. For example:

{
    "firstName": "John",
    "middleName": "",
    "lastName": "Smith",
    "dateOfBirth": "1972-11-16",
    "socialSecurityNumber": "123456789",
    "email": "email@gmail.com",
    "phoneNumber": "+15031234567",
    "personalNumber": "",
    "address": {
        "line1": "12345 SW Address Ln",
        "postalCode": "97201",
        "city": "Portland",
        "subdivision": "OR",
        "country": "USA"
    },
    "id": {
        "idNumber": "057033812",
        "type": "DRIVING_LICENSE",
        "issuingDate": "2021-01-22",
        "expiryDate": "2026-01-22"
    }
}
To prevent SQL/XML injection threats the character set [^<>"/;`%{}|] is not allowed in the prepared data body values for these keys: firstName, lastName, middleName, paternalSurname , maternalSurname ,email, phoneNumber.

Supported Fields

Not all values are required for all requests. See the documentation for specific risk signals for details on required values and formats.
Field Type Example Description
suffix string Mr, Mrs, Ms  
firstName string John First name of the subject.
middleName string Percival Middle name of the subject.
lastName string Smith Last name of the subject.
sex string M Gender of Id subject. M for male and F for female.
dateOfBirth string($date) 1972-11-16 Date of birth in ISO 8601 date format.
socialSecurityNumber string 123456789 USA SSN of the subject.
nationality string USA Nationality of the subject.
email string($email) john.smith@mymail.com Primary email address of the subject.
phoneNumber string +2134445678 Primary phone number of the subject in E.164 format.
phoneNumber2 string +3109992939 Alternate phone number of the subject in E.164 format.
personalNumber string   For Brazil, this will be the CPF number.

address

Object

 

Primary address for the subject.

address.line1

string

12345 SW Address Ln

 

address.line2

string

Suite 707

 

address.city

string

Portland

City of residence as it appears on the Id.

address.postalCode

string

97201

Postal or zip code.

address.subdivision

string

OR

City subdivision of residence as it appears on the Id.

address.country

string

USA

Country in ISO-3166-1 Alpha-3 Code or ISO-3166-1 Alpha-2 Code format.

id

Object

 

Document data.

id.idNumber

string

057033812

Primary id number on the identity document.

id.Type

string

DRIVING_LICENSE

Type of identity document.

id.subType

string

 

Sub-type of identity document.

id.issuingDate

string

2021-01-22

Date the document was issued.

id.expiryDate

string

2026-01-22

Date the document will expire.