Managing Clients
Overview
This section offers request samples and details for managing clients through our API.
Partners have clients, and these clients can be utilized to create users within the system. However, the primary significance of clients lies in their role in creating Templates. Clients are directly associated with tokenization templates, which means that each client can have specific templates based on their needs. These templates are crucial for managing and applying tokenization processes, ensuring that the correct settings and configurations are used for each client's data handling requirements.
Ensure that your user role has the necessary permissions to perform these operations. For more information, refer to the Hierarchy Diagram of Organizations.
For requests with additional settings, consult the API Reference.
Creating a Client
As stated in the Introduction, the Client Level is directly linked to the Partner so it requires a directPartner as one of the parameters, including either its id or name: optimally both.
Request
POST /api/v1/clients
{
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
},
"body": {
"name": "Test Client 2",
"isActive": false,
"directPartner": {
"id": 792,
"name": "partnerName"
},
"contact": {
"id": 2666,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
}
}
}
Response
In response, we receive the id of the newly created client. This can also be reused to Get a Client.
{
"id": 872
}
Getting Clients
To retrieve a summarized list of all clients, you must specify the partner. This approach helps narrow down the results to clients associated with a particular partner.
Request
GET /api/v1/clients?partner=partnerName
{
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
}
}
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
partner | string/integer | Yes | Filter the list by Partner. The parameter value can be either a Partner ID or Name. |
take | integer | No ( Default: 10) | The number of entries to include in the list. It starts from skip. |
skip | integer | No ( Default: 0 ) | The number of results to skip before listing entries. |
Response
{
"total": 2,
"data": [
{
"id": 744,
"name": "Test Client",
"mid": null,
"isActive": true,
"version": 0,
"partner": {
"id": 792,
"name": "partnerName"
},
"directPartner": {
"id": 792,
"name": "partnerName"
},
"contact": {
"id": 2664
},
"billingId": "cba321"
},
{
"id": 872,
"name": "Test Client 2",
"mid": null,
"isActive": false,
"version": 0,
"partner": {
"id": 792,
"name": "partnerName"
},
"directPartner": {
"id": 792,
"name": "partnerName"
},
"contact": {
"id": 2664
},
"billingId": null
}
]
}
Retrieving an individual client will provide additional meta-data such as contact, created, and modified information. These are covered in the following sub-section.
Getting a Client
Request
Note
The
{id}value in the path is theidof the client to get.
GET /api/v1/clients/{id}
{
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
}
}
Response
{
"id": 872,
"name": "Test Client 2",
"mid": null,
"isActive": false,
"created": "2024-08-13T16:51:24.000Z",
"modified": "2024-08-13T16:51:24.000Z",
"version": 0,
"partner": {
"id": 792,
"name": "partnerName"
},
"directPartner": {
"id": 792,
"name": "partnerName"
},
"contact": {
"id": 2666,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
},
"billingId": null
}
Response Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
id | integer | The Client's unique identifier. | 872 |
name | string | The Client's name. Must be unique. | "Test Client 2" |
mid | string | Some Partners will have an merchant ids on their own software offerings. This is an open field that allows those Partner associate a Client resource with their Merchant Identifier. | "merchantId123" |
isActive | boolean | This property indicates if the Client account is active or disabled. It is not possible to delete Clients, however their account can be set to inactive. | false |
created | string | Creation timestamp in ISO 8601 format. | "2024-08-13T16:51:24.000Z" |
modified | string | Last modified timestamp in ISO 8601 format. Overwritten by Updating Client. | "2024-08-13T16:51:24.000Z" |
version | integer | The number of times that the client has been updated. | 1 |
partner | object | This can be either the parent partner of the directPartner or, in cases where Sub-Partner trees are expanded, the root partner. The reference can contain either the ID or Name. With GET API calls, both of these are included. | { "id": 792, "name": "partnerName" } |
directPartner | object | This is the direct partner associated with the client be it a Sub-Partner or a Partner. The reference can contain either the ID or Name. With GET API calls, both of these are included. | { "id": 792, "name": "partnerName" } |
contact | object | This is the user data, which is receives by Getting a User. Here, id is the id of the user: /api/v1/users/id. | { "id": 2666, "firstName": "WATERFORD", "lastName": "Example", "email": "[email protected]" } |
billingId | string | ? | "cba321" |
location | integer | Location ID |
Updating a Client
Unlike the process for Creating a Client, not all body parameters are mandatory, as some fields may not require updates in every situation
Request
Note
The
{id}value in the path is theidof the client to update.
PATCH /api/v1/clients/{id}
{
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
},
"body": {
"name": "Updated Test Client 2",
"isActive": false,
"directPartner": {
"id": 793,
"name": "newPartnerName"
},
"contact": {
"id": 2666,
"firstName": "WATERFORD",
"lastName": "Example",
"email": "[email protected]"
}
}
}
For all the request parameters, see API Reference.
Response
Same as with Creating a Client, we receive the id of the updated client. This can also be reused to Get a Client to check out our changes if necessary.
{
"id": 872
}
Deleting a Client
Request
Note
The
{id}value in the path is theidof the client to delete.
DELETE /api/v1/clients/{id}
{
"method": "DELETE",
"headers": {
"Content-Type": "application/json",
"Authorization": "Basic Base64(username:password)"
}
}
Responses
200 - Client has been deleted successfully
404 - Not Found
{
"uuid": "e6356050-599d-11ef-ae4c-3d5f4ba36a27",
"errorCode": 7404,
"message": "Requested resource cannot be found."
}
Updated 12 days ago