# API Reference

# Introduction

Sum&Substance's API allows you to send and receive applicants’ data and documents for verification through simple RESTful APIs. API responds with JSON payload (unless otherwise stated). When data payload should be provided, it expects parameters to be passed in valid JSON (except when stated otherwise) with the Content-Type: application/json header being set.

We have two environments:

• Test environment test-api.sumsub.com is only needed to implement integration with Sum&Substance. No checks are performed on the test environment.
• In order to provide you with access to the production environment api.sumsub.com we require that the integration is tested first. We just want to make sure that everything goes right.

# Authentication

# App Tokens

This is the most secure method of talking to our API programmatically.

You can generate App Tokens in the dev space in our dashboard for test and production environments.

# Making a request

All requests must contain the following headers:

• X-App-Token - an App Token that you generate in our dashboard
• X-App-Access-Sig - signature of the request in the hex format (see below)
• X-App-Access-Ts - number of seconds since Unix Epoch in UTC

# Signing a request

The value of the X-App-Access-Sig is generated by a sha256 HMAC algorithm using a secret key (provided upon App Token generation) on the bytes obtained by concatenating the following information:

• A timestamp (value of the X-App-Access-Ts header) taken as a string
• An HTTP method name in upper-case, e.g. GET or POST
• URI of the request without a host name, starting with a slash and including all query parameters, e.g. /resources/applicants/123?fields=info
• Request body, taken exactly as it will be sent. If there is no request body, e.g. for GET requests, don't include it.

# Examples

Here are some examples how you can sign a request

def sign_request(request: requests.Request) -> requests.PreparedRequest:
    prepared_request = request.prepare()
    now = int(time.time())
    method = request.method.upper()
    path_url = prepared_request.path_url  # includes encoded query params
    # could be None so we use an empty **byte** string here
    body = b'' if prepared_request.body is None else prepared_request.body
    # prepared request body is already in bytes, so don't need to encode it
    data_to_sign = str(now).encode('utf-8') + method.encode('utf-8') + path_url.encode('utf-8') + body
    # hmac needs bytes
    signature = hmac.new(
        APP_TOKEN_SECRET.encode('utf-8'),
        data_to_sign,
        digestmod=hashlib.sha256
    )
    prepared_request.headers['X-App-Token'] = APP_TOKEN_KEY
    prepared_request.headers['X-App-Access-Ts'] = str(now)
    prepared_request.headers['X-App-Access-Sig'] = signature.hexdigest()
    return prepared_request

<?php
    function _addSignature(Am_HttpRequest $request)
    {
        $ts = time();

        $uri = $request->getUrl()->getPath() . ($request->getUrl()->getQuery() ? "?" . $request->getUrl()->getQuery() : "");
        $signature = hash_hmac('sha256',
            $ts . strtoupper($request->getMethod()) . $uri . $request->getBody(),
            $this->getConfig(self::CONFIG_APP_SECRET));

        $request->setHeader([
            'Accept' => 'application/json',
            'X-App-Token' => $this->getConfig(self::CONFIG_APP_TOKEN),
            'X-App-Access-Sig:' . $signature,
            'X-App-Access-Ts:' . $ts,
            'Content-Type: application/json'
        ]);

    }

signature(
        '/resources/applicants',
        'POST',
        '{"externalUserId":"12345","email":"[email protected]","lang":"en","requiredIdDocs":{"docSets":[{"idDocSetType":"IDENTITY","types":["ID_CARD","PASSPORT","DRIVERS"],"subTypes":["FRONT_SIDE","BACK_SIDE"]},{"idDocSetType":"SELFIE","types":["SELFIE"],"videoRequired":"liveness"}]}}'
    );
?>

$appToken = 'tst:tZlb1OcruVy3wNtcN9BvcbrC.vRsDrrxisT9vCEfIFBGNtwzySpixEgy0';
$secretKey = 'C51rrsh8YkHi7LwWb1olnYdP2RhAu2Qc';

$applicantId = '5ebc1010e18bd7d522799f12';
$baseUrl = 'https://test-api.sumsub.com';
$endpoint = '/resources/applicants/' . $applicantId . '/info/idDoc';

$config = [];
$client = new \GuzzleHttp\Client($config);

$ts = round(strtotime("now"));

$metadata = ['idDocType' => 'PASSPORT', 'country' => 'GBR'];
$file = '/tmp/dlf.jpeg';

$multipart = new \GuzzleHttp\Psr7\MultipartStream([
    [
        "name" => "metadata",
        "contents" => json_encode($metadata)
    ],
    [
        'name' => 'content',
        'contents' => fopen($file, 'r')
    ],
]);
$request = new \GuzzleHttp\Psr7\Request('POST', $baseUrl . $endpoint);
$request = $request->withBody($multipart);

$signature = hash_hmac('sha256', $ts . 'POST' . $endpoint . $request->getBody(), $secretKey);

$request = $request->withHeader('X-App-Token', $appToken);
$request = $request->withHeader('X-App-Access-Sig', $signature);
$request = $request->withHeader('X-App-Access-Ts', $ts);

$body = $client->send($request)->getBody();
echo $body;

