External Onboarding Services

Edit on Github Send Feedback develop

Onboarding Server can call services exposed by the entity to extend the KYC process. These services need to be implemented by the client, so the documentation below describes API requirements, not existing services.

Authentication

Onboarding server optionally supports HTTP Basic Auth when calling external services.

Authorization: Basic <credentials>

If you choose to secure your API, credentials (username and password) have to be configured at onboarding server.

API URL

When calling API, endpoint URL is constructed from configured “base path” and fixed “resource uri”

$BASE_PATH/$RESOURCE_URI

BASE_PATH cointains protocol, domain and optionally port or prefixes (like “api” or “version” etc.)
RESOURCE_URI containes fixed endpoint URI (see respective endpoint description)

Example API URL:

https://my.great.api/api/v1/client/approve

For Onboarding Server configuration BASE_PATH value is needed.

HTTP Headers

Header	Optional	Description
Content-Type: application/json	false	Defines request MIME type
X-Correlation-Id: < id >	true	Defines transaction ID
X-Request-Id: < id >	true	Defines request ID

Optional headers can be configured to different names.

Error Handling

Onboarding Server uses following format for error response body, accompanied by an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down), following ERROR codes may be returned:

Error Code	HTTP Code	Description
ERROR_GENERIC	400	Issue with a request format or issue of the business logic
ERROR_UNAUTHORIZED	401	Unauthorized request

All error responses that are produced by the Onboarding Server have the following body:

{
  "errorCode": "ERROR_GENERIC",
  "message": "An error message"
}

API Endpoints

Optional RESTful API services called by Onboarding Server:

post /client/approve Onboarding Approval Service

Service for onboarding process approval.

Request

