Customers
REST reference

Customers API

Customer records (deduplicated across channels).

View as Markdown

List customers

GET/v1/customers

Cursor-paginated customers, newest first.

Required scope: customers:read.

Parameters
limitinteger

Page size (1–100).

starting_afterstring

Cursor: the `id` of the last item from the previous page.

statusstring
searchstring

Case-insensitive match over name, email, and phone.

Request
cURL
curl "https://api.asks.app/v1/customers" \
  -H "Authorization: Bearer $ASKS_API_KEY"
Response 200
JSON
{
  "object": "list",
  "data": [
    {
      "object": "customer",
      "id": "string",
      "email": {},
      "phone": {},
      "name": {},
      "avatar_url": {},
      "status": "string",
      "tags": [
        "string"
      ],
      "external_id": {},
      "conversation_count": 1,
      "first_contact_at": {},
      "last_contact_at": {},
      "created_at": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Create or find a customer

POST/v1/customers

Creates a customer, or returns the existing match. At least one of email, phone, or external_id is required.

Required scope: customers:write.

Request body
emailstring
phonestring
namestring
external_idstring
metadataobject
Request
cURL
curl -X POST "https://api.asks.app/v1/customers" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "phone": "string",
    "name": "string",
    "external_id": "string",
    "metadata": {}
  }'
Response 201
JSON
{
  "object": "customer",
  "id": "string",
  "email": {},
  "phone": {},
  "name": {},
  "avatar_url": {},
  "status": "string",
  "tags": [
    "string"
  ],
  "external_id": {},
  "conversation_count": 1,
  "first_contact_at": {},
  "last_contact_at": {},
  "created_at": {}
}

Retrieve a customer

GET/v1/customers/{id}

Required scope: customers:read.

Request
cURL
curl "https://api.asks.app/v1/customers/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY"
Response 200
JSON
{
  "object": "customer",
  "id": "string",
  "email": {},
  "phone": {},
  "name": {},
  "avatar_url": {},
  "status": "string",
  "tags": [
    "string"
  ],
  "external_id": {},
  "conversation_count": 1,
  "first_contact_at": {},
  "last_contact_at": {},
  "created_at": {}
}

Update a customer

PATCH/v1/customers/{id}

Required scope: customers:write.

Request body
emailstring
phonestring
namestring
statusstring

One of: active, inactive, archived.

tagsarray of string
Request
cURL
curl -X PATCH "https://api.asks.app/v1/customers/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "phone": "string",
    "name": "string",
    "status": "active",
    "tags": [
      "string"
    ]
  }'
Response 200
JSON
{
  "object": "customer",
  "id": "string",
  "email": {},
  "phone": {},
  "name": {},
  "avatar_url": {},
  "status": "string",
  "tags": [
    "string"
  ],
  "external_id": {},
  "conversation_count": 1,
  "first_contact_at": {},
  "last_contact_at": {},
  "created_at": {}
}
← Previous
Conversations
Next →
Tickets