Curata response service

Overview

The Curata Response Service submits the outcomes of the biometric verification process of an applicant back to the Consumer. To achieve this, a receiving API on the end of the Consumer is required.

This API requires and endpoint with a JSON-encoded request body with the fields defined below. The response of this service does not require a payload to be returned, only a status code in the success range (200 – 299) is required. All standard HTTP response codes, authentication, and verbs must be implemented by the receiving API. All requests will be made over HTTPS.s

Consumer API requirements

Method: POST

URL: To be supplied to Comcorp. This is the endpoint that would need to be exposed for us to send the response message to upon completion of the Curata process.

Consumer API security

Curata supports the ability to integrate using a variety of header based authentication methods. The preferred method however, is to use an X-API-Key header method for authorisation.

Curata response content

The content of the response will vary according to the version of Requesting API used, see Curata API for more details on the different versions.

For convenience, we'll devide this section into two, first detailing a normal generatedynamiclink v1 response, and then go into more detail on the differences when using generatedynamiclink v2.

Response when using generatedynamiclink v1

Unless otherwise configured, the following default response content will be sent by the Curata Response service.

Response when using generatedynamiclink v2

When using version 2 of generatedynamiclink, it is possible to request for - and receive - additional fields. Depending on the combination of your configuration with Comcorp and the additional fields requested, it is possible to obtain the full payload as depicted below:

Field summary

  • consumerReference | string | not-null |: Reference provided by the user to track calls. Not used by Comcorp.

  • consumerBusinessUnitId | guid | not-null |: Unique ID for the Consumer Business Unit. Provided during onboarding.

  • transactionStatusId | int | not-null |: Numeric code of the transaction status. See Transaction Statuses for more information

  • transactionStatus | string | not-null |: Text description of the transaction status.

  • consent | array | not-null | *only supplied when verificationType=1 : List of consent items for the transaction, including:

    • description | string | not-null |: Description of the consented item (e.g., "Payslip").

    • consented | boolean | not-null |: Indicates whether consent was given for the item.

  • idRequestedVsIdReturned | string | nullable |: Status indicating whether the requested ID number matches the ID number extracted from the uploaded document.

  • documentValidationStatus | string | nullable |: Status indicating the result of the Document Validation step.

  • document | string (Base64) | nullable | *only supplied when IncludeDocumentData=true in generatedynamiclink request OR configured by Comcorp : Base64 encoded PDF document for Curata Certificate.

  • hanisReference | guid | nullable |: Unique reference number from the HANIS system. Will be empty if DHA was bypassed.

  • dhaConsumerReference | string | not-null |: Reference number from the Department of Home Affairs.

  • livenessAttempts | int | not-null |: Number of liveness verification attempts made.

  • documentData | object | not-null | *only supplied when IncludeDocumentData=true in generatedynamiclink request OR configured by Comcorp : JSON representation of the data returned from DHA used in creating the PDF certificate. Includes the fields:

    • curataReference | int | not-null |: Internal reference for the document.

    • nameRequested | string | not-null |: Name submitted for verification.

    • nameReturned | string | nullable |: Name returned by Home Affairs.

    • surnameRequested | string | not-null |: Surname submitted for verification.

    • surnameReturned | string | nullable |: Surname returned by Home Affairs.

    • identityNo | string | not-null |: Identity number of the subject person, returned by Home Affairs.

    • countryOfBirth | string | nullable |: Country where the subject was born.

    • idCardIssued | string | nullable |: Indicates if an ID card was issued ("Yes" or "No").

    • idBookDateIssued | string (date) | nullable |: Date when the ID book was issued.

    • idCardDateIssued | string (date) | nullable |: Date when the ID card was issued.

    • deceasedStatus | string | nullable |: Indicates if the subject is deceased ("Yes" or "No").

    • gender | string | nullable |: Gender of the subject (e.g., "Male").

    • maritalStatus | string | nullable |: Marital status of the subject (e.g., "Married").

    • dateOfMarriage | string (date) | nullable |: Date of marriage, if applicable.

    • hanisReference | guid | nullable |: Unique reference number from the HANIS system. Will be empty if DHA was bypassed.

    • hanisRetrievalDate | string (datetime) | not-null |: Date and time when the HANIS record was retrieved.

    • digitalIdStatus | string | not-null |: Status of the digital ID verification process (e.g., "Successful").

  • extractedDocumentData | object | not-null | *only supplied when IncludeExtractedDocumentData=true in generatedynamiclink request OR configured by Comcorp: JSON representation of data extracted directly from the provided identity document using OCR, including:

    • curataReference | int | not-null |: Internal reference for the extracted document data.

    • initials|string | nullable |: Initials extracted from a driver's license, if available.

    • initialsWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted initials.

    • names |string | nullable |: First name(s) extracted from the document.

    • namesWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted first name(s).

    • surname | string | nullable |: Surname extracted from the document.

    • surnameWordConfidence | decimal (0.000 - 1)| nullable |: Confidence score for the extracted surname.

    • identityNumber | string | nullable |: Identity number extracted from the document.

    • identityNumberWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted identity number.

    • passportNumber | string | nullable |: Passport number extracted from a passport, if available.

    • passportNumberWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted passport number.

    • licenseNumber| string | nullable |: License number extracted from a driver's license, if available.

    • licenseNumberWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted license number.

    • dateOfBirth | string (date) | nullable |: Date of birth extracted from the document.

    • dateOfBirthWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted date of birth.

    • nationality | string | not-null |: Nationality extracted from the document (ISO 3166-1 alpha-3 code).

    • nationalityWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted nationality.

    • sex | string | nullable |: Gender extracted from the document (e.g., "M" or "F").

    • sexWordConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted gender.

    • dateOfIssue | string (date) | nullable l |: Date when the document was issued.

    • dateOfIssueConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted date of issue.

    • dateOfExpiry | string (date) | nullable |: Expiry date of the document.

    • dateOfExpiryConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted expiry date.

    • countryOfIssue| string | nullable |: Country of issue for the extracted driver's license, if available.

    • countryOfIssueConfidence | decimal (0.000 - 1) | nullable |: Confidence score for the extracted driver's license.

    • digitalIdStatus | string | nullable |: Status of the digital ID verification process (e.g., "Successful").

  • documentValidationResults | object | nullable | Contains the results of validation checks performed on the uploaded document. *Note: In most cases below, the isValid field should not be used verbatim, rather, the probability should be used and interpreted.

    • metadataCheckPass | object | nullable | Indicates whether the metadata check passed.

      • isValid | boolean | nullable | Indicates whether the document passed the metadata check.

      • status | string | nullable | Descriptive interpretation of check results, forwarded from Comcorp's provider.

    • greyScaleCheckPass | boolean | nullable | *Deprecated. Indicates whether the grayscale check passed.

    • photocopyCheckPass | object | nullable | Indicates probability of the document being a photocopy of an original.

      • isValid | boolean | nullable | Indicates whether the document passed the photocopy check.

      • status | string | nullable | Descriptive interpretation of probability, forwarded from Comcorp's provider.

      • probability | int | nullable | Represents the probability (percentage) that the document is a photocopy of an original.

    • recapturedCheckPass | object | nullable | Indicates the probability of the document being a screencapture or photo-of-a-photo of the original.

      • isValid | boolean | nullable | Indicates whether the document passed the recaptured check.

      • status | string | nullable | Descriptive interpretation of probability, forwarded from Comcorp's provider..

      • probability | int | nullable | Represents the probability (percentage) that the document is a screencapture or photo-of-a-photo of the origina.

    • spliceDetectionCheckPass | object | nullable | Indicates probability of image being spliced.

      • isValid | boolean | nullable | Indicates whether the document passed the splice detection check.

      • status | string | nullable | Descriptive interpretation of probability, forwarded from Comcorp's provider..

      • probability | int | nullable | Represents the probability (percentage) that the document is spliced.

    • securityZoneCheckPass | object | nullable | Contains result of security zone checks.

      • isValid | boolean | nullable | Indicates whether the document passed the security zone check.

      • status | string | nullable | Descriptive interpretation of security zone check results, forwarded from Comcorp's provider.

      • probability | int | nullable | Represents the probability (percentage) that the document didn't pass security zone checks.

    documentValidationError | string | nullable | Contains any error message related to the document validation process. Null if no errors occurred.

  • capturedImage | string (Base64) | nullable |: Base64 encoded image captured during the Curata verification process.

  • extractedImage | string (Base64) | nullable | *only supplied when IncludeExtractedImage=true in generatedynamiclink request : Base64 encoded image extracted from the ID Document photo.

  • uploadedDocumentImage | string (Base64) | nullable | *only supplied when IncludeUploadedDocumentImage=true in generatedynamiclink request : Base64 encoded image of the original uploaded document.

  • matchingImageUsed | string | not-null |: Base64 encoded image of the image used to match against the capturedImage. Used by consumer to differentiate between referenceImage or extractedImage used for matching if both was supplied.

  • backImage| string (Base64) | nullable | *only supplied when IncludeUploadedDocumentImage=true in generatedynamiclink request : Base64 encoded image of the back of the original uploaded document.