{
    "processId": "String",
    "processType": "String",
    "userId": "String",
    "identityVerificationId": "String",
    "provider": "String",
    "status": "String",
    "score": Number,
    "presenceCheckResult": {
      "frame": "String"
    }
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`userId`	`String`	ID of a user stored on onboarding process.
`identityVerificationId`	`String`	ID of the identity verification subprocess.
`provider`	`String`	Name of the configured external biometry provider. For example, `iProov`.
`status`	`String`	Status of the identity verification process, `SUCCESS` or `FAILURE`.
`score`	`Number`	Outcome confidence of the verification check on scale 0-10.
`presenceCheckResult.frame`	`String`	Photo/image from the biometry session, encoded in base64.

Response

{
  "result": "String",
  "resultReason": null
}

Attribute	Type	Description
`result`	`String`	The approval outcome OK, NOK and WAIT. Process should either continue (OK), or fail/reset (NOK) or WAIT for asynchronous evaluation.
`resultReason`	`String`	The reason is used when result is NOK to disclose the reason of failed process (for example user started new identity verification subprocess).

post /user/lookup User Lookup Service

Service to identify the prospect and assign user identifier.

Request

{
    "processId": "String",
    "processType": "String",
    "identification": Object # Dictionary/Hashmap
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`identification`	`Object`	The credentials passed from the mobile app. This attribute should be defined as dictionary/hashmap with free-form object type. Keys in the dictionary can differ depending on use-case on specific instance. Example value `{"clientNumber": "String","birthDate": "String"}`

Response

{
  "userId": "String",
  "consent": "String",
  "consentRequired": Boolean # Deprecated
}

Attribute	Type	Description
`userId`	`String`	The bank assigned ID for the user being onboarded.
`consent`	`String`	Tells if the user has to consent the onboarding (REQUIRED/NOT_REQUIRED) or if it’s not evaluated by backend (NOT_EVALUATED or `null`).
`consentRequired (deprecated)`	`Boolean`	Tells if the user has to consent the onboarding.

post /client/evaluate Client Evaluation Service

Service to evaluate data from the scanned documents.

NOTE: Currently triggered only in positive result.

Request

{
    "processId": "String",
    "processType": "String",
    "userId": "String",
    "identityVerificationId": "String",
    "provider": "String",
    "status": "String",
    "score": Number,
    "documentCheckResult": {
        "documents": [
            {
                "type": "String",
                "status": "String",
                "data": {
                    "givenNames": "String",
                    "surname": "String",
                    "dateOfBirth": "String",
                    "placeOfBirth": "String",
                    "sex": "String",
                    "nationality": "String",
                    "personalNumber": "String",
                    "documentNumber": "String",
                    "dateOfIssue": "String",
                    "dateOfExpiry": "String",
                    "authority": "String"
                },
                "images": [
                    {
                        "type": "String",
                        "data": "String"
                    }
                ],
                "rawData": Object
            }
        ]
    }
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`userId`	`String`	ID of a user stored on onboarding process.
`identityVerificationId`	`String`	ID of the identity verification subprocess.
`provider`	`String`	Name of the configured external document provider: ZenID or Microblink.
`status`	`String`	Status of the identity verification process, `SUCCESS` or `FAILURE`.
`score`	`Number`	Outcome confidence of the verification check on scale 0-10.
`documentCheckResult.documents`	`Array`	Array of documents containing all mined data.
`documentCheckResult.documents.type`	`String`	Document type, eg. `ID_CARD`, `PASSPORT`, `DRIVING_LICENCE`.
`documentCheckResult.documents.status`	`String`	Status of the identity verification process for specific document, `SUCCESS` or `FAILURE`.
`documentCheckResult.documents.data`	`Object`	Selected normalized data extracted from the document. See `documentCheckResult.documents.rawData` for complete results. Date values are in ISO 8601 format `YYYY-MM-DD` (e.g. `2010-01-21`).
`documentCheckResult.documents.images`	`Array`	Array of images extracted from the document.
`documentCheckResult.documents.images.type`	`String`	Image type, e.g. `FACE`.
`documentCheckResult.documents.images.data`	`String`	JPEG binary data encoded using `base64`.
`documentCheckResult.documents.rawData`	`Object`	Complete response from verification provider with verification status, performed checks and extracted data.

Response

{
  "result": "String",
  "resultReason": null
}

Attribute	Type	Description
`result`	`String`	The approval outcome OK, NOK and WAIT. Process should either continue (OK), or fail/reset (NOK) or WAIT for asynchronous evaluation.
`resultReason`	`String`	The reason is used when result is NOK to disclose the reason of failed process (for example user started new identity verification subprocess).

post /otp/send OTP Delivery Service

Service to send generated OTPs.

Request

{
    "processId": "String",
    "processType": "String",
    "userId": "String",
    "language": "String",
    "otpCode": "String",
    "otpType": "String",
    "resend": Boolean
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`userId`	`String`	ID of a user stored on onboarding process.
`language`	`String`	The language used by the mobile app in ISO 639-1 format.
`otpCode`	`String`	OTP generated by the system.
`otpType`	`String`	Static value ACTIVATION.
`resend`	`Boolean`	Indication if the code is send for first time or resend is requested.

Response

{
  "otpSent": Boolean
}

Attribute	Type	Description
`otpSent`	`Boolean`	Boolean value indicating if the OTP was sent.

post /consent/storage Consent Storage Service

Service providing the storage of provided consents.

Request

{
    "processId": "String",
    "processType": "String",
    "userId": "String",
    "consentType": "String",
    "approved": Boolean
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`userId`	`String`	ID of a user stored on onboarding process.
`consentType`	`String`	Type of the consent configured for the process.
`approved`	`Boolean`	User approval or rejection.

Response

post /consent/text Consent Text Service

Service providing the text of the consent.

Request

{
    "processId": "String",
    "processType": "String",
    "userId": "String",
    "consentType": "String",
    "language": "String"
}

Request Params

Attribute	Type	Description
`processId`	`String`	ID of an onboarding process.
`processType`	`String`	Type of the onboarding process.
`userId`	`String`	ID of a user stored on onboarding process.
`consentType`	`String`	Type of the consent configured for the process.
`language`	`String`	The language used by the mobile app in ISO 639-1 format.

Response

{
  "consentText": "String"
}

Attribute	Type	Description
`consentText`	`String`	Consent text in HTML format in the requested language.

Last updated on Jan 26, 2026 (12:53) Edit on Github Send Feedback