Customers

Customers represent the people who submit support requests to your organization. On this page, we will dive into the different customer endpoints you can use to manage customers programmatically. We will look at how to create, retrieve, update, delete, and list customers.

The customer model

The customer model contains all the information about your customers, including their email, name, and any custom metadata you want to store.

Properties

Name
id
Type
string
Description
Unique identifier for the customer (UUID).
Name
email
Type
string
Description
Customer email address (unique per organization).
Name
name
Type
string
Description
Customer display name.
Name
external_user_id
Type
string
Description
Your system user ID for this customer.
Name
external_organization_id
Type
string
Description
Your system organization/company ID for this customer.
Name
external_organization_name
Type
string
Description
Your system organization/company name for this customer.
Name
avatar_url
Type
string
Description
URL to the customer avatar image.
Name
metadata
Type
object
Description
Arbitrary JSON metadata stored with the customer.
Name
ticket_count
Type
integer
Description
Number of tickets created by this customer.
Name
created_at
Type
timestamp
Description
Timestamp of when the customer was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the customer was last updated.

POST/api/v1/customers

Create a customer

Creates a new customer in your organization.

Required scope: customers:write

Required attributes

Name
email
Type
string
Description
Customer email address (must be unique per organization).

Optional attributes

Name
name
Type
string
Description
Customer display name.
Name
external_user_id
Type
string
Description
Your system user ID.
Name
external_organization_id
Type
string
Description
Your system organization/company ID.
Name
external_organization_name
Type
string
Description
Your system organization/company name.
Name
metadata
Type
object
Description
Arbitrary JSON metadata to store with the customer.

Request

POST

/api/v1/customers

curl -X POST https://api.supportstation.io/api/v1/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Smith",
    "external_user_id": "user_789",
    "metadata": {
      "plan": "enterprise",
      "mrr": 500
    }
  }'

Response

{
  "data": {
    "id": "customer-uuid",
    "email": "[email protected]",
    "name": "Jane Smith",
    "external_user_id": "user_789",
    "external_organization_id": null,
    "external_organization_name": null,
    "avatar_url": null,
    "metadata": {
      "plan": "enterprise",
      "mrr": 500
    },
    "ticket_count": 0,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

GET/api/v1/customers

List all customers

Returns a paginated list of customers in your organization.

Required scope: customers:read

Query parameters

Name
page
Type
integer
Description
Page number (default: 1).
Name
limit
Type
integer
Description
Items per page, max 100 (default: 20).
Name
search
Type
string
Description
Search in email or name.

Request

GET

/api/v1/customers

curl -G https://api.supportstation.io/api/v1/customers \
  -H "Authorization: Bearer {token}" \
  -d search=jane \
  -d limit=20

Response

{
  "data": [
    {
      "id": "customer-uuid",
      "email": "[email protected]",
      "name": "Jane Smith",
      "external_user_id": "user_789",
      "external_organization_id": null,
      "external_organization_name": null,
      "avatar_url": null,
      "metadata": {
        "plan": "enterprise",
        "mrr": 500
      },
      "ticket_count": 5,
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "total_pages": 3
    }
  }
}

GET/api/v1/customers/:id

Retrieve a customer

Returns a single customer by their ID.

Required scope: customers:read

Request

GET

/api/v1/customers/:id

curl https://api.supportstation.io/api/v1/customers/customer-uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "customer-uuid",
    "email": "[email protected]",
    "name": "Jane Smith",
    "external_user_id": "user_789",
    "external_organization_id": null,
    "external_organization_name": null,
    "avatar_url": null,
    "metadata": {
      "plan": "enterprise",
      "mrr": 500
    },
    "ticket_count": 5,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

PATCH/api/v1/customers/:id

Update a customer

Updates a customer information. All fields are optional.

Required scope: customers:write

Optional attributes

Name
email
Type
string
Description
New email address (must be unique per organization).
Name
name
Type
string
Description
Updated display name.
Name
external_user_id
Type
string
Description
Updated external user ID.
Name
external_organization_id
Type
string
Description
Updated external organization ID.
Name
external_organization_name
Type
string
Description
Updated external organization name.
Name
avatar_url
Type
string
Description
URL to the customer avatar image.
Name
metadata
Type
object
Description
Updated metadata (replaces existing metadata).

Request

PATCH

/api/v1/customers/:id

curl -X PATCH https://api.supportstation.io/api/v1/customers/customer-uuid \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "metadata": {
      "plan": "enterprise",
      "mrr": 1000
    }
  }'

Response

{
  "data": {
    "id": "customer-uuid",
    "email": "[email protected]",
    "name": "Jane Doe",
    "external_user_id": "user_789",
    "external_organization_id": null,
    "external_organization_name": null,
    "avatar_url": null,
    "metadata": {
      "plan": "enterprise",
      "mrr": 1000
    },
    "ticket_count": 5,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T14:00:00.000Z"
  }
}

DELETE/api/v1/customers/:id

Delete a customer

Deletes a customer from your organization. This action cannot be undone.

Required scope: customers:write

Deleting a customer will not delete their associated tickets. The tickets will remain but will no longer be linked to a customer.

Request

DELETE

/api/v1/customers/:id

curl -X DELETE https://api.supportstation.io/api/v1/customers/customer-uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true
}