Transaction statuses

One of he following transaction statuses will be returned in the transactionStatusId and transactionStatus fields respectively.

Status ID
Message

1

Successful

2

Liveness Failed

3

No Image available at Source Image Provider

4

Source Image Provider Unavailable

5

One to One Match Failed

6

Validation Error

7

Internal System Error

8

Partial Match

9

Consent Declined for Source Image Provider (Liveness)

10

Consent Declined for Data/Documents

11

Provider System Error

12

No Camera Detected

13

No Camera Access Provided

14

Face Extraction Failed

15

Link Expired - Liveness Failed

Status ID 15 is returned when a user accesses a link, fails the liveness check, and does not complete the process within the configured expiration time. Note that this status is only processed at 15 minute intervals. So the maximum time to wait for such a response will be: configured-expiration-time + 15 minutes.

Configuration concepts

The response received by the Consumer may be customised by one, or both, of the following ways:

  1. Comcorp managed configuration.

  2. Request-time configuration.

1. Comcorp managed configuration

Comcorp can configure your response to always be returned in a certain way. The following is a list of fields that can be returned or omitted. Note that this configuration will always be maintained unless overridden by the responseFields field in the generatedynamiclink request.

  • PDF Document: document field is present in Curata response payload. *Note: This field will always be configured to return by default during the onboarding process

  • Document Data: documentData field is present in Curata response payload.

  • Captured Image: capturedImage field is present in Curata response payload.

2. Request-time configuration

At any time the response can be customised when making a request to the generatedynamiclink endpoint. See Curata API for more information when requesting this way. Specifying the response fields in this way will override any configuration managed by Comcorp. Note that at this time, the only way to receive certain fields will be to specify them during this step, as this feature extends on the configuration offered by Comcorp.

The following fields may be present based on the configuration issued when requesting:

  • IncludeCapturedImage = true : capturedImage field is present in Curata response payload.

  • IncludeDocument = true : document (PDF Document) field is present in Curata response payload.

  • IncludeDocumentData = true : documentData field is present in Curata response payload.

  • IncludeExtractedImage = true : extractedImage field is present in Curata response payload. *Only if UseDocUpload flag was specified during request

  • IncludeUploadedDocumentImage = true : uploadedDocumentImage field is present in Curata response payload. *Only if UseDocUpload flag was specified during request

PreviousCurata APINextEmbedding Curata

Last updated