Locations

The Location object represents a physical location (office, warehouse, etc.) for your company.

View as Markdown

Endpoints

GET/api/v1/locations

GET/api/v1/locations/{uuid}

POST/api/v1/locations

PUT/api/v1/locations/{uuid}

DELETE/api/v1/locations/{uuid}

The Location object

Attributes

uuidstring

Unique identifier for the location

namestring

Location name

location_codestring |null

Optional location code

address1string

First line of address

address2string |null

Second line of address

citystring

City

statestring

2-letter US state code

zipstring

ZIP code (5 or 9 digits)

phonestring |null

Phone number (xxx-xxx-xxxx format)

timezonestring

Timezone (default: 'America/New_York')

business_hoursJSONB |null

Business hours configuration

default_tax_rulesJSONB |null

Default tax rules

service_types_offeredJSONB |null

Service types offered at this location

default_pricing_set_uuidUUID |null

Default pricing set UUID

is_primaryboolean

Whether this is the primary location

is_activeboolean

Whether the location is active

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 LOCATION OBJECT

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Main Office",
  "address1": "123 Main St",
  "city": "Seattle",
  "state": "WA",
  "zip": "98101",
  "is_primary": true,
  "is_active": true
}

List locations

Returns a paginated list of locations for your company.

Parameters

include_deleted(boolean, default: false)required

Include soft-deleted locations

page(number, default: 1)required

Page number

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

Items per page

GET/api/v1/locations

curl -G \
  https://customtradescrm.com/api/v1/locations \
  -H "Authorization: Bearer ctc_live_..."

Response

{
  "success": true,
  "data": {
    "locations": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Main Office",
        "address1": "123 Main St",
        "city": "Seattle",
        "state": "WA",
        "zip": "98101",
        "is_primary": true,
        "is_active": true
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

Get a location

Returns a specific location by UUID.

GET/api/v1/locations/{uuid}

curl -G \
  https://customtradescrm.com/api/v1/locations/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."

Create a location

Creates a new location. **Request Body:**

Parameters

name(string)required

Location name

address1(string)required

First line of address

city(string)required

City

state(string)required

2-letter US state code (e.g., "WA", "CA")

zip(string)required

ZIP code (5 digits or 5+4 format)

location_code(string)

Location code

address2(string)

Second line of address

phone(string)

Phone number (xxx-xxx-xxxx format)

timezone(string)

Timezone (default: 'America/New_York')

business_hours(string)

JSONB object

default_tax_rules(string)

JSONB object

service_types_offered(string)

JSONB object

default_pricing_set_uuid(string)

UUID

is_primary(string)

boolean (default: false)

POST/api/v1/locations

curl -G \

Response

{
  "success": true,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Main Office",
    "address1": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "zip": "98101",
    "is_primary": false,
    "is_active": true,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Update a location

Updates a location. All fields are optional (partial update). **Request Body:**

PUT/api/v1/locations/{uuid}

curl -G \

Response

{
  "name": "Updated Office Name",
  "phone": "206-555-5678"
}

Delete a location

Soft deletes a location (sets `deleted_at` timestamp). Cannot delete primary location (`is_primary = true`).

Error codes

HTTP status code	Description
200	Success
400	Validation error or cannot delete primary location
401	Unauthorized (invalid API key)
403	Forbidden (add-on required, IP restriction, or usage limit exceeded)
404	Location not found
500	Server error

DELETE/api/v1/locations/{uuid}

curl -X DELETE \
  https://customtradescrm.com/api/v1/locations/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer ctc_live_..."

Response

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