Customers API
The Customers API lets you sync your own user base with TidySupport. Each customer is identified by your own externalId so you can link conversations and events back to records in your database. These endpoints use your secret API key and do not require a workspace ID in the path — the workspace is inferred from the key.
Authentication
All Customers endpoints require a secret API key with api_user scope in the Authorization header. The workspace is resolved automatically from the key.
Authorization: Bearer ts_sk_live_xxxxxxxxxxxxEndpoints
POST/v1/customers
Creates a new customer. The externalId must be unique within your workspace — this is the ID from your own system.
Request
curl -X POST "https://api.tidysupport.com/v1/customers" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"externalId": "usr_01J8X3Y",
"email": "jane@example.com",
"name": "Jane Doe",
"metadata": { "plan": "pro" }
}'Response
{
"id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
"workspaceId": "wrk_abc123",
"externalId": "usr_01J8X3Y",
"email": "jane@example.com",
"name": "Jane Doe",
"status": "ACTIVE",
"metadata": { "plan": "pro" },
"createdAt": "2026-03-13T10:00:00Z",
"updatedAt": null
}GET/v1/customers
Returns a paginated list of customers in your workspace.
Request
curl "https://api.tidysupport.com/v1/customers?status=ACTIVE&limit=20" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"Response
{
"items": [
{
"id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
"workspaceId": "wrk_abc123",
"externalId": "usr_01J8X3Y",
"email": "jane@example.com",
"name": "Jane Doe",
"status": "ACTIVE",
"metadata": { "plan": "pro" },
"createdAt": "2026-03-13T10:00:00Z",
"updatedAt": null
}
],
"cursor": null,
"hasMore": false
}GET/v1/customers/lookup
Looks up a customer by your own externalId. Useful when you have a user ID from your database and need to find the corresponding TidySupport customer.
Request
curl "https://api.tidysupport.com/v1/customers/lookup?externalId=usr_01J8X3Y" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"GET/v1/customers/{id}
Retrieves a single customer by their TidySupport ID.
Request
curl "https://api.tidysupport.com/v1/customers/ctc_B7OSYsnTUVwBPOGrgYTjvSGS" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"PUT/v1/customers/{id}
Updates a customer. All body fields are optional — only provided fields are updated.
Request
curl -X PUT "https://api.tidysupport.com/v1/customers/ctc_B7OSYsnTUVwBPOGrgYTjvSGS" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "status": "SUSPENDED" }'DELETE/v1/customers/{id}
Permanently deletes a customer and all associated data. This action cannot be undone.
Request
curl -X DELETE "https://api.tidysupport.com/v1/customers/ctc_B7OSYsnTUVwBPOGrgYTjvSGS" \
-H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"Customer Object
Node.js SDK
Use the official server SDK to interact with the Customers API without writing raw HTTP calls.
import { init } from "@tidysupport/node";
const tidysupport = init("ts_sk_live_xxxxxxxxxxxx");
// Create
const customer = await tidysupport.customers.create({
externalId: "usr_01J8X3Y",
email: "jane@example.com",
name: "Jane Doe",
});
// Lookup by your own ID
const found = await tidysupport.customers.getByExternalId("usr_01J8X3Y");
// Update
await tidysupport.customers.update(customer.id, { status: "SUSPENDED" });
// Delete
await tidysupport.customers.delete(customer.id);