Customers

Create or update a customer

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

POST

/customers

curl --request POST \
  --url https://api.getrotor.com/open-api/customers \
  --header 'x-api-key: <api-key>' \
  --header 'rotor-api-version: 1.1.0' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing_city": "<string>",
  "billing_country": "<string>",
  "billing_same_as_property": true,
  "billing_state": "<string>",
  "billing_street1": "<string>",
  "billing_street2": "<string>",
  "billing_zip": "<string>",
  "company_name": "<string>",
  "email": "jsmith@example.com",
  "first_name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "last_name": "<string>",
  "notes": "<string>",
  "phone": "<string>",
  "property_city": "<string>",
  "property_country": "<string>",
  "property_state": "<string>",
  "property_street1": "<string>",
  "property_street2": "<string>",
  "property_zip": "<string>",
  "service_frequency": "<string>",
  "service_type": "<string>",
  "source": "<string>",
  "status": "active",
  "tags": [
    "<string>"
  ]
}
'

{
  "billing_city": "<string>",
  "billing_country": "<string>",
  "billing_same_as_property": true,
  "billing_state": "<string>",
  "billing_street1": "<string>",
  "billing_street2": "<string>",
  "billing_zip": "<string>",
  "company_name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "email": "jsmith@example.com",
  "first_name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "last_name": "<string>",
  "message": "Customer created successfully",
  "notes": "<string>",
  "phone": "<string>",
  "property_city": "<string>",
  "property_country": "<string>",
  "property_state": "<string>",
  "property_street1": "<string>",
  "property_street2": "<string>",
  "property_zip": "<string>",
  "service_frequency": "<string>",
  "service_type": "<string>",
  "source": "<string>",
  "status": "active",
  "tags": [
    "<string>"
  ]
}

Upsert Logic:

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

Tags are merged (not replaced) when updating.

Authorizations

x-api-keystringheaderrequired

Company API key in the format: rotor_{keyId}_{keySecret}

To obtain an API key:

Log into your Rotor dashboard
Go to Settings → Integrations → API Keys
Create a new key and select the scopes you need
Copy the key — it's only shown once!

Headers

rotor-api-versionenum<string>headerdefault:1.1.0required

Required OpenAPI version header.

Available options: 1.1.0

Example: 1.1.0

Body

billing_citystring

billing_countrystring

billing_same_as_propertyboolean

billing_statestring

billing_street1string

billing_street2string

billing_zipstring

company_namestring

Maximum string length: 255

emailstring

Maximum string length: 255

first_namestring

Maximum string length: 255

idstring

Optional — provide to update an existing customer

last_namestring

Maximum string length: 255

notesstring

Maximum string length: 2000

phonestring

property_citystring

property_countrystring

property_statestring

property_street1string

property_street2string

property_zipstring

service_frequencystring

service_typestring

sourcestring

statusenum<string>

Available options: active, inactive

tagsstring[]

Maximum array length: 20

Response

Customer updated successfully

billing_citystring | null

billing_countrystring | null

billing_same_as_propertyboolean

billing_statestring | null

billing_street1string | null

billing_street2string | null

billing_zipstring | null

company_namestring | null

created_atstring

emailstring | null

first_namestring | null

idstring

last_namestring | null

messagestring

Example: Customer created successfully

notesstring | null

phonestring | null

property_citystring | null

property_countrystring | null

property_statestring | null

property_street1string | null

property_street2string | null

property_zipstring | null

service_frequencystring | null

service_typestring | null

sourcestring | null

statusenum<string>

Available options: active, inactive

tagsstring[] | null

Still need help? Ask the team