Skip to main content
POST
/
api
/
v3
/
verifications
Create New Verification
curl --request POST \
  --url https://api.dataspike.io/api/v3/verifications \
  --header 'Content-Type: application/json' \
  --header 'ds-api-token: <api-key>' \
  --data '{
  "applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "checks_required": [
    "passport"
  ],
  "profile_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "applicant_country": "BR-12458344",
  "expiration_minutes": 240,
  "sandbox_result": {
    "status": "verified",
    "errors": {
      "document_mrz": [
        1001
      ],
      "face_comparison": [
        1001
      ],
      "poa": [
        1001
      ],
      "liveness": [
        1001
      ]
    }
  }
}'
{
  "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "status": "initial",
  "documents": [
    {
      "document_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
      "document_type": "passport"
    }
  ],
  "checks": {
    "document_mrz": {
      "data": {
        "document_type": "Passport",
        "country": "DE",
        "name": "John",
        "surname": "Doe",
        "doc_number": "P-1234567890",
        "nationality": "British",
        "birth_date": "871224",
        "sex": "M",
        "expiry_date": "201224"
      },
      "status": "pending",
      "pending_documents": [
        "passport"
      ],
      "errors": [
        {
          "code": 1001,
          "message": "document parsing failed"
        }
      ]
    },
    "face_comparison": {
      "status": "pending",
      "pending_documents": [
        "passport"
      ],
      "errors": [
        {
          "code": 1001,
          "message": "document parsing failed"
        }
      ]
    },
    "poa": {
      "status": "pending",
      "pending_documents": [
        "passport"
      ],
      "errors": [
        {
          "code": 1001,
          "message": "document parsing failed"
        }
      ]
    },
    "liveness": {
      "status": "pending",
      "pending_documents": [
        "passport"
      ],
      "errors": [
        {
          "code": 1001,
          "message": "document parsing failed"
        }
      ]
    }
  },
  "created_at": "2023-07-18T15:32:13.000Z",
  "completed_at": "2023-07-18T15:32:13.000Z",
  "verification_url": "https://am.dataspike.io/VDBA1B2EA6A28A7D2",
  "verification_url_id": "VDBA1B2EA6A28A7D2",
  "country_code": "DE",
  "expires_at": "2023-07-18T15:32:13.000Z",
  "poi_data": {
    "parsed_type": "passport",
    "has_mrz": true,
    "raw_mrz_type": "P",
    "country": "DEU",
    "full_name": "John Doe",
    "name": "John",
    "surname": "Doe",
    "document_number": "P-1234567890",
    "nationality": "DEU",
    "birth_date": "1983-03-21",
    "sex": "M",
    "expiry_date": "2021-02-24",
    "issue_date": "2021-02-24",
    "pin": "<string>",
    "card_number": "<string>",
    "license_number": "<string>",
    "license_type": "<string>",
    "license_class": "<string>",
    "cpf_number": "<string>",
    "vin": "<string>",
    "nin": "<string>",
    "occupation": "<string>",
    "polling_unit": "<string>",
    "region": "<string>",
    "restrictions": "<string>",
    "height": "<string>",
    "registration_date": "<string>",
    "parents_names": "<string>",
    "endorsements": "<string>"
  },
  "is_sandbox": false,
  "profile_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "settings": {
    "poi_required": true,
    "poi_allowed_documents": [
      "passport"
    ],
    "face_comparison_required": true,
    "face_comparison_allowed_documents": [
      "selfie"
    ],
    "poa_required": false,
    "disable_cross_check_by_bio": false,
    "disable_cross_check_by_photo": false,
    "disable_verify_poa_country_match_with_poi": false,
    "countries": [
      "FR"
    ],
    "allow_poi_manual_uploads": false,
    "allow_desktop": false,
    "ui_settings": {},
    "manual_field_settings": {
      "enabled": true,
      "description": "<string>",
      "full_name": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "email": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "phone": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "country": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "dob": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "gender": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "citizenship": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "address": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "certificate_of_incorporation": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "ownership_document": {
        "enabled": true,
        "caption": "<string>",
        "order": 123,
        "optional": true
      },
      "custom_fields": [
        {
          "label": "<string>",
          "caption": "<string>",
          "order": 123,
          "options": {
            "choices": [
              "<string>"
            ],
            "type": "<string>"
          }
        }
      ]
    },
    "finish_screen_settings": {
      "enabled": true,
      "settings": {
        "title": "<string>",
        "main_text": "<string>",
        "redirect_warning": "<string>",
        "cta": "<string>",
        "redirect_link": "<string>"
      }
    }
  },
  "aml_search_id": "d358ace9-9e35-42cd-b8b7-837c1005d2f5",
  "manual_fields": {
    "full_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "country": "<string>",
    "dob": "<string>",
    "gender": "M",
    "citizenship": "<string>",
    "address": "<string>",
    "custom_fields": {}
  },
  "custom_files": {}
}