private static String sign(long ts, String secret, String method, String path, byte[] body) {
  Mac hmacSha256 = Mac.getInstance("HmacSHA256");
  hmacSha256.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
  hmacSha256.update((ts + method + path).getBytes(StandardCharsets.UTF_8));
  byte[] bytes = body == null ? hmacSha256.doFinal() : hmacSha256.doFinal(body);
  return Hex.encodeHexString(bytes);
}

const axios = require('axios')
const crypto = require('crypto')
const fs = require('fs')
const FormData = require('form-data')
const APP_TOKEN_KEY = 'tst:PbIv5zDOPEIayyrr6ZAglQxU.76eq3HJOghyYHBf89WZY8mCxzl2GczZa'
const APP_TOKEN_SECRET = 'MhsLVxBBUcC00VR3LMa51XAO5K0atVXJ'

axios.interceptors.request.use(sign, function (error) {
  return Promise.reject(error);
})

function getBufferFromFormData(data) {
  var dataBuffer = new Buffer.alloc( 0 );
  var boundary = data._boundary
  for (var i = 0, len = data._streams.length; i < len; i++) {
    if (typeof data._streams[i] !== 'function') {

      // Add content to the buffer.
      if(Buffer.isBuffer(data._streams[i])) {
        dataBuffer = Buffer.concat( [dataBuffer, data._streams[i]]);
      }else {
        dataBuffer = Buffer.concat( [dataBuffer, Buffer.from(data._streams[i])]);
      }

      // Add break after content.
      if (typeof data._streams[i] !== 'string' || data._streams[i].substring( 2, boundary.length + 2 ) !== boundary) {
        dataBuffer = Buffer.concat( [dataBuffer, Buffer.from(FormData.LINE_BREAK)] );
      }
    }
  }
  var lastBoundary = '--' + data._boundary + '--' + FormData.LINE_BREAK
  return Buffer.concat( [dataBuffer, Buffer.from(lastBoundary)] )
}

function sign(config) {

  console.log('comes for authorization')
  const time =  Math.round(Date.now() / 1000)
  const hmacSha256 = crypto.createHmac('sha256',  APP_TOKEN_SECRET)
  hmacSha256.update(time + config.method.toUpperCase() + config.url)

  if (config.data) {
    hmacSha256.update(getBufferFromFormData(config.data))
  }

  config.headers['Accept'] = 'application/json'
  config.headers['Content-Type'] = 'multipart/form-data'
  config.headers['X-App-Token'] = APP_TOKEN_KEY
  config.headers['X-App-Access-Ts'] = time
  config.headers['X-App-Access-Sig'] = hmacSha256.digest('hex')

  return config
}


async function addDocument() {

  axios.defaults.baseURL = 'https://test-api.sumsub.com'
  axios.defaults.headers.post['Accept'] = 'application/json'

      const applicantId = '5eec9cc9155a632657d88bcd'
      const idDocType = 'PASSPORT'
      const country = 'GBR'
      const filePath = 'file.png'

      const form = new FormData()

      form.append('metadata', JSON.stringify({ idDocType, country }))

      const content = fs.readFileSync(filePath)
      form.append('content', content, 'file.png')

      axios.post(`/resources/applicants/${applicantId}/info/idDoc`, form, {headers: form.getHeaders()}
      ).then(res => {
          console.log('result', res.data)
      }).catch(error => {
          console.error(' error while making connection ', error)
      })

}
addDocument()


const ttlInSecs='600'
const externalUserId='coolExternalUserId1'

function requestAccessToken(externalUserId, ttlInSecs) {

  axios.post(`/resources/accessTokens?userId=${externalUserId}&ttlInSecs=${ttlInSecs}`
  ).then(res => {
    console.log('result', res.data)
  }).catch(error => {
    console.error(error)
  })
}

requestAccessToken(externalUserId, ttlInSecs)

func sign(ts string, secret string, method string, path string, body *[]byte) string {
 hash := hmac.New(sha256.New, []byte(secret))
 data := []byte(ts + method + path)

 if body != nil {
  data = append(data, *body...)
 }

 hash.Write(data)
 return hex.EncodeToString(hash.Sum(nil))
}

require 'json'
require 'httparty'

class Sumsub
 class << self

  def request_env_url
    return 'https://api.sumsub.com/resources/applicants' if Rails.env.production?
    return 'https://test-api.sumsub.com/resources/applicants' if Rails.env.staging? || Rails.env.development?
  end

  def request_env_token
    return "XXXX" if Rails.env.production?
    return "XXXX" if Rails.env.staging? || Rails.env.development?
  end

  def signed_message(time, body)
    key = 'XXXX'
    data = time.to_s + 'POST' + '/resources/applicants' + body.to_json.to_s
    puts data
    digest = OpenSSL::Digest.new('sha256')
    hexdigest = OpenSSL::HMAC.hexdigest(digest, key, data)
    return hexdigest
  end

  def applicantRequest(user_id: 00001, user_email: '[email protected]')

    body = {
        "externalUserId": user_id.to_s.encode("UTF-8"),
        "email": user_email.encode("UTF-8"),
        "requiredIdDocs": {
          "docSets": [
            {
              "idDocSetType": "IDENTITY",
              "types": [
                "ID_CARD",
                "PASSPORT",
                "DRIVERS"
              ]
            },
            {
              "idDocSetType": "SELFIE",
              "types": [
                "SELFIE"
              ]
            }
          ]
        }
      }

    epoch_time = Time.now.to_i
    access_signature = signed_message(epoch_time, body)
    header = {
      "X-App-Token": "#{request_env_token.encode("UTF-8")}",
      "X-App-Access-Sig": "#{access_signature.encode("UTF-8")}",
      "X-App-Access-Ts": "#{epoch_time.to_s.encode("UTF-8")}",
      "Accept": "application/json",
      "Content-Type": "application/json"
    }

    puts access_signature
    puts access_signature.encode("UTF-8")


    # Send the request
    response = HTTParty.post(request_env_url, body: body, headers: header )
    puts response
    puts "@"*50
    puts response.body
    json_body = JSON.parse(response.body)
    puts json_body
    return json_body
  end
 end
