Specification
Customers
Customers API calls
Used to create, edit and archive customers.
When creating payments you can either submit a payment record with the customer details or create a customer here and then assign a customer_id to a payment record.
Create
API call to create new customer(s) as single or batch records.
Path
POST /customers/create
Request Body
{
"records": [{
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
},
"customer_status_lookups_id": "loo_abc123...",
}]
}
Response Body
{
"status": true,
"results": [{
"id": "cus_abc123...",
"customer_status_lookups_id": "loo_abc123...",
"deleted_at": null,
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | cus_abc123... |
| reference | Y | String(35) | Reference to identify a specific customer | CLN240919000001 |
| company_name | C | String(64) | Either a company name OR person name and surname must be provided. Company name is used when collection is made from a specific company. DebiCheck only works with individuals, not companies. | Superior Meteor Corp |
| person_name | C | String(32) | Name of the person to be collected from. Required for DebiCheck mandates. | John |
| person_surname | C | String(32) | Surname of the person to be collected from. Required for DebiCheck mandates. | Doe |
| id_type_lookups_id | C | String(32) | Required field for DebiCheck. Lookups ID relating to the type of ID number e.g. South African ID, passport or temporary residence | loo_abc123... |
| id_number | C | String(13) | Required field for DebiCheck. ID number relating to the ID type | 900112... |
| N | String(128) | Valid email address of the person to be collected from | johndoe@mail.com | |
| contact_number | C | String(16) | Mobile contact number of the person to be collected from. Must include the area code. Required for DebiCheck mandates | +27831234567 |
| billing_address_line_1 | N | String(128) | First line of address for the person to be collected from. Should be the street address if no complex number is applicable. | 145 Superior Complex |
| billing_address_line_2 | N | String(128) | Second line of address for the person to be collected from. Should be the street address if a complex was used on line 1. | 541 New River Road |
| city_or_town | N | String(64) | City/Town where address lines 1 and 2 are located in. | Pretoria |
| postal_code | N | Integer | Postal code related to address lines 1 and 2. | 1285 |
| metadata | N | JSON | Any additional meta data | {} |
| customer_status_lookups_id | n/a | String(32) | Status of customer from the lookups table. | loo_abc123... |
| created_at | n/a | Datetime | Date and time record was created | 2024-02-27 09:11:23 |
Update
API call to update existing customer(s) as single or batch records. Records can not be deleted, only archived.
Path
POST /customers/update
WARNINGWhen updating customer details it will not update a DebiCheck mandate, to update mandates check the mandates section.
If you archive/disable a customer then it will not cancel a DebiCheck mandate. A customer can not be archived/disabled if you have running payments for the customer you need to stop the related payments first.
Likewise customer updates will only update the connected payments if those payments are running EFT debit orders and not DebiCheck.
Request Body
Only include fields you wish to change (besides id used to find the record). Setting a column to null e.g. city_or_town = null will clear that fields value if allowed
{
"records": [{
"id": "cus_abc123...",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"customer_status_lookups_id": "loo_abc123...",
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}]
}
Response Body
{
"status": true,
"results": [{
"id": "cus_abc123...",
"customer_status_lookups_id": "loo_abc123...",
"deleted_at": null,
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | Y | String(32) | Record id to update | cus_abc123... |
| reference | Y | String(35) | Reference to identify a specific customer | CLN240919000001 |
| company_name | C | String(64) | Either a company name OR person name and surname must be provided. Company name is used when collection is made from a specific company. DebiCheck only works with individuals, not companies. | Superior Meteor Corp |
| person_name | C | String(32) | Name of the person to be collected from. Required for DebiCheck mandates. | John |
| person_surname | C | String(32) | Surname of the person to be collected from. Required for DebiCheck mandates. | Doe |
| id_type_lookups_id | C | String(32) | Required field for DebiCheck. Lookups ID relating to the type of ID number e.g. South African ID, passport or temporary residence | loo_abc123... |
| id_number | C | String(13) | Required field for DebiCheck. ID number relating to the ID type | 900112... |
| N | String(128) | Valid email address of the person to be collected from | johndoe@mail.com | |
| contact_number | C | String(16) | Mobile contact number of the person to be collected from. Must include the area code. Required for DebiCheck mandates | +27831234567 |
| billing_address_line_1 | N | String(128) | First line of address for the person to be collected from. Should be the street address if no complex number is applicable. | 145 Superior Complex |
| billing_address_line_2 | N | String(128) | Second line of address for the person to be collected from. Should be the street address if a complex was used on line 1. | 541 New River Road |
| city_or_town | N | String(64) | City/Town where address lines 1 and 2 are located in. | Pretoria |
| postal_code | N | Integer | Postal code related to address lines 1 and 2. | 1285 |
| customer_status_lookups_id | n/a | String(32) | Status of customer from the lookups table. | loo_abc123... |
| created_at | n/a | Datetime | Date and time record was created | 2024-02-27 09:11:23 |
| updated_at | n/a | Datetime | Date and time record was last updated | 2024-02-27 09:11:23 |
List
List customers loaded on the platform.
Path
GET /customers/list?{params}
Query Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| customer_status_lookups_id | String(32) | N | Filter for a specific customer status. Lookups type must be 'customer_status'. | loo_abc123... |
| date_start | Date(YYYY-MM-DD) | N | Filter for records that have a created date after this date specified. | 2024-09-13 |
| date_end | Date(YYYY-MM-DD) | N | Filter for records that have an created date before this specified date | 2025-04-24 |
Response Body
{
"status": true,
"results": [{
"id": "cus_abc123...",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"id_type_lookups_id": "loo_abc123...",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"customer_status_lookups_id": "loo_abc123...",
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
},
"updated_at": "2024-03-17 12:35:24",
"created_at": "2024-02-27 09:11:23",
}, ...]
}