Authorizations

​
ds-api-token
string
header
required

Body

application/json

Create Verification Request

​
applicant_id
string<uuid>

Applicant ID, for which the verification will be linked to, if omitted then new random Applicant will be created automatically

Example:

"01827ed4-c928-7a3c-9a30-7ab7cc169d11"

​
checks_required
enum<string>[]
deprecated

Deprecated, please use verification profiles instead. List of verification checkes, that will be performed for the end-user. In case of empty required checks will be gathered from profile.

​
profile_id
string<uuid>

Verification profile id, if ommited default will be used. Verification profile defines allowed document types, countries and other verification settings.

Example:

"01827ed4-c928-7a3c-9a30-7ab7cc169d11"

​
applicant_country
string<ISO 3166-1 ALPHA-2 code>

Two-letter ISO 3166-1 ALPHA-2 code, reference https://www.iban.com/country-codes

Example:

"BR-12458344"

​
expiration_minutes
integer
default:240

The expiration_minutes field is an optional integer value representing the duration after the verification creation when verifications are still valid. The default value is 240 minutes, and the allowed range for this field is from 1 to 10080 minutes.

​
sandbox_result
object

Predefined result of verification. Only valid for sandbox environment.

Response

200 - application/json

Create Verification Response

​
id
string<uuid>
required

Id of created verification

Example:

"01827ed4-c928-7a3c-9a30-7ab7cc169d11"

​
applicant_id
string<uuid>
required

Id of applicant verification is linked to

Example:

"01827ed4-c928-7a3c-9a30-7ab7cc169d11"

​
status
enum<string>
required

The First verification status is initial.

Second one is pending, when some documents are uploaded to verification or applicant of verification, but not all required documents are uploaded.

When all documents are uploaded and verification has been proceeded by api (https://docs.dataspike.io/api#tag/Verifications/operation/proceed-verification) or web sdk status becomes to in_progress.

After in_progress status can be both verified or failed depending on the verification result.

Transition to canceled status can be from any status if verification was canceled, except verified and failed.

Transition to expired status can be from any status if verification has expired, except verified, in_progress and failed.

Flow of status

Available options:
initial,
pending,
in_progress,
verified,
failed,
canceled,
expired
​
checks
object
required

Object describes required checks and it`s current status

​
created_at
string<ISO-8601>
required

Verification creation timestamp

Example:

"2023-07-18T15:32:13.000Z"

​
verification_url
string
required

Verification url that can be provided to the end user to perform online verification

Example:

"https://am.dataspike.io/VDBA1B2EA6A28A7D2"

​
verification_url_id
string
required

Verification short id

Example:

"VDBA1B2EA6A28A7D2"

​
expires_at
string<ISO-8601>
required

Verification expiration timestamp

Example:

"2023-07-18T15:32:13.000Z"

​
is_sandbox
boolean
default:false
required

Flag indicates that verification is created in sandbox env

​
profile_id
string<uuid>
required

Verification profile id

Example:

"01827ed4-c928-7a3c-9a30-7ab7cc169d11"

​
settings
object
required

Verification profile settings

​
documents
object[]

List of prodived documents

​
completed_at
string<ISO-8601>

Time of completion

Example:

"2023-07-18T15:32:13.000Z"

​
country_code
string<ISO 3166-1 ALPHA-2 code>

Two-letter ISO 3166-1 ALPHA-2 code, reference https://www.iban.com/country-codes

Example:

"DE"

​
poi_data
object
​
aml_search_id
string<uuid>

AML search id operation

Example:

"d358ace9-9e35-42cd-b8b7-837c1005d2f5"

​
manual_fields
object

Custom fields values

​
custom_files
object

Mapping of custom field labels to uploaded document info