➕Create New Customer

A customer is the foundation of almost all Gathr API calls. You will need to create a customer before performing any of the consumer verifications and validations.

Create New Customer

POST{{baseUrl}}/customers

Create a new customer on your Gathr tenant to perform verifications and validations against the customers consumer profile.

You cannot create multiple Customers with the same ID Number on the same Gathr Tenant.

Path Parameters

Name	Type	Description
tenantId*	String	This is the tenantId that was assigned to you when your tenant was created. You will have received this information via message from a member of the Finch Technologies team. If you can't find it, please email [e-mail].
environmentUrl*	String	Environment URL's uat - https://gathr.uat.fincheck.co.za prod - https://gathr.fincheck.co.za *Please note that you need to be set up in each environment by a member of the Finch Technologies team, who will share your bearer token with you for the specific environment in a protected link.

Request Body

Name	Type	Description
id_type*	String	This is the type of identification number you want to create the customer with. The options are: "id_number" "passport" You need to use "id_number" if you wish to get a Credit Report or perform an ID Verification on this customer.
id_number*	String	This is the 13-digit South African ID Number of the Customer you are creating. Each Customer created with "id_type" = "id_number" will need to have a valid ID Number. When id_type "passport" is selected, there is no validation on the Passport Number.
first_name*	String	The Customer's First Name as per their ID Document.
last_name*	String	The Customer's Last Name/Surname as per their ID Document.
email*	String	The Customer's Email Address. It has to be of the format [e-mail]
client_reference*	String	This is a reference that you may use to identify and do a lookup on the Customer in your system. Each Customer needs to have a unique client_reference.
middle_name	String	The customer's Middle Name as per their ID Document.
country	String	The Customer's nationality.
popi*	Boolean	This is used to store whether the Customer has given you Consent under the Protection Of Personal Information (POPI) Act to continue with collecting their data and performing additional verifications in Gathr.
terms_and_conditions	Boolean	This is used to store whether the Customer has agreed to the Terms and Conditions of the Application and Verifications you are performing.

Status Codes

201 - Created

New Customer Successfully Created

{
    "data": {
        "id": "{{customerId}}",
        "client_reference": "clientnumber1",
        "popi": null,
        "terms_and_conditions": null,
        "email": "[e-mail]",
        "id_number": "8511215433085",
        "first_name": "John",
        "middle_name": "Jovonovich",
        "last_name": "Wick",
        "full_name": "John Jovonovich Wick",
        "id_type": "id_number",
        "country": null,
        "initials": "JJW",
        "api_token": {{apiToken}} 
    }
}

401 - Unauthorised

Unauthenticated

{
    "error": "Unauthenticated."
}

409 - Conflict

Duplicate ID Number

{
    "errors": [
        "Duplicate entry '8511215433085' for key 'leads_id_number_unique'"
    ]
}

Duplicate Client Reference

{
    "errors": [
        "Duplicate entry 'custom_01' for key 'leads_client_reference_unique'"
    ]
}

422 - Unprocessable Content

Invalid ID Number

{
    "errors": {
        "id_number": [
            "A valid RSA Id number is required"
        ]
    }
}

Invalid ID Type

{
    "errors": {
        "id_type": [
            "The selected id type is invalid."
        ]
    }
}

Invalid Email Address

{
    "errors": {
        "email": [
            "The email must be a valid email address."
        ]
    }
}

Syntax Error

{
    "errors": {
        "email": [
            "The email field is required when client reference is not present."
        ],
        "id_number": [
            "The id number field is required."
        ],
        "client_reference": [
            "The client reference field is required when email is not present."
        ]
    }
}

Examples

Example Request Body with a valid RSA ID Number

{

        "id_type": "id_number",
        "id_number": "8511215433085",
        "client_reference": "clientnumber1",
        "email": "[e-mail]",
        "first_name": "John",
        "middle_name": "Jovonovich",
        "last_name": "Wick",
        "popi": null,
        "terms_and_conditions": null,
        "country": null
    }
}

Example Request Body with a Passport Number

{

        "email": "[e-mail]",
        "id_type": "passport",
        "id_number": "SA2345",
        "first_name": "John",
        "last_name": "Wick"

    }
}