end

# Descriptions for 401 error code

{
  "description": "Invalid app token [if]",
  "code": 401,
  "correlationId": "req-5fd59b09-7f5e-41cd-a86b-38a4e6d57e08"
}

# Access tokens for SDKs

When initializing WebSDK or MobileSDK, an access token authentication must be used.

POST /resources/accessTokens

# REQUEST ARGUMENTS

# RESPONSE

# Creating an access token for applicant

curl -X POST \
  'https://test-api.sumsub.com/resources/accessTokens?userId=JamesBond007&ttlInSecs=600' \
  -H 'Accept: application/json'

# Example response

{
  "token": "639e5279-0ec2-4814-96f2-2c7b2dc813a5",
  "userId": "JamesBond007"
}

# Errors

On API errors we return standard HTTP Status Codes. Response body contains a JSON payload with additional information. For example:

{
  "description": "Error analyzing file, unsupported format or corrupted file",
  "code": 400,
  "correlationId": "req-5fd59b09-7f5e-41cd-a86b-38a4e6d57e08",
  "errorCode": 1004, // may be absent
  "errorName": "corrupted-file" // may be absent
}

# Response body

# Error codes

# Applicants API

# Creating an applicant

An applicant is an entity representing one physical person. It may have several ID documents attached, like an ID card or a passport. Many additional photos of different documents can be attached to the same applicant.

POST /resources/applicants

When creating the applicant, the request body should contain parameter requiredIdDocs. You can have any combination of docSets in any order (this will be automatically mapped to the corresponding WebSDK steps). The only limitation is that document types must not overlap between different docSets.

# REQUEST ARGUMENTS

# REQUEST BODY

# info ATTRIBUTE

# addresses ELEMENTS FIELDS

An applicant entity with the associated id (refer to the example). Persist the id field after creating the applicant - it will be needed for further requests that you intend to make.

# Supported idDocSetType are:

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants' \
  -H 'Content-Type: application/json' \
  -d '{
	"externalUserId": "someClientUserId",
	"info": {
    "country": "GBR",
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+449112081223",
    "dob": "2000-03-04",
    "placeOfBirth": "London"
	},
	"requiredIdDocs": {
		"docSets": [{
				"idDocSetType": "IDENTITY",
				"types": ["PASSPORT","ID_CARD","DRIVERS","RESIDENCE_PERMIT"]
			},
			{
				"idDocSetType": "SELFIE",
				"types": ["SELFIE"]
			},
			{
				"idDocSetType": "PROOF_OF_RESIDENCE",
				"types": ["UTILITY_BILL"]
			}
		]
	}
}'

# Example response

{
  "id": "5bb8563c0a975a5e6b322ecc",
  "createdAt": "2018-10-06 06:29:16",
  "clientId": "SumsubClient",
  "inspectionId": "5bb8563c0a975a5e6b322ecd",
  "externalUserId": "someClientUserId",
  "info": {
    "firstName": "John",
    "lastName": "Smith",
    "dob": "2000-03-04",
    "placeOfBirth": "London",
    "country": "GBR",
    "phone": "+449112081223"
  },
  "env": "test-api",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": ["PASSPORT", "ID_CARD", "DRIVERS"]
      },
      {
        "idDocSetType": "SELFIE",
        "types": ["SELFIE"]
      },
      {
        "idDocSetType": "PROOF_OF_RESIDENCE",
        "types": ["UTILITY_BILL"]
      }
    ]
  },
  "review": {
    "createDate": "2018-10-06 06:29:16+0000",
    "reviewResult": {},
    "reviewStatus": "init",
    "notificationFailureCnt": 0
  }
}

# Changing required document set

This method patches the required document set of the applicant. In case you need to add one more step to the check, for example, only the id document and the selfie were requested at first, and after the check has been completed you need to get the proof of address, so you need to add one more step to the current list of required documents. Please note that you should have special permission to make this request (contact the Sum&Substance tech team).

POST /resources/applicants/{applicantId}/requiredIdDocs

# REQUEST ARGUMENTS

# RESPONSE

A new requiredIdDocs will be returned.

# Example request without body for getting current required document set

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5bb862d90a975a5e6b322ef0/requiredIdDocs' \
  -H 'Content-Type: application/json'

# Example request with body for changing required document set

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5bb862d90a975a5e6b322ef0/requiredIdDocs' \
  -H 'Content-Type: application/json' \
  -d '{
    "docSets": [
        {
            "idDocSetType": "IDENTITY",
            "types": [
                "PASSPORT",
                "ID_CARD",
                "DRIVERS",
                "RESIDENCE_PERMIT"
            ]
        },
        {
            "idDocSetType": "PROOF_OF_RESIDENCE",
            "types": ["UTILITY_BILL"]
        }
    ]
}'

