📄Identity Validation v1.1

Validate the authenticity of South African ID documents in real time.

This API performs data comparisons using the Customer's details that were provided in the POST Create New Customer endpoint.

📸 Image Quality Recommendations

To ensure accurate and reliable ID document validation:

• Use high-resolution images.

• Ensure the document is flat, well-lit, and free from reflections or shadows.

• Avoid any obstructions or fingers covering key parts of the document.

• Capture the entire document without cropping edges.

• For best results, prefer documents in the following order of accuracy: id_card > id_book > drivers_licence

This is the sequence of steps you need to follow to validate a Customer's ID Document:

1. POST Upload Identity Document (v1.1)

2. GET Identity Document Validation (v1.1)

---

POST Upload Identity Document (v1.1)

POST {{baseUrl}}/api/v1.1/identity-documents/upload-document

The Identity Validation module has been included in Gathr v1.1. Ensure your integration handles versioning appropriately.

If you are using the {{baseUrl}} variable, you’ll need to manually update or override it to point to the correct version. Base URL: {{environmentUrl}}/{{tenantId}}/api/v1.1

Path Parameters

Name	Type	Description
customer_id*	text	This is UUID for a specific customer that gets generated and returned in the POST Create New Customer response.
type*	text	The type of Identity Document you would like to upload to complete the ID Validation against. We support 3 types of South African ID Documents, id_card, id_book, drivers_licence
front*	file	Upload the front image or PDF of the ID document. *Required for all document types.
back*	file	Upload the front image or PDF of the ID document. *Required for id_card and drivers_licence.

API Responses

200 - OK

The response id is the identity_id for the subsequent validation api call.

{
  "data": {
    "id": "{{identityDocumentId}}",
    "type": "id_card",
    "front": {
      "id": 17832,
      "name": "idcard_front.jpeg",
      "type": "jpg",
      "url": "https://example.com/documents/idcard_front.jpeg"
    },
    "back": {
      "id": 17833,
      "name": "idcard_back.jpeg",
      "type": "jpg",
      "url": "https://example.com/documents/idcard_back.jpeg"
    },
    "valid": false
  }
}

422 - Unprocessible Entity

The error indicates that the information given is incorrect/incomplete

Only the front of the ID is uploaded

{
    "errors": {
        "back": [
            "The back field is required."
        ]
    }
}

Only the back of the ID is uploaded

{
    "errors": {
        "front": [
            "Please upload the front of your document."
        ]
    }
}

ID Document format is incorrect (eg. word)

{
    "errors": {
        "front": [
            "Front must be an image or PDF (jpg/png/pdf)."
        ],
        "back": [
            "Back must be an image or PDF (jpg/png/pdf)."
        ]
    }
}

No ID Document uploaded

{
    "errors": {
        "front": [
            "Please upload the front of your document."
        ],
        "back": [
            "The back field is required."
        ]
    }
}

500 - Server Error

Internal server error - contact [e-mail].

[
 {
   "errors": {
        "code": "error_verifying_identity”
        "message": " Please contact [e-mail]."
    }
 }
]

---

GET Identity Document Validation (v1.1)

GET {{baseUrl}}/api/v1.1/identity-documents/:identity_id/validate

Path Parameters

Name	Type	Description
identityDocumentId*	String	This the UUID that gets generated in the response of POST Upload Identity Document V1.1

API Responses

The validation_source indicates the method used to extract and validate the data from the submitted ID document. Possible validation sources: barcode_39, barcode_417, ocr

200 - OK

A true value indicates a match between the document and Customer data.

{
  "data": {
    "id": "identity_document_uuid",
    "type": "id_card",
    "idValidation": {
      "outcome_id_validation": {
        "idNumberMatch": true,
        "firstNamesMatch": true,
        "surnameMatch": true,
        "sexMatch": true,
        "countryMatch": true,
        "citizenshipMatch": true,
        "idCardStructureMatch": true
      },
      "validation_source": "barcode_39"
    }
  }
}

422 - Unprocessible Entity

The error indicates that the information given is incorrect/incomplete.

{
    "data": {
        "id": "72762b23-bc65-4f7a-93e3-fc57f5ea8b80",
        "type": "id_card",
        "idValidation": {
            "outcome_id_validation": {
                "errors": {
                    "validation_source": "The ID document could not be processed. Please ensure the ID document is clear, unobstructed, and of good quality."
                }
            },
            "validation_source": ""
        }
    }
}

500 - Server Error

Internal server error - contact [e-mail].

[
 {
   "errors": {
        "code": "server_error”
        "message": " Please contact [e-mail]."
    }
 }
]