Resources

Customers

Manage your customer (contact) records.

The Customer object represents a person you support -- the requester of tickets and the recipient of emails and campaigns. Customers can be organized into contact groups.

Create or update a customerPOST/v1/customers

Permission: write. If a customer with the same email already exists, the existing record is updated with the name, phone and metadata you provide instead of creating a duplicate (returns 200 instead of 201). When updating, metadata replaces the stored object.

Field	Type	Required	Description
email	string	Yes	Customer email address.
name	string	No	Display name. Defaults to the local part of the email on creation.
phone	string	No	Phone number.
metadata	object	No	Arbitrary JSON metadata. Default: {}.
group	string	No	Name of an active contact group (case-insensitive match). Adds the customer to this group.

terminal

Bash

01curl https://api.tickos.dev/v1/customers \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{
05    "email": "jane@example.com",
06    "name": "Jane Doe",
07    "phone": "+1234567890",
08    "metadata": { "company": "Acme Inc" },
09    "group": "VIP Customers"
10  }'

UTF-8 · LF · Bashtickos.dev

Returns the customer object plus group: { id, name } when the customer was added to (or already belonged to) the group, or null when no group was given. If the group is not found among your active groups, the customer is still created or updated and the response includes group: null and a warning field (for example: Group "VIP" not found. Customer was created but not added to any group.)

List customersGET/v1/customers

Permission: read. Ordered by created_at, newest first. Query params: email (partial, case-insensitive match), limit (default 50, max 100) and offset. Returns { data: [...], pagination: { limit, offset, total } }.

Get a customerGET/v1/customers/{id}

Permission: read. Returns the customer record with its tickets embedded. Each ticket includes id, client_id, subject, status, priority and created_at.

Query param	Description
include	Comma-separated extra data. surveys: CSAT surveys of the customer (newest first). emails: the last 50 emails linked to the customer (id, direction, from_address, to_address, subject, status, related_type, related_id, created_at). Default: surveys. Passing include replaces the default, so use include=surveys,emails to get both.

terminal

Bash

01curl 'https://api.tickos.dev/v1/customers/cst-xxxxxxxx?include=surveys,emails' \
02  -H 'Authorization: Bearer sk_your_api_key'

UTF-8 · LF · Bashtickos.dev

Returns 404 if the customer does not exist in your account.

Update a customerPATCH/v1/customers/{id}

Permission: write. Accepts name, email, phone, metadata and group. Only provided fields are updated (metadata replaces the stored object). Sending no recognized field returns 400. Returns the customer plus group: { id, name } | null.

group on PATCH

On PATCH, group must match the group name exactly (case-sensitive). If no group matches, the request still succeeds and the customer is not added to any group: the response has group: null and no warning. PATCH only adds the customer to a group; it never removes existing memberships.

Delete a customerDELETE/v1/customers/{id}

Permission: admin. Permanently deletes the customer record. Returns { deleted: true, id }.

Implicit creation

You rarely need to create customers upfront: creating a ticket with customer_email creates the customer automatically if it does not exist yet. Sending an email with POST /v1/emails also links (or creates) a customer for the first recipient.

Blocking

Blocked customers (is_blocked: true) cannot open new tickets: POST /v1/tickets returns HTTP 403 when the customer_id or customer_email belongs to a blocked customer. Blocked customers are also excluded from campaigns. Blocking and unblocking is done from the dashboard; the API does not change the blocked state.

PreviousEmails Next Campaigns