# Example response

{
  "docSets": [
    {
      "idDocSetType": "IDENTITY",
      "types": ["PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT"]
    },
    {
      "idDocSetType": "PROOF_OF_RESIDENCE",
      "types": ["UTILITY_BILL"]
    }
  ]
}

# Adding an ID document

A method gets a multipart form: ID doc JSON metadata and, optionally, a document photo. If the ID doc with this type already exists, its data will be merged. Existing data will be overwritten if they also present in the new object. However, a new image will be added nonetheless. If document metadata are not known yet, just send type and a country. E.g. "PASSPORT" and "GBR". These two fields are mandatory.

POST /resources/applicants/{applicantId}/info/idDoc

# REQUEST HEADERS

# REQUEST ARGUMENTS

# FORM DATA

# REQUEST metadata BODY PART FIELDS

# RESPONSE

JSON representing added document information.

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5b75a5e80a975a3ef2102a87/info/idDoc' \
  -H 'content-type: multipart/form-data' \
  -F 'metadata={"idDocType":"PASSPORT","country":"USA"}' \
  -F 'content={path to file (file contents)}'

# Example response

{
  "idDocType": "PASSPORT",
  "country": "USA"
}

In cases when only the data of the document needs to upload:

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5b75a5e80a975a3ef2102a87/info/idDoc' \
  -H 'Content-Type: multipart/form-data' \
  -F 'metadata={
  "idDocType": "PASSPORT",
  "country": "GBR",
  "number": "123456789",
  "issuedDate": "2015-01-02",
  "dob": "2000-02-01",
  "placeOfBirth": "London"
}'

# Example response

{
  "idDocType": "PASSPORT",
  "country": "GBR",
  "issuedDate": "2015-01-02",
  "number": "40111234567",
  "dob": "2000-02-01",
  "placeOfBirth": "London"
}

# Supported document types

# Getting applicant data

During the verification we also extract data from the applicant's id docs. To get the full structured view of an applicant you should perform the following request.

GET /resources/applicants/{applicantId}/one

or

GET /resources/applicants/-;externalUserId={externalUserId}/one

# REQUEST ARGUMENTS

# RESPONSE

It's basically an applicant that you've created (or we've created for you, e.g. via WebSDK) with augmented information in cases where a verification has been completed. The info.idDocs field contains information extracted from applicants’ documents. As the described endpoint is actually quite generic (e.g. may return several applicants by external id, but we omit such details in this document), it returns a list of items. However, if you provide an applicant id that exists, only 1 item will be returned.

# Example request

curl -X GET \
  'https://test-api.sumsub.com/resources/applicants/5b594ade0a975a36c9349e66/one'

# Example response

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "ClientName",
  "inspectionId": "5b594ade0a975a36c9379e67",
  "externalUserId": "SomeExternalUserId",
  "info": {
    "firstName": "CHRISTIAN",
    "firstNameEn": "CHRISTIAN",
    "lastName": "SMITH",
    "lastNameEn": "SMITH",
    "dob": "1989-07-16",
    "country": "DEU",
    "addresses": [
      {
        "street": "Biegerstraße",
        "streetEn": "Biegerstrasse",
        "subStreet": "16 APT 5",
        "subStreetEn": "16 APT 5",
        "town": "Knetzgau",
        "townEn": "Knetzgau",
        "postCode": "97478",
        "country": "DEU"
      }
    ],
    "idDocs": [
      {
        "idDocType": "ID_CARD",
        "country": "DEU",
        "firstName": "CHRISTIAN",
        "firstNameEn": "CHRISTIAN",
        "lastName": "SMITH",
        "lastNameEn": "SMITH",
        "issuedDate": "2018-09-05",
        "validUntil": "2028-09-04",
        "number": "LGXX359T8",
        "dob": "1989-07-16",
        "mrzLine1": "IDD<<LGXX359T88<<<<<<<<<<<<<<<",
        "mrzLine2": "8907167<2809045D<<<<<<<<<<<<<8",
        "mrzLine3": "SMITH<<CHRISTIAN<<<<<<<<<<<<<<"
      }
    ]
  },
  "email": "[email protected]",
  "env": "ru-api",
  "applicantPlatform": "Android",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "PASSPORT",
          "ID_CARD"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ]
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 115879,
    "elapsedSinceQueuedMs": 95785,
    "reprocessing": true,
    "createDate": "2020-06-24 05:11:02+0000",
    "reviewDate": "2020-06-24 05:12:58+0000",
    "startDate": "2020-06-24 05:11:22+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed",
    "notificationFailureCnt": 0
  },
  "lang": "de",
  "type": "individual"
}

Here you can find examples of recognition results for all supported document types.

# Changing applicant data

If you want to change an applicant's data you can issue a PATCH request instead of creating a new applicant, which is highly discouraged. This method patches the fields in the info key of the applicant. Please note that you should have special permissions to make this request (contact the Sum&Substance tech team).

PATCH /resources/applicants/{applicantId}/info

# REQUEST ARGUMENTS

The body must contain only those fields that you intend to change. Null fields will be ignored. If you want to unset some fields, provide these in the unsetFields query parameter. Check the info attribute above for the list of supported fields.

# RESPONSE

