Customers

Customers represent the people who submit support tickets. Each customer is identified by their email address, which must be unique within your tenant.

List Customers

GET /api/v1/external/customers

Returns a paginated list of customers.

Query Parameters

Parameter	Type	Default	Description
per_page	integer	25	Results per page (max: 100)
cursor	string	—	Cursor for next page
search	string	—	Search by name or email

Example Request

GET /api/v1/external/customers?search=jane&per_page=10

Example Response

{
  "data": [
    {
      "id": "01912345-0000-7abc-def0-123456789abc",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "phone": "+1-555-0123",
      "metadata": {
        "company": "Acme Inc",
        "plan": "professional"
      },
      "ticket_count": 12,
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "per_page": 10,
    "has_more": false,
    "next_cursor": null
  }
}

Create a Customer

POST /api/v1/external/customers

Request Body

Field	Type	Required	Description
email	string	Yes	Unique email address
name	string	No	Display name
phone	string	No	Phone number
metadata	object	No	Custom key-value pairs

Example Request

{
  "email": "bob@example.com",
  "name": "Bob Wilson",
  "phone": "+1-555-0456",
  "metadata": {
    "company": "Widget Co",
    "plan": "enterprise",
    "account_id": "ACC-12345"
  }
}

Example Response (201 Created)

{
  "data": {
    "id": "01912345-4444-7abc-def0-123456789abc",
    "email": "bob@example.com",
    "name": "Bob Wilson",
    "phone": "+1-555-0456",
    "metadata": {
      "company": "Widget Co",
      "plan": "enterprise",
      "account_id": "ACC-12345"
    },
    "ticket_count": 0,
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Duplicate Email

If a customer with the given email already exists, you'll receive a 409 Conflict:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": [
      { "field": "email", "message": "The email has already been taken." }
    ]
  }
}

Hint: You don't need to create customers before creating tickets. When you submit a ticket with a customer email that doesn't exist, Tiqora creates the customer automatically.

Get a Customer

GET /api/v1/external/customers/{customer_id}

Example Response

{
  "data": {
    "id": "01912345-0000-7abc-def0-123456789abc",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "phone": "+1-555-0123",
    "metadata": {
      "company": "Acme Inc",
      "plan": "professional"
    },
    "ticket_count": 12,
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Update a Customer

PATCH /api/v1/external/customers/{customer_id}

Update one or more customer fields. Only the fields you include in the request are updated.

Request Body

Field	Type	Description
email	string	Update email (must be unique)
name	string	Update display name
phone	string	Update phone number
metadata	object	Merge with existing metadata

Example: Update Name and Metadata

{
  "name": "Jane Smith-Johnson",
  "metadata": {
    "plan": "enterprise"
  }
}

Example Response

{
  "data": {
    "id": "01912345-0000-7abc-def0-123456789abc",
    "email": "jane@example.com",
    "name": "Jane Smith-Johnson",
    "phone": "+1-555-0123",
    "metadata": {
      "company": "Acme Inc",
      "plan": "enterprise"
    },
    "ticket_count": 12,
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

Using Metadata

The metadata field is a flexible JSON object where you can store any custom data about your customers. Common uses:

{
  "metadata": {
    "company": "Acme Inc",
    "plan": "enterprise",
    "account_id": "ACC-12345",
    "region": "us-east",
    "signup_date": "2024-06-15",
    "mrr": 299.00,
    "feature_flags": ["beta_dashboard", "api_v2"]
  }
}

Hint: Metadata is great for storing context from your own systems. This data is visible to agents in the dashboard, helping them provide better support without switching between tools.

Best Practices

1. Pre-create customers with metadata — While tickets auto-create customers, pre-creating them with rich metadata (company, plan, account ID) gives your support team better context.

2. Keep metadata up to date — Use webhooks or periodic syncs to keep customer metadata in Tiqora aligned with your own system.

3. Use search for lookups — The search parameter matches against both email and name, making it easy to find customers without knowing their exact ID.