New article
Recently updated
Creating clients via API
Who is this article for?
Administrators who want to learn to create clients via the API.
Administrator permissions are required.
This article explains how to create clients using the API endpoint, including request formatting and field requirements.
Understanding the endpoint
The POST /api/v1/clients endpoint requires a bearer token for authentication. This endpoint is create-only, meaning if a client name already exists in the tenant, it will not be updated.
Formatting the request
To create clients, send a POST request with the following JSON structure:
{
"clients": [
{
"name": "Acme Pvt Ltd",
"clientReference": "ACM002",
"userEmail": null,
"userGroupName": null
},
{
"name": "Globex Pvt Corp",
"clientReference": "GLX0033"
}
]
}Understanding request fields
The following table describes each field in the request:
| Field | Required | Notes |
|---|---|---|
| name | Yes | Client name. Uniqueness is determined by name, not clientReference. [TEST CLIENT] is reserved. |
| clientReference | No | Maximum 30 characters |
| userEmail | No | Adds specific users for client security. Use comma- or pipe-separated emails to grant access (restricted client). Unknown emails produce a warning. |
| userGroupName | No | Adds user groups for client security. Use comma- or pipe-separated group names to grant access. Unknown groups produce a warning. |
Understanding the success response
A successful request returns a 200 OK status with the following response structure:
{
"tenantId": 1,
"saved": 2,
"results": [
{
"name": "Acme Pvt Ltd",
"clientReference": "ACM002",
"clientId": 16,
"action": "Added",
"message": null,
"warnings": []
}
]
}The response includes the tenant ID, number of clients saved, and detailed results for each client creation attempt, including any warnings.