A patched info entity. As this endpoint could be quite damaging if misused, please check that it returns expected results on the test environment — it's a client's responsibility to treat their applicants well 😃

# Example request

curl -X PATCH \
  'https://test-api.sumsub.com/resources/applicants/5b76df770a975a1404cbcb60/info' \
  -H 'Content-Type: application/json' \
  -d '{
  "firstName" : "Andrew",
  "dob" : "1990-05-01"
}'

# Example response

{
  "firstName": "Andrew",
  "dob": "1990-05-01",
  "country": "GBR",
  "idDocs": [
    {
      "idDocType": "PASSPORT",
      "country": "GBR",
      "number": ""
    },
    {
      "idDocType": "DRIVERS",
      "country": "GBR"
    }
  ]
}

# Getting verification results

When we are talking about verification results we typically mean two labels:

Once verification is finished, we will send you a POST request with JSON payload to the URL provided to us while integrating. Oftentimes, there are different URLs for staging and production environments. We may send several types of webhooks, but the one of interest here is the applicantReviewed webhook. This type of webhook is expected to arrive on average after 3-5 minutes, but can take up to 24 hours, in theory.

We recommend that you wait for the webhook no more than a day, and then send a request to our server for information about the status of the applicant.

Also you can monitor webhook statuses and resend them manually on the API Health page of dashboard on test and production.

Webhook contains a reviewResult field that contains extra information, please see example. An important field is reviewAnswer, which contains a final highly trusted answer. Additionally, in cases of the RED answer, the rejectLabels field contains one or more of the following machine-readable constants:

Finally, the reviewRejectType field tells about the rejection type (if the RED answer is given). The following values are possible:

# Example webhook payload with 'RED' answer

