Curata API

Security

The Curata API uses X-API-Key header principals to secure the API for authorised use. The key will be generated and provided during the onboarding phase. Additionally, the API key is used to track API requests associated with billing.

To connect to and interact with the API, your individual X-API-Key must be provided in calls to the API.

Usage

The API Key must be included in the HTTP header for every request, example:

• X-API-Key: abcdef12345

Postman example:

Endpoints

The Curata API contains the following endpoints:

1. POST: generatedynamiclink - api version 1

2. POST: generatedynamiclink - api version 2

3. GET: consent

POST: Generate dynamic link v1

• UAT URL: https://uatcurataservicesapi.comcorp.co.za/api/v1/generatedynamiclink

• PROD URL: https://curataservicesapi.comcorp.co.za/api/v1/generatedynamiclink

This endpoint generates a tokenised link for the customer. The Generate Dynamic Link endpoint expects a JSON-encoded request body. A JSON response will be returned by the endpoint, which includes the link and a reference number generated by the Curata system, for auditing and tracing purposes.

Request composition

Example request message

{
    "consumerBusinessUnitId":"d05b75ba-6d80-ea11-8119-00155d64810e",
    "consumerReference":"abcde123456",
    "verificationType":2,
    "identityNo":"1234567890123",
    "firstName":"John",
    "surname":"Doe",
    "purpose":"Vehicle Finance",
    "consent":[
      {
         "description":"Account Verification"         
      }
   ]
}

Operational fields

The body of the POST request to generatedynamiclink consists of the following fields:

• consumerBusinessUnitId | guid | not-null |: Your unique Consumer Business Unit Id. Value provided during onboarding process. Used to identify you and cross referenced with provided XAPI Key

• consumerReference | string | not-null |: Reference of your choice. Will be returned to you by the response service. Can be used to track calls on your side. Not used by Comcorp.

• verificationType | int | not-null |: Choice of verification types. Choices are:

  • 1 - Identity verification + Verified Consent.

  • 2 - Identity verification only.

• identityNo | int | not-null |: Identity number of the subject person.

• firstName | string | not-null |: Firstname of the subject person.

• surname | string | not-null |: Surname of the subject person.

• purpose | string | not-null |: Purpose of this transaction. -verificationAttemptsAllowed | int | nullable |: Amount of times a user is allowed to retry liveness process before process terminates with the appropriate response message.

• consent | string | nullable | *only supplied when verificationType=1 : List of consent items to be presented to the subject in Curata Web (ui). Must match list of consent items set up during onboarding. May contain only a subset (or none) of the configured consent items. This item is not required when using verificationType=2.

Response composition

The following response object will be returned by the generatedynamiclink endpoint on a status of 200(OK).

Example response message

{
"reference": 10000001,
"link": " https://comcorp.curata.co.za/DJdFKUa2",
"embedded": "https://curatanucleus.comcorp.co.za/embedded/DJdFKUa2",
"token": "DJdFKUa2"
}

Response fields

The body of the response will consist of the following:

• reference | long | not-null |: Unique dynamic link master reference. This value will be used by Comcorp to track this transaction.

• link | string | not-null |: Link for Curata process, to be provided by you to the subject person.

• embedded | string | not-null |: Link optimised for embedded process of Curata. For information see the section on embedding.

• token | string | not-null |: Token used by the curata system to uniquely identify the current session. Returned to you for reference purposes. Either this field or the reference field can be provided to Comcorp for troubleshooting purposes.

POST: Generate dynamic link v2

• UAT URL: https://uatcurataservicesapi.comcorp.co.za/api/v2/generatedynamiclink

• PROD URL: https://curataservicesapi.comcorp.co.za/api/v2/generatedynamiclink

Version two of the generatedynamiclink API allows for an extended and more configurable use of Curata, under Comcorp's Curata Plus product. This version of the API extends on the existing API V1 and allows for more fields as listed below.

Up front DHA calls

