# 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 ```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. ## 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" ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.comcorp.co.za/biometric-authentication/curata-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.