{
  "applicantId": "5cb744200a975a67ed1798a4", // applicant ID
  "inspectionId": "5cb744200a975a67ed1798a5", // applicant's inspection ID
  "correlationId": "req-fa94263f-0b23-42d7-9393-ab10b28ef42d",
  "externalUserId": "externalUserId",
  "type": "applicantReviewed",
  "reviewResult": {
    // A human-readable comment that can be shown to your end user
    // Please note that individual images may also contain additional document-specific comments.
    // In this case this field might be empty.
    // In order to get them, refer to the Getting document images section
    "moderationComment": "We could not verify your profile. Please contact support: [email protected]",
    // A human-readable comment that should not be shown to an end user, and is meant to be read by a client
    // This field will contain applicant's top-level comments,
    // plus, if the rejectType is not RETRY it may contain some private info, like that the user is a fraudster.
    // we envision that this field will be used for admin areas of our clients,
    // where a human can get all information
    "clientComment": " Suspected fraudulent account.",
    // final answer that should be highly trusted (only 'RED' and 'GREEN' are currently supported)
    "reviewAnswer": "RED",
    // a machine-readable constant that describes the problems in case of verification failure
    "rejectLabels": ["UNSATISFACTORY_PHOTOS", "GRAPHIC_EDITOR", "FORGERY"],
    "reviewRejectType": "FINAL"
  },
  // indicates that the verification process has been completed
  // NOTE: it does not mean that the applicant was approved,
  // it just means that an applicant was processed
  "reviewStatus": "completed",
  // time of webhook creation
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Example webhook payload with 'GREEN' answer

{
  "applicantId": "5cb56e8e0a975a35f333cb83",
  "inspectionId": "5cb56e8e0a975a35f333cb84",
  "correlationId": "req-a260b669-4f14-4bb5-a4c5-ac0218acb9a4",
  "externalUserId": "externalUserId",
  "type": "applicantReviewed",
  "reviewResult": {
    "reviewAnswer": "GREEN"
  },
  "reviewStatus": "completed",
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Applicant life-cycle

• When creating an applicant, its status becomes init.
• After uploading all required documents the status becomes pending.

• In some cases (discussed in advance), there is a special mode, when a client must manually signal to us when an applicant is ready to be reviewed.
• After the verification process is completed, the status of the applicant will change to completed.

# Getting applicant status (SDK)

It is recommended that you use this method if you are using a WebSDK.

GET /resources/applicants/{applicantId}/status

# REQUEST ARGUMENTS

# RESPONSE

The reviewStatus can be one of the following:

# Example request

curl -X GET \
  'https://test-api.sumsub.com/resources/applicants/5b76df770a975a1404cbcb60/status'

# Example response

{
  "id": "5b76df770a975a1404cbcb60",
  "inspectionId": "5b76df770a975a1404cbcb61",
  "applicantId": "5b76df770a975a1404cbcb60",
  "createDate": "2018-10-06 12:47:57+0000",
  "startDate": "2018-08-17 14:51:59+0000",
  "reviewResult": {
    "moderationComment": "We could not verify your profile. Please contact support: [email protected]",
    "clientComment": "The submitted documents or means of payment belong to different people.",
    "reviewAnswer": "RED",
    "rejectLabels": ["INCONSISTENT_PROFILE", "GRAPHIC_EDITOR"],
    "reviewRejectType": "FINAL"
  },
  "reviewStatus": "completed",
  "notificationFailureCnt": 0
}

# Getting applicant status (API)

It is recommended that you use this method if you not only need an applicant’s status, but also information about documents.

GET /resources/applicants/{applicantId}/requiredIdDocsStatus

# REQUEST ARGUMENTS

# RESPONSE

A breakdown for each step. Each step contains an array of images' IDs (could be several, e.g. if two sides were uploaded). You can get images with those IDs by issuing a request described here.

# Example request:

curl -X GET \
  'https://test-api.sumsub.com/resources/applicants/5bb8cca10a975a624903cf65/requiredIdDocsStatus'

# Example response:

{
  "IDENTITY": {
   // a step identifier
    "reviewResult": {
    // if exists, that means that a document was uploaded
      "moderationComment": "Please upload a photo of the front of your ID card.",
      "reviewAnswer": "RED"
    },
    "country": "LVA", // document country
    "idDocType": "ID_CARD", // specific document type for the step
    "imageIds": [122352326,34246467], // image IDs that represent a document
    "imageReviewResults": {
      "34246467": {
        "reviewAnswer": "GREEN"
      },
      "122352326": {
        "moderationComment": "Please upload a photo of the front of your ID card.", // A human-readable comment that can be shown to your end user
        "reviewAnswer": "RED",
        "rejectLabels": ["DOCUMENT_PAGE_MISSING","FRONT_SIDE_MISSING"],
        "reviewRejectType": "RETRY"
      }
    }
  },
  "SELFIE": {
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "country": "LVA",
    "idDocType": "SELFIE",
    "imageIds": [181314576],
    "imageReviewResults": {
      "181314576": {
        "reviewAnswer": "GREEN"
      }
    }
  }
}

# Requesting an applicant re-check

You can programmatically ask us to re-check an applicant in cases where you or your user believe that our system made a mistake, or you want to request some additional checks agreed with us in advance. To do so you should explicitly move an applicant to the pending state by performing the following request.

POST /resources/applicants/{applicantId}/status/pending?reason=${reason}

# REQUEST ARGUMENTS

Provide a reason if available. It will help us understand why you want to recheck an applicant. If agreed in advance the reason you will be sending, we can automate the process and e.g. perform some additional checks and notify you about the results by the usual webhook means. If you want to automate complaints to your support, just send a user message along and we will consider it on a case-by-case basis.

# RESPONSE

In case of HTTP response 200, you may ignore the response body.

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5b73b82f0a975a3b46429758/status/pending?reason=someReason'

# Example response

{
  "ok": 1
}

# Requesting an applicant check with different flow

You can programmatically request applicant check with flow that somehow differs from your usual checks.

POST /resources/applicants/{applicantId}/status/pending?reasonCode=${reason}

# REQUEST ARGUMENTS

Provide a reasonCode to us so we could set up different flows on our side.

# RESPONSE

In case of HTTP response 200, you may ignore the response body.

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5b73b82f0a975a3b46429758/status/pending?reasonCode=someFlow'

# Example response

{
  "ok": 1
}

# Getting document images

If you are interested in receiving images that were part of the final verification, you should use this method. Please note that you should have special permissions to make this request (contact the Sum&Substance tech team).

GET /resources/inspections/{inspectionId}/resources/{imageId}

# REQUEST ARGUMENTS

# RESPONSE

Binary content representing a document. The Content-Type response header more precisely describes the response mime-type. The full list of mime-types and file formats you can find here.

# Example request:

curl -X GET \
  'https://test-api.sumsub.com/resources/inspections/5bb8cca10a975a624903cf66/resources/551262049'

# Adding an applicant to blacklist

If for some reason you need to add an applicant to the blacklist, you can use this endpoint. It is necessary to add the reason for adding the applicant to the blacklist.

POST /resources/applicants/{applicantId}/blacklist

# REQUEST ARGUMENTS

# RESPONSE

The answer will contain the applicant added to the blacklist.

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5c0e93c30a975a53a79aa54b/blacklist?note=A%20user%20provided%20a%20fake%20document'

# Example response

{
  "id": "5bb8563c0a975a5e6b322ecc",
  "createdAt": "2018-10-06 06:29:16",
  "clientId": "SumsubClient",
  "inspectionId": "5bb8563c0a975a5e6b322ecd",
  "externalUserId": "someClientUserId",
  "info": {
    "firstName": "John",
    "lastName": "Smith",
    "dob": "2000-03-04",
    "placeOfBirth": "London",
    "country": "GBR",
    "phone": "+449112081223"
  },
  "env": "test-api",
  "requiredIdDocs": {
    "country": "GBR",
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": ["PASSPORT", "ID_CARD", "DRIVERS"]
      }
    ]
  },
  "review": {
    "createDate": "2018-12-10 16:26:45+0000",
    "reviewDate": "2018-12-10 16:27:29+0000",
    "reviewResult": {
      "reviewAnswer": "RED",
      "rejectLabels": ["BLACKLIST"],
      "reviewRejectType": "FINAL"
    },
    "reviewStatus": "completed",
    "notificationFailureCnt": 0
  }
}

# Sharing applicants between partner services

Sometimes our clients partner with each other and want to simplify and speed up verification for their users when they have passed KYC once via Sum&Substance.

Assume a user A passed KYC in service X, and is now registering at the partner service Y. If X agrees to share information about A with Y, it can be done as follows:

• X generates a share token and passes it to Y
• Y calls our API with the share token and receives an applicant for user A (with all its data and documents) on their account

# Generating a share token