With version 2 of the API, when specified by the PrefetchDHAflag, the process of calling the DHA can be moved up front as opposed to calling the DHA after the user has interacted with Curata. This gives the Consumer more control over the Curata process and better handling of potential DHA downtimes.

DHA Prefetch Process

Request composition

Example request message

{
  {
  "ConsumerBusinessUnitId": "",
  "ConsumerReference": "abcde123456",
  "VerificationType": 2,
  "IdentityNo": "1234567890123",
  "FirstName": "",
  "Surname": "",
  "Purpose": "",
  "VerificationAttemptsAllowed": 0,
  "ReferenceImage": "/9j/4AAQSkZJAAc6gAAABAAAAAAA...",
  "PrefetchDHA": false,
  "BypassDHA": false,
  "UseDocUploaded": false,
  "ResponseFields": {
    "IncludeCapturedImage": true,
    "IncludeDocument": true,
    "IncludeDocumentData": true,
    "IncludeExtractedImage": false,
    "IncludeUploadedDocumentImage": false
  },
  "UploadedDocType": 0,
  "VerifyUploadedDoc": false,
  "UploadedDocCountryOfOrigin": "ZAF"
 }
}

Fields

The body of the POST request to generatedynamiclink v2 is described below. Note, fields up to consent is described in the section Operational Fields of generatedynamiclink v1.

Note: some of the fields below are configured for you by Comcorp, allowing you to have a default behaviour. Should you wish to then override this configuration, the following fields may be presented in the body of the generatedynamiclink v2 request.

Input parameters/fields

• ReferenceImage | string | null or empty | : Reference image to be used during matching process. When PrefetchDha is true, ReferenceImage will be used in case no data is returned from DHA.

• PrefetchDHA | boolean | may be omitted | : A boolean indicating if Curata should attempt to fetch data from the Department of Home Affairs (DHA) before issuing the dynamic link. If data cannot be retreived from DHA, and no referenceImage or UseDocUpload options were specified, the endpoint will fail with an appropriate failure reason.

• BypassDHA | boolean | may be omitted | : A boolean indicating if verification should skip the DHA process, in stead relying on provided reference image or docupload.

• UseDocUploaded | boolean | may be omitted | : When specified as true, the Curata User Interface will ask the individual being verified to upload a valid Identity Document.

• VerifyUploadedDoc | boolean | may be omitted |: When specified, provides option to either verify the uploaded user ID document, or to skip this test. *Note: For current version of Curata, this step is always performed, and setting this as "false" will not skip the process.

• UploadedDocType | integer | may be omitted |: Not currently used.

• UploadedDocCountryOfOrigin | string | may be omitted |: Not currently used.

ResponseFields (Nested Object)

Response fields are used to customise the response submitted back to the consumer. Note: the combination of requested Input parameters vs ResponseFields may cause validation to fail if impossible combinations are requested (eg. IncludeExtractedImage=true but UseDocUpload=false)

• IncludeCapturedImage: |optional| Boolean flag to include one of the images captured during the liveness process.

• IncludeDocument: |optional| Boolean flag to include the Curata Certificate PDF document in the response.

• IncludeDocumentData: |optional| Boolean flag to include the Curata Certificate data in a raw format in the response.

• IncludeExtractedImage: |optional| Boolean flag to include the extracted image from the document obtained via UseDocUpload in the response.

• IncludeUploadedDocumentImage: |optional| Boolean flag to include the original uploaded document image obtained via UseDocUpload in the response.

GET: consent

• UAT URL: https://uatcurataservicesapi.comcorp.co.za/api/v1/consent

• PROD URL: https://curataservicesapi.comcorp.co.za/api/v1/consent

This endpoint fetches a JSON list of consent types that is configured on the Curata system for a specific Business Unit. This list can be used to populate the consent property of the request in "Generate Dynamic Link v1 or "Generate Dynamic Link v2 with a verificationType of 1.

The X-API key supplied in the header will be used to identify the Business Unit in question.

Example response message:

{
    [
        "Account Verification",
        "Payslip",
        "Bank Statement"
    ]
}