Skip to content

Customers

Customers are the people who submit support tickets. Each customer has a profile with contact information, company details, and account metadata.

Endpoints

Method Endpoint Description Scope Required
GET /v1/customers List customers customers:read
GET /v1/customers/{id} Get customer customers:read
POST /v1/customers Create customer customers:write
PATCH /v1/customers/{id} Update customer customers:write
DELETE /v1/customers/{id} Delete customer customers:delete

The Customer Object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "company": "Acme Corp",
  "department": "Engineering",
  "title": "Software Engineer",
  "customer_tier": "tier_1",
  "contact_number": "+1-555-123-4567",
  "pronoun": "he/him",
  "location_country": "United States",
  "location_city": "San Francisco",
  "location_state": "California",
  "location_zip": "94102",
  "location_address": "123 Main St, Suite 500",
  "region": "amer",
  "timezone": "America/Los_Angeles",
  "account_value": "50000.00",
  "has_premium_support": true,
  "is_vip": false,
  "social_linkedin": "https://linkedin.com/in/johndoe",
  "social_website": "https://johndoe.dev",
  "social_github": "https://github.com/johndoe",
  "notes": "Key stakeholder for Q4 renewal.",
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-10T09:00:00Z"
}

Attributes

Field Type Description
id UUID Unique customer identifier
name string Customer's full name
email string Email address (unique per organization)
company string Company name
department string Department within company
title string Job title
customer_tier enum tier_1, tier_2, tier_3, tier_4
contact_number string Phone number
pronoun string Preferred pronouns
location_country string Country
location_city string City
location_state string State/province
location_zip string ZIP/postal code
location_address string Street address
region enum amer, apac, emea, latam, asean
timezone string Timezone identifier
account_value decimal Account monetary value
has_premium_support boolean Premium support tier
is_vip boolean VIP flag
social_linkedin string LinkedIn profile URL
social_website string Personal/company website
social_github string GitHub profile URL
notes string Internal notes (max 1000 chars)
created_at datetime Creation timestamp
updated_at datetime Last modification timestamp

List Customers

Retrieve a paginated list of customers.

GET /v1/customers

Query Parameters

Parameter Type Default Description
skip integer 0 Number of records to skip
limit integer 50 Maximum records to return (max: 100)

Examples

curl -X GET "https://api.toptickets.app/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With pagination
curl -X GET "https://api.toptickets.app/v1/customers?skip=50&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.toptickets.app/v1/customers",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"skip": 0, "limit": 50}
)

Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "is_vip": false,
    "has_premium_support": true
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "is_vip": true,
    "has_premium_support": true
  }
]

Get Customer

Retrieve a single customer with full details.

GET /v1/customers/{customer_id}

Path Parameters

Parameter Type Description
customer_id UUID The customer ID

Examples

curl -X GET "https://api.toptickets.app/v1/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

CUSTOMER_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://api.toptickets.app/v1/customers/{CUSTOMER_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response

Returns the full customer object.

Create Customer

Create a new customer.

POST /v1/customers

Request Body

Field Type Required Description
name string Yes Full name (max 255 chars)
email string Yes Email address (must be unique)
company string No Company name
department string No Department
title string No Job title
customer_tier enum No Tier classification
contact_number string No Phone number
pronoun string No Preferred pronouns
location_* string No Location fields
region enum No Business region
timezone string No Timezone
account_value decimal No Account value
has_premium_support boolean No Premium support (default: false)
is_vip boolean No VIP status (default: false)
social_* string No Social profile URLs
notes string No Internal notes (max 1000 chars)

Examples

curl -X POST "https://api.toptickets.app/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "Acme Corp",
    "customer_tier": "tier_1",
    "has_premium_support": true
  }'

import requests

response = requests.post(
    "https://api.toptickets.app/v1/customers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "John Doe",
        "email": "john.doe@example.com",
        "company": "Acme Corp",
        "customer_tier": "tier_1",
        "has_premium_support": True
    }
)

Response (201 Created)

Returns the created customer object.

Update Customer

Update an existing customer. All fields are optional.

PATCH /v1/customers/{customer_id}

Path Parameters

Parameter Type Description
customer_id UUID The customer ID

Request Body

Any field from the customer object can be updated. Only include fields you want to change.

Examples

curl -X PATCH "https://api.toptickets.app/v1/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_vip": true,
    "notes": "Upgraded to VIP status after contract renewal."
  }'

import requests

CUSTOMER_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.patch(
    f"https://api.toptickets.app/v1/customers/{CUSTOMER_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "is_vip": True,
        "notes": "Upgraded to VIP status after contract renewal."
    }
)

Response

Returns the updated customer object.

Delete Customer

Permanently delete a customer.

DELETE /v1/customers/{customer_id}

Path Parameters

Parameter Type Description
customer_id UUID The customer ID

Examples

curl -X DELETE "https://api.toptickets.app/v1/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

CUSTOMER_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.delete(
    f"https://api.toptickets.app/v1/customers/{CUSTOMER_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Customer deleted")

Response

Returns 204 No Content on success.

Related Tickets

Deleting a customer may affect associated tickets. Consider the impact before deletion.

Customer Tiers

Customer tiers help categorize customers for prioritization:

Tier Typical Use
tier_1 Enterprise / highest priority
tier_2 Business / high priority
tier_3 Standard / normal priority
tier_4 Basic / lowest priority

Business Regions

Region Description
amer Americas
apac Asia-Pacific
emea Europe, Middle East, Africa
latam Latin America
asean Southeast Asia