API Reference

Customers

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create or update a customer

POST/customers

Creates a new customer or updates an existing one based on the provided information.

Upsert Logic:

1. If id is provided, updates the customer with that ID
2. If no id but phone/email provided, searches for existing customer by phone first, then email
3. If no existing customer found, creates a new customer

Tags are merged (not replaced) when updating.

Header ParametersExpand Collapse

"rotor-api-version": "1.1.0"

Body ParametersJSONExpand Collapse

id: optional string

Optional — provide to update an existing customer

formatuuid

billing_city: optional string

billing_country: optional string

billing_same_as_property: optional boolean

billing_state: optional string

billing_street1: optional string

billing_street2: optional string

billing_zip: optional string

company_name: optional string

email: optional string

first_name: optional string

last_name: optional string

notes: optional string

phone: optional string

property_city: optional string

property_country: optional string

property_state: optional string

property_street1: optional string

property_street2: optional string

property_zip: optional string

service_frequency: optional string

service_type: optional string

source: optional string

status: optional "active" or "inactive"

One of the following:

"active"

"inactive"

tags: optional array of string

ReturnsExpand Collapse

id: optional string

billing_city: optional string

billing_country: optional string

billing_same_as_property: optional boolean

billing_state: optional string

billing_street1: optional string

billing_street2: optional string

billing_zip: optional string

company_name: optional string

created_at: optional string

email: optional string

first_name: optional string

last_name: optional string

message: optional string

notes: optional string

phone: optional string

property_city: optional string

property_country: optional string

property_state: optional string

property_street1: optional string

property_street2: optional string

property_zip: optional string

service_frequency: optional string

service_type: optional string

source: optional string

status: optional "active" or "inactive"

One of the following:

"active"

"inactive"

tags: optional array of string

Create or update a customer

HTTP

HTTP

curl https://api.getrotor.com/open-api/customers \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $ROTOR_API_KEY" \
    -d '{}'

200 example

400 example

401 example

403 example

429 example

500 example

{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "billing_city": "billing_city",
  "billing_country": "billing_country",
  "billing_same_as_property": true,
  "billing_state": "billing_state",
  "billing_street1": "billing_street1",
  "billing_street2": "billing_street2",
  "billing_zip": "billing_zip",
  "company_name": "company_name",
  "created_at": "2019-12-27T18:11:19.117Z",
  "email": "dev@stainless.com",
  "first_name": "first_name",
  "last_name": "last_name",
  "message": "Customer created successfully",
  "notes": "notes",
  "phone": "phone",
  "property_city": "property_city",
  "property_country": "property_country",
  "property_state": "property_state",
  "property_street1": "property_street1",
  "property_street2": "property_street2",
  "property_zip": "property_zip",
  "service_frequency": "service_frequency",
  "service_type": "service_type",
  "source": "source",
  "status": "active",
  "tags": [
    "string"
  ]
}

{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

{
  "status": "error",
  "message": "Internal server error"
}

Returns Examples

200 example

400 example

401 example

403 example

429 example

500 example

{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "billing_city": "billing_city",
  "billing_country": "billing_country",
  "billing_same_as_property": true,
  "billing_state": "billing_state",
  "billing_street1": "billing_street1",
  "billing_street2": "billing_street2",
  "billing_zip": "billing_zip",
  "company_name": "company_name",
  "created_at": "2019-12-27T18:11:19.117Z",
  "email": "dev@stainless.com",
  "first_name": "first_name",
  "last_name": "last_name",
  "message": "Customer created successfully",
  "notes": "notes",
  "phone": "phone",
  "property_city": "property_city",
  "property_country": "property_country",
  "property_state": "property_state",
  "property_street1": "property_street1",
  "property_street2": "property_street2",
  "property_zip": "property_zip",
  "service_frequency": "service_frequency",
  "service_type": "service_type",
  "source": "source",
  "status": "active",
  "tags": [
    "string"
  ]
}

{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

{
  "status": "error",
  "message": "Authentication required. Provide x-api-key header.",
  "error_code": "AUTHENTICATION_REQUIRED"
}

{
  "status": "error",
  "message": "Forbidden: required scope 'leads:read' not granted for this API key",
  "error_code": "INSUFFICIENT_SCOPE"
}

{
  "status": "error",
  "message": "Daily API key request limit of 1000 exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

{
  "status": "error",
  "message": "Internal server error"
}