Customer

The Customer APIs let you create, update, and retrieve customer records, including contact details, address information, preferred contact methods, and marketing opt-in preferences.

Customer data fields

A customer record typically includes:

First name

Last name

Company name (optional)

Email (primary email)

Phone number (primary phone, international format)

Address line 1

Address line 2 (optional)

City

State

ZIP / Postal code

Preferred contact methods (Email, Phone, SMS)

Marketing email opt-in (boolean)

Marketing SMS opt-in (boolean)

Notes and common validations:

First name and last name should be 2–50 characters and must not contain numbers.

Email may be required when phone is missing, and is required when marketing email opt-in is true.

Phone number may be required when email is missing, and is required when marketing SMS opt-in is true.

Create Customer

Creates a new customer record with primary contact details, address information, preferred contact methods, and marketing preferences.

Method: POST

Path: /v1/customers

Success: 201 Created

Errors: 400 Invalid input, 401 Unauthorized, 500 Internal server error

Key behaviors:

Do not include a customerId when creating.

On success, the response includes a newly created customerId and a createdAt timestamp.

Update Customer

Updates an existing customer record identified by customerId. You can modify name, company, email/phone, address, preferred contact methods, and marketing opt-in preferences.

Method: PUT

Path: /v1/customers/{customerId}

Path parameter: customerId (required)

Success: 200 OK

Errors: 400 Invalid input, 401 Unauthorized, 500 Internal server error

Key behaviors:

The customerId must reference an existing customer.

On success, the response includes the customerId and an updatedAt timestamp.

Search Customers by phone, email, or first name

Retrieves customers that match one or more of the provided search criteria.

Method: GET

Path: /v1/customers/search

Query parameters (all optional):

phone

firstName

Success: 200 OK

No results: 204 No Content

Errors: 400 Invalid input, 401 Unauthorized, 500 Internal server error

Key behaviors:

Use this endpoint to find customers when you have partial identifying information (like phone or email).

On success, the response returns a list of matching customers with profile and contact details.

Search Customers by address

Searches and retrieves customers using address information.

Method: GET

Path: /v1/customers/by-address

Query parameters:

addressLine1 (required)

addressLine2 (optional)

city (required)

stateOrRegion (required)

postalCode (required)

Success: 200 OK

No results: 204 No Content

Errors: 400 Invalid input, 401 Unauthorized, 500 Internal server error

Key behaviors:

Use this endpoint when address is the primary way to locate a customer (for example, matching service locations).

Get Customer by ID

Retrieves customer details using a unique customer identifier.

Method: GET

Path: /v1/customers/id/{customerId}

Path parameter: customerId (required)

Success: 200 OK

No results: 204 No Content

Errors: 400 Invalid input, 401 Unauthorized, 500 Internal server error

Key behaviors:

Use this endpoint when you already have the customerId and need the full customer record.

Error handling

400 Invalid input

Returned when one or more fields fail validation. The response typically includes:

A high-level error code and message

A list of field-level errors (field name, error code, and message)

A requestId for tracing/debugging

A timestamp

401 Unauthorized

Returned when credentials are missing or invalid.

500 Internal server error

Returned when the service encounters an unexpected condition while processing the request.

Customer data fields#

Create Customer#

Update Customer#

Search Customers by phone, email, or first name#

Search Customers by address#

Get Customer by ID#

Error handling#

400 Invalid input#

401 Unauthorized#

500 Internal server error#

Customer data fields

Create Customer

Update Customer

Search Customers by phone, email, or first name

Search Customers by address

Get Customer by ID

Error handling

400 Invalid input

401 Unauthorized

500 Internal server error