POST /resources/accessTokens/-/shareToken?applicantId={applicantId}&forClientId={clientId}

# Example of getting a share token (done by X)

## applicantId and Y's client ID must be provided
 curl -X POST \
    'https://test-api.sumsub.com/resources/accessTokens/-/shareToken?applicantId=5ce412012b4da877b2d910bd&forClientId=CoolCoinLtd'

# Example response

{
  "token": "_act-460a698b-d2bc-4cbc-9456-5f36fee38083",
  "forClientId": "CoolCoinLtd"
}

# REQUEST ARGUMENTS

# RESPONSE

Share token in the token field of the returned JSON (see example).

# Importing an applicant

# Example of importing an applicant (done by Y)

 curl -X POST \
    'https://test-api.sumsub.com/resources/applicants/-/import?shareToken=_act-0b8a43f6-b70f-4ad3-bda9-7ce904589380'

# Example response

{
    // Applicant in service Y
    "id": "5d08a63239b79354a2ebaa1d",
    "createdAt": "2019-06-18 10:52:02",
    "clientId": "CoolCoinLtd",
    ...
}

POST /resources/applicants/-/import?shareToken={shareToken}

# REQUEST ARGUMENTS

# RESPONSE

Applicant entity in service Y. Note a new applicant ID returned in the response. Bind it in your system as needed.

# Resetting an applicant

In very rare cases, it is required to change the status of the applicant to init. For example, if a user has contacted support with a request to re-pass verification. Or if the applicant has been rejected with FINAL reviewRejectType and needs to be allowed to re-upload the documents.

POST /resources/applicants/{applicantId}/reset

# REQUEST ARGUMENTS

# Example request

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5d6f821b0a975a0b8aa27b27/reset'

# Example response

{
  "ok": 1
}

# Changing top-level info

This method patches top-level applicant info like email, externalUserId, sourceKey, type for specified applicantId. The body must contain only those fields that you intend to change. Null fields will be ignored.

PATCH /resources/applicants/

# REQUEST BODY

# Example request

curl -X PATCH \
    'https://test-api.sumsub.com/resources/applicants/' \
    -H 'Content-Type: application/json' \
    -d '{"id":"5e9ad53d0a975a656d67e4d0","externalUserId":"1983114","email":"[email protected]"}'

# Example response

{
  "id": "5e9ad53d0a975a656d67e4d0",
  "createdAt": "2020-04-18 10:23:57",
  "inspectionId": "5e9ad53d0a975a656d67e4d1",
  "externalUserId": "1983114",
  "email": "[email protected]",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "ID_CARD",
          "PASSPORT",
          "DRIVERS"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ],
        "videoRequired": "liveness"
      }
    ]
  },
  "review": {
    "createDate": "2020-04-18 10:25:53+0000",
    "expireDate": "2020-04-18 10:40:53+0000",
    "reviewStatus": "init"
  },
  "lang": "en",
  "type": "individual"
}

# Import applicants

This method is intended for data import. For example, in case if you already got a lot of applicants and want to recheck or maintain data consistency.

POST /resources/applicants/-/ingestCompleted

# REQUEST ARGUMENTS

# Example request

curl -X POST 'https://test-api.sumsub.com/resources/applicants/-/ingestCompleted' \
  -H 'Content-Type: application/json' \
  -d '{
	  "externalUserId": "someClientUserId",
	  "info": {
		"firstName": "John",
		"lastName": "Snow",
	  },
	  "review": {
		"elapsedSincePendingMs": 100,
		"elapsedSinceQueuedMs": 50,
		"createDate": "2019-10-21 08:25:32+0000",
		"reviewDate": "2019-10-21 08:25:36+0000",
		"startDate": "2019-10-21 08:25:35+0000",
		"reviewResult": {
			"moderationComment": "",
			"clientComment": "",
			"reviewAnswer": "GREEN"
		},
		"reviewStatus": "completed"
	  },
	  "requiredIdDocs": {
		  "docSets": [{
				"idDocSetType": "IDENTITY",
				"types": [
					"PASSPORT",
					"ID_CARD",
					"DRIVERS"
				]
			  }
		  ]
	  }
  }'

# Example response

{
  "ok": 1
}

# Set risk level for the applicant

This method allows you to set a risk level for your applicant by your own criteria.

POST /resources/applicants/$applicantId/riskLevel/entries

Please note that you should have special permission to make this request (contact the Sum&Substance tech team).

# REQUEST BODY

# Example request

curl -X POST 'https://test-api.sumsub.com/resources/applicants/5edbe3460a975a259dd2f993/riskLevel/entries' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"Danger!","riskLevel":"high"}'

# Example response

{
  "riskLevel": "high",
  "entries": [
    {
      "id": "5eda11960a975a6de48b5c08",
      "createdAt": "2020-06-05 09:34:14",
      "comment": "Danger!",
      "riskLevel": "high"
    }
  ]
}

# Webhooks

We can send webhooks not only via HTTP request, but also as notifications in Slack, Telegram or via email.

# Webhooks types

Example applicantReviewed webhook payload you can find here.

# Example applicantCreated webhook payload:

