4. API-Based Integration

4.1 API Prerequisites

4.2 API Authentication

Every Sumsub API request requires the following headers:

Signature Format

payload = bytes(timestamp + METHOD + path + body)
signature = HMAC_SHA256(secretKey, payload) -> lowercase hex

Rules

• METHOD must be uppercase, for example GET, POST, or PATCH.
• path must include the query string and must start with /.
• For multipart/form-data, sign the exact bytes sent on the wire.
• For bodyless requests, omit the body from the signed payload.

4.3 API Flow Summary

1. 1

   Create applicant with full fixedInfo and metadata.

   POST/resources/applicants?levelName=payblr-kyc-individuals-poa-batch
2. 2

   Upload ID front.

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

   Upload ID back, when required.

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

   Check PoA status.

   GET/resources/applicants/{applicantId}/requiredIdDocsStatus
5. 5

   Upload dedicated PoA if still required.

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

   Upload selfie.

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

   Submit questionnaire.

   POST/resources/applicants/{applicantId}/questionnaires
8. 8

   Preflight required steps.

   GET/resources/applicants/{applicantId}/requiredIdDocsStatus
9. 9

   Request review.

   POST/resources/applicants/{applicantId}/status/pending
10. 10

    Await result.

    GET polling or webhook/resources/applicants/{applicantId}/status or applicantReviewed webhook

4.4 API Flow Diagram

The sequence below shows how the client system, Sumsub, and Payblr interact during API-based verification.

4.5 Create Applicant with Full fixedInfo

Recommended single-shot approach: send the applicant profile, address, TIN, and required metadata in the create applicant request. A follow-up PATCH /fixedInfo is optional and normally used only when correcting or refreshing an existing applicant.

POST /resources/applicants?levelName=payblr-kyc-individuals-poa-batch
Content-Type: application/json
X-App-Token: <token>
X-App-Access-Ts: <unix-seconds>
X-App-Access-Sig: <signature>

{
  "externalUserId": "user-92847-unique",
  "email": "anna.krause@example.com",
  "phone": "+491701234567",
  "lang": "en",
  "metadata": [
    { "key": "sourceKey", "value": "<payblr-assigned-source-key>" },
    { "key": "partnerName", "value": "Payblr-YourCompany" },
    { "key": "cardHolderId", "value": "ch-92847" },
    { "key": "customerPartnerId", "value": "user-92847" }
  ],
  "fixedInfo": {
    "firstName": "Anna",
    "middleName": "Marie",
    "lastName": "Krause",
    "dob": "1990-05-15",
    "country": "DEU",
    "tin": "12345678901",
    "addresses": [
      {
        "street": "Musterstrasse 1",
        "town": "Berlin",
        "state": "Berlin",
        "country": "DEU",
        "postCode": "10115"
      }
    ]
  }
}

Expected response: 201 with the Sumsub applicant ID. Save that value as applicantId.

4.6 Optional PATCH fixedInfo

PATCH /resources/applicants/{applicantId}/fixedInfo is optional when the create applicant call already includes complete fixedInfo.

Use it when:

• Updating profile, address, or TIN on an existing applicant.
• Retrying after corrected data.
• Resuming a partially completed submission.

4.7 Upload Documents

Each file is sent as a separate multipart/form-data request.

POST /resources/applicants/{applicantId}/info/idDoc
Content-Type: multipart/form-data; boundary=----...
X-Return-Doc-Warnings: true

Form Parts

Common Metadata Examples

{
  "idDocType": "ID_CARD",
  "country": "DEU",
  "idDocSubType": "FRONT_SIDE"
}

{
  "idDocType": "ID_CARD",
  "country": "DEU",
  "idDocSubType": "BACK_SIDE"
}

{
  "idDocType": "UTILITY_BILL",
  "country": "DEU"
}

{
  "idDocType": "SELFIE",
  "country": "DEU"
}

4.8 Submit Questionnaire

POST /resources/applicants/{applicantId}/questionnaires
Content-Type: application/json

Request body:

{
  "id": "beforeWeFinishWeJust",
  "sections": {
    "workAndIncome": {
      "items": {
        "occupation": { "value": "Analyst" },
        "industryYouWorkFor": { "value": "Finance and Insurance" },
        "workStatus": { "value": "Full Time" }
      }
    },
    "section2": {
      "items": {
        "sourceOfFunds": { "value": "Salary" },
        "expectedMonthVolume": { "value": "$0 - $1,999" },
        "expectedAnnualIncome": { "value": "$50,000 - $74,999" }
      }
    },
    "cardholderAgreementA": {
      "items": {
        "cardTermsConditionsAccept": { "value": "true" }
      }
    }
  }
}

Expected response: 200 on success.

4.9 Preflight: Required Steps Status

GET /resources/applicants/{applicantId}/requiredIdDocsStatus

Inspect the response before moving the applicant to pending. Every required step should show as fulfilled. If a step is incomplete, Sumsub may not process the review correctly.

Use this call in integration tests and logging.

4.10 Request Review

Move the applicant to pending when all required data, documents, and questionnaire answers have been submitted.

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

Optional Query Parameter

?reason=Your+reason+string

Expected response: 200 when the applicant is queued for automated or manual review.

4.11 Get Review Result

GET /resources/applicants/{applicantId}/status

Example Completed Response

{
  "reviewStatus": "completed",
  "reviewResult": {
    "reviewAnswer": "GREEN",
    "reviewRejectType": null,
    "rejectLabels": []
  }
}

Review Answer Values

Review Reject Type Values

Next steps