Customers API

The Customers API provides access to customer records, including personal information, addresses, and service preferences.

Base URL

https://api.otesse.com/v1/customers

List Customers

GET /v1/customers

Query Parameters

Parameter	Type	Description
search	string	Search by name, email, or phone
status	string	active, inactive, deactivated
created_after	string (ISO 8601)	Filter by creation date
has_subscription	boolean	Filter to customers with active subscriptions
zone_id	string	Filter by service zone
page	integer	Page number
per_page	integer	Items per page (max: 100)

Example

curl -X GET "https://api.otesse.com/v1/customers?search=john&status=active" \
  -H "Authorization: Bearer otesse_live_sk_..."

Response

{
  "data": [
    {
      "id": "cust_01HQ3K5M7N",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "phone": "+15551234567",
      "status": "active",
      "addresses": [
        {
          "id": "addr_01HQ3K5M7N",
          "label": "Home",
          "street": "123 Main St",
          "city": "Eugene",
          "state": "OR",
          "zip": "97401",
          "is_default": true
        }
      ],
      "stats": {
        "total_bookings": 12,
        "total_spent": 195000,
        "last_booking_at": "2026-02-15T10:00:00Z",
        "active_subscription": true
      },
      "created_at": "2025-06-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Create a Customer

POST /v1/customers

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone": "+15559876543",
  "address": {
    "label": "Home",
    "street": "456 Oak Ave",
    "city": "Springfield",
    "state": "OR",
    "zip": "97477"
  }
}

Returns the created customer with 201 Created. An invitation email is sent to the customer automatically.

Get a Customer

GET /v1/customers/:id

Returns the full customer record with addresses, subscription status, and summary statistics.

Update a Customer

PATCH /v1/customers/:id

{
  "phone": "+15551112222",
  "preferences": {
    "preferred_contact": "sms",
    "marketing_opt_in": false
  }
}

Add an Address

POST /v1/customers/:id/addresses

{
  "label": "Office",
  "street": "789 Business Blvd, Suite 200",
  "city": "Eugene",
  "state": "OR",
  "zip": "97401",
  "access_notes": "Check in at the front desk. Suite is on the 2nd floor.",
  "is_default": false
}

Customer Bookings

GET /v1/customers/:id/bookings

Returns all bookings for the customer with the same query parameters as the Bookings API list endpoint.

Customer Invoices

GET /v1/customers/:id/invoices

Returns all invoices for the customer, ordered by date descending.