> For the complete documentation index, see [llms.txt](https://docs.comcorp.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.comcorp.co.za/biometric-authentication/curata-api.md). # 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 ### ⚠️ Deprecation Notice: Version 1 **The v1 version of Generate Dynamic Link (`api/v1/generatedynamiclink`) has been deprecated** * **Existing Customers:** V1 remains active and supported exclusively for existing integrations to prevent breaking changes. * **New Customers:** All new integrations must use the Generate Dynamic Link V2 (`api/v2/generateddynamiclink`). V2 offers enhanced performance, upfront DHA call capabilities, and improved nested response structures. ## 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 ```json { "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 ```json { "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](/biometric-authentication/embedding-curata.md). * `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 `PrefetchDHA`flag, 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 ```json { { "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](#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. ### Backward Compatibility with V1 If you are migrating from V1 to V2, V2 has been designed to accept your existing data structures with minimal modification. Review the sample mapping below to handle the transition seamlessly. ```json { "ConsumerBusinessUnitId": "d05b75ba-6d80-ea11-8119-00155d64810e", // Casing updated "ConsumerReference": "abcde123456", // Casing updated "VerificationType": 2, "IdentityNo": "1234567890123", "FirstName": "John", "Surname": "Doe", "Purpose": "Vehicle Finance", "VerificationAttemptsAllowed": 0, // Set to 0 for system defaults "ReferenceImage": null, // Pass null or omit if not uploading a face/reference image "PrefetchDHA": false, "BypassDHA": false, "UseDocUploaded": false, "ResponseFields": { // Mandatory nested configuration "IncludeCapturedImage": true, "IncludeDocument": true, "IncludeDocumentData": true, // Ensures you get your core V1 data fields back "IncludeExtractedImage": false, "IncludeUploadedDocumentImage": false }, "UploadedDocType": 0, "VerifyUploadedDoc": false, "UploadedDocCountryOfOrigin": "ZAF" } ``` 💡 **Migration Tip:** To emulate V1 behavior in the V2 endpoint without tapping into new features (like upfront DHA checks or document uploading), explicitly set `PrefetchDHA`, `BypassDHA`, and `UseDocUploaded` to `false`. Additionally, ensure you pass `true` to `IncludeDocumentData` inside the `ResponseFields` object—this guarantees that the core identity data payload you relied on in V1 is returned in the V2 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](#post-generate-dynamic-link-v1) or ["Generate Dynamic Link v2](#post-generate-dynamic-link-v1) 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: ```json { [ "Account Verification", "Payslip", "Bank Statement" ] } ```