{
  "applicantId": "5c9e177b0a975a6eeccf5960",
  // inspection ID that contains a result
  "inspectionId": "5c9e177b0a975a6eeccf5961",
  // an ID to debug in case of unexpected errors (should be provided to Sum&Substance)
  "correlationId": "req-63f92830-4d68-4eee-98d5-875d53a12258",
  "externalUserId": "externalUserId",
  // type of webhook (see the corresponding section)
  "type": "applicantCreated",
  "reviewStatus": "init",
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Example applicantPending webhook payload:

{
  "applicantId": "5c7791f80a975a1df426b9e9",
  "inspectionId": "5c7791f80a975a1df426b9ea",
  "correlationId": "req-4af54c06-6a50-4cb9-a7dc-b94b2f5b07eb",
  "externalUserId": "externalUserId",
  "type": "applicantPending",
  "reviewStatus": "pending",
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Example applicantOnHold webhook payload:

{
  "inspectionId": "5d10ca4e0a975a1c4cc30bbb",
  "correlationId": "req-a98abc30-a5d9-4e1d-bab4-2f1af64bd5a5",
  "externalUserId": "12672",
  "reviewStatus": "onHold",
  "applicantId": "5d10ca4e0a975a1c4cc30bba",
  "type": "applicantOnHold",
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Example applicantPersonalInfoChanged webhook payload:

{
  "applicantId" : "5ede51230a975a19a19ba5c1",
  "inspectionId" : "5ede51230a975a19a19ba5c2",
  "applicantType" : "individual",
  "correlationId" : "req-60103dee-79f1-43f4-bdcc-eb2554556afa",
  "externalUserId" : "msdk2-demo-android-d6d5e717-9fa8-4c2b-950f-1c6c9435cb9a",
  "type" : "applicantPersonalInfoChanged",
  "reviewResult" : {
    "reviewAnswer" : "GREEN"
  },
  "reviewStatus" : "completed",
  "createdAt" : "2020-06-08 19:39:29+0000"
}

# Example applicantPrechecked webhook payload:

{
  "applicantId": "5d1f2914c2d75a1c14130bd2",
  "inspectionId": "5d1f2914c2d75a1c14130bd3",
  "correlationId": "req-e9d77142-59e6-4713-9b07-9b342cc51dda",
  "externalUserId": "12672",
  "type": "applicantPrechecked",
  "reviewStatus": "queued",
  "createdAt": "2020-02-21 13:23:19+0000"
}

# Testing on the test environment

On a test environment you can try receiving results via applicantReviewed webhooks by triggering the following endpoint (provide either GREEN or RED to simulate a positive or negative answer, correspondingly):

POST /resources/applicants/{applicantId}/status/testCompleted

# REQUEST ARGUMENTS

# REQUEST BODY

# RESPONSE

In the case of HTTP response 200, you may ignore the response body.

# Example request to change the applicant status to GREEN

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5bb8cca10a975a624903cf65/status/testCompleted' \
  -H 'content-type: application/json' \
  -d '{
   "reviewAnswer" : "GREEN",
   "rejectLabels": []
  }
'

# Example request to change the applicant status to RED

curl -X POST \
  'https://test-api.sumsub.com/resources/applicants/5bb8cca10a975a624903cf65/status/testCompleted' \
  -H 'content-type: application/json' \
  -d '{
          "reviewAnswer": "RED",
          "moderationComment": "We don't accept screenshots. Please upload an original photo.",
          "clientComment": "Screenshots are not accepted.",
          "reviewRejectType": "RETRY",
          "rejectLabels": ["UNSATISFACTORY_PHOTOS","SCREENSHOTS"]
      }
'

# Example response

{
  "ok": 1
}

# Verifying webhook sender

In order to make sure that a webhook is sent by us, we have the possibility to sign it with the HMAC Sha1Hex algorithm. If you want to utilize this feature, we need to agree on a secret key that will be used for signing the HTTP webhook body. To compute digest correctly, you need to convert the HTTP webhook body into bytes and then perform calculations. The header x-payload-digest will be added to the webhook. In order to verify that a webhook is sent by us, you compute the same digest using the HTTP body and a secret key and compare it to the digest value that we've sent to you.

In order to check that you compute the digest the same way we do, you can call the following endpoint.

POST /resources/inspectionCallbacks/testDigest?secretKey={secretKey}

# REQUEST ARGUMENTS

# RESPONSE

# Example request to get digest

curl -X POST \
  'https://test-api.sumsub.com/resources/inspectionCallbacks/testDigest?secretKey=SoMe_SeCrEt_KeY' \
  -H 'Content-Type: text/plain' \
  -d 'someText'

# Example response

{
  "digest": "34fbf271ecf2b6a0712025de9f83c484405283e2"
}

# Example request to client's endpoint

curl -X POST \
  'https://callbackurl.com/kyc' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicantId": "5cb56e8e0a975a35f333cb83",
    "inspectionId": "5cb56e8e0a975a35f333cb84",
    "correlationId": "req-ec508a2a-fa33-4dd2-b93d-fcade2967e03",
    "externalUserId": "12672",
    "type": "applicantReviewed",
    "reviewResult": {
        "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed",
    "createdAt": "2020-02-21 13:23:19+0000"
}'

# Example of computing digest on JS

export function checkDigest(req): boolean {
 const calculatedDigest = crypto
  .createHmac('sha1', SUMSUB_PRIVATE_KEY)
  .update(req.rawBody)
  .digest('hex')

 return calculatedDigest === req.headers['x-payload-digest']
}