Custom Trades CRM
Custom Trades CRMAPI docs

Customers

The Customer object represents a customer record in your Custom Trades CRM account.

View as Markdown

Endpoints

GET/api/v1/customers
GET/api/v1/customers/{uuid}
POST/api/v1/customers
PUT/api/v1/customers/{uuid}
DELETE/api/v1/customers/{uuid}

The Customer object

Attributes

uuidstring

Unique identifier for the customer

first_namestring

Customer's first name

last_namestring

Customer's last name

company_namestring |null

Company name (for commercial customers)

emailstring |null

Email address

phonestring |null

Phone number (xxx-xxx-xxxx format)

customer_typestring

'Residential' or 'Commercial'

is_vipboolean

Whether customer is marked as VIP

physical_address1string |null

Physical address line 1

physical_address2string |null

Physical address line 2

physical_citystring |null

Physical city

physical_statestring |null

Physical state

physical_zipstring |null

Physical ZIP code

billing_address1string |null

Billing address line 1

billing_address2string |null

Billing address line 2

billing_citystring |null

Billing city

billing_statestring |null

Billing state

billing_zipstring |null

Billing ZIP code

primary_service_location_uuidUUID |null

Primary service location UUID

notesstring |null

Internal notes

internal_flagsJSONB |null

Internal flags/metadata

on_my_way_notify_viastring |null

Notification preference ('email', 'sms', 'both')

created_atstring

ISO timestamp of creation

updated_atstring

ISO timestamp of last update

deleted_atstring |null

ISO timestamp of soft deletion (null if not deleted)

View as Markdown

THE CUSTOMER OBJECT

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "206-555-1234",
  "customer_type": "Residential",
  "is_vip": false
}

List customers

Returns a paginated list of customers for your company.

Parameters

include_deleted(boolean, default: false)required

Include soft-deleted customers

filter(string)

Filter by type: 'all', 'residential', 'commercial', 'vip'

search(string)

Search term (searches name, email, phone, customer_id)

page(number, default: 1)required

Page number

limit(number, default: 50, max: 100)required

Items per page

success(boolean)

Whether the request succeeded.

data(object)

Object containing customers and pagination. See "The Customer object" table for attribute list.

data.customers(array)

List of Customer objects. Each item has the same shape as the Customer object.

data.pagination(object)

Pagination metadata.

data.pagination.page(number)

Current page number.

data.pagination.limit(number)

Items per page.

data.pagination.total(number)

Total number of items.

data.pagination.total_pages(number)

Total number of pages.

Returns

success(boolean)

Whether the request succeeded.

data(object)

Object containing customers and pagination. See "The Customer object" table for attribute list.

GET/api/v1/customers
curl -G \
  https://customtradescrm.com/api/v1/customers?filter=residential&search=john \
  -H "Authorization: Bearer ctc_live_sk_test_1234567890abcdefghijklmnopqrstuvwxyz"

Response

{
  "success": true,
  "data": {
    "customers": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "206-555-1234",
        "customer_type": "Residential",
        "is_vip": false
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

Get a customer

Returns a specific customer by UUID. **Response attributes:** - `success` (boolean) - Whether the request succeeded. - `data` (object) - The Customer object. See "The Customer object" table for attribute list.

Returns

success(boolean)

Whether the request succeeded.

data(object)

The Customer object. See "The Customer object" table for attribute list.

GET/api/v1/customers/{uuid}
curl -G \
  https://customtradescrm.com/api/v1/customers/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_sk_test_1234567890abcdefghijklmnopqrstuvwxyz"

Response

{
  "success": true,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": null,
    "email": "john@example.com",
    "phone": "206-555-1234",
    "customer_type": "Residential",
    "is_vip": false,
    "physical_address1": "123 Main St",
    "physical_address2": null,
    "physical_city": "Seattle",
    "physical_state": "WA",
    "physical_zip": "98101",
    "billing_address1": "123 Main St",
    "billing_address2": null,
    "billing_city": "Seattle",
    "billing_state": "WA",
    "billing_zip": "98101",
    "primary_service_location_uuid": null,
    "notes": null,
    "internal_flags": null,
    "on_my_way_notify_via": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "deleted_at": null
  }
}

Create a customer

Creates a new customer.

Parameters

first_name(string)required

Customer's first name

last_name(string)required

Customer's last name

company_name(string)

Company name (for commercial customers)

email(string)

Email address

phone(string)

Phone number (xxx-xxx-xxxx format)

customer_type(string)

'Residential' or 'Commercial' (default: 'Residential')

is_vip(string)

boolean (default: false)

primary_service_location_uuid(string)

UUID of primary service location

notes(string)

Internal notes

internal_flags(string)

JSONB object

on_my_way_notify_via(string)

'email', 'sms', 'both', or null

Returns

success(boolean)

Whether the request succeeded.

data(object)

The created Customer object. See "The Customer object" table for attribute list.

POST/api/v1/customers
curl -X POST \
  https://customtradescrm.com/api/v1/customers \
  -H "Authorization: Bearer ctc_live_sk_test_1234567890abcdefghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  --json '{
      '

Response

{
  "success": true,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": null,
    "email": "john@example.com",
    "phone": "206-555-1234",
    "customer_type": "Residential",
    "is_vip": false,
    "physical_address1": null,
    "physical_address2": null,
    "physical_city": null,
    "physical_state": null,
    "physical_zip": null,
    "billing_address1": "123 Main St",
    "billing_address2": null,
    "billing_city": "Seattle",
    "billing_state": "WA",
    "billing_zip": "98101",
    "primary_service_location_uuid": null,
    "notes": null,
    "internal_flags": null,
    "on_my_way_notify_via": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "deleted_at": null
  }
}

Update a customer

Updates a customer. All fields are optional (partial update). **Response attributes:** - `success` (boolean) - Whether the request succeeded. - `data` (object) - The updated Customer object. See "The Customer object" table for attribute list.

Returns

success(boolean)

Whether the request succeeded.

data(object)

The updated Customer object. See "The Customer object" table for attribute list.

PUT/api/v1/customers/{uuid}
curl -X PUT \
  https://customtradescrm.com/api/v1/customers/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_sk_test_1234567890abcdefghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  --json '{
      '

Response

{
  "success": true,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": null,
    "email": "newemail@example.com",
    "phone": "206-555-1234",
    "customer_type": "Residential",
    "is_vip": true,
    "physical_address1": "123 Main St",
    "physical_address2": null,
    "physical_city": "Seattle",
    "physical_state": "WA",
    "physical_zip": "98101",
    "billing_address1": "123 Main St",
    "billing_address2": null,
    "billing_city": "Seattle",
    "billing_state": "WA",
    "billing_zip": "98101",
    "primary_service_location_uuid": null,
    "notes": null,
    "internal_flags": null,
    "on_my_way_notify_via": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-16T14:20:00Z",
    "deleted_at": null
  }
}

Delete a customer

Soft deletes a customer (sets `deleted_at` timestamp). **Response attributes:** - `success` (boolean) - Whether the request succeeded. - `data` (object) - Confirmation payload. - `data.message` (string) - Success message.

Returns

success(boolean)

Whether the request succeeded.

data(object)

Confirmation payload.

DELETE/api/v1/customers/{uuid}
curl -X DELETE \
  https://customtradescrm.com/api/v1/customers/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_sk_test_1234567890abcdefghijklmnopqrstuvwxyz"

Response

{
  "success": true,
  "data": {
    "message": "Customer deleted successfully"
  }
}