# Customers

## 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
1. If no `id` but phone/email provided, searches for existing customer by phone first, then email
1. If no existing customer found, creates a new customer

Tags are merged (not replaced) when updating.

### Header Parameters

- `"rotor-api-version": "1.1.0"`

  - `"1.1.0"`

### Body Parameters

- `id: optional string`

  Optional — provide to update an existing customer

- `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"`

  - `"active"`

  - `"inactive"`

- `tags: optional array of string`

### Returns

- `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"`

  - `"active"`

  - `"inactive"`

- `tags: optional array of string`

### Example

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

#### Response

```json
{
  "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"
  ]
}
```

## List customers

**get** `/customers`

Returns a paginated list of customers for the authenticated company.

### Query Parameters

- `archived: optional boolean`

  Include archived customers (default false)

- `limit: optional number`

  Number of results per page (max 1000)

- `page: optional number`

  Page number (1-based)

- `search: optional string`

  Search by first name, last name, company name, email, or phone

- `status: optional "active" or "inactive"`

  Filter by customer status

  - `"active"`

  - `"inactive"`

- `tags: optional string`

  Filter by tags (comma-separated)

### Header Parameters

- `"rotor-api-version": "1.1.0"`

  - `"1.1.0"`

### Returns

- `data: optional array of object { id, address, company_name, 11 more }`

  - `id: optional string`

  - `address: optional object { city, country, state, 3 more }`

    - `city: string`

    - `country: string`

    - `state: string`

    - `street1: string`

    - `zip: string`

    - `street2: optional string`

  - `company_name: optional string`

  - `created_at: optional string`

  - `email: optional string`

  - `first_name: optional string`

  - `is_auto_pay: optional boolean`

  - `last_name: optional string`

  - `location: optional array of number`

  - `notes: optional string`

  - `phone: optional string`

  - `source: optional string`

  - `status: optional "active" or "inactive"`

    - `"active"`

    - `"inactive"`

  - `tags: optional array of string`

- `pagination: optional object { has_more, limit, page, total }`

  - `has_more: optional boolean`

    Whether more pages are available

  - `limit: optional number`

  - `page: optional number`

  - `total: optional number`

    Total number of matching records

- `status: optional string`

### Example

```http
curl https://api.getrotor.com/open-api/customers \
    -H "x-api-key: $ROTOR_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "address": {
        "city": "city",
        "country": "country",
        "state": "state",
        "street1": "street1",
        "zip": "zip",
        "street2": "street2"
      },
      "company_name": "company_name",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "first_name": "first_name",
      "is_auto_pay": true,
      "last_name": "last_name",
      "location": [
        0
      ],
      "notes": "notes",
      "phone": "phone",
      "source": "source",
      "status": "active",
      "tags": [
        "string"
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}
```

## Get a customer by ID

**get** `/customers/{id}`

Get a customer by ID

### Path Parameters

- `id: string`

### Header Parameters

- `"rotor-api-version": "1.1.0"`

  - `"1.1.0"`

### Returns

- `data: optional object { id, address, company_name, 11 more }`

  - `id: optional string`

  - `address: optional object { city, country, state, 3 more }`

    - `city: string`

    - `country: string`

    - `state: string`

    - `street1: string`

    - `zip: string`

    - `street2: optional string`

  - `company_name: optional string`

  - `created_at: optional string`

  - `email: optional string`

  - `first_name: optional string`

  - `is_auto_pay: optional boolean`

  - `last_name: optional string`

  - `location: optional array of number`

  - `notes: optional string`

  - `phone: optional string`

  - `source: optional string`

  - `status: optional "active" or "inactive"`

    - `"active"`

    - `"inactive"`

  - `tags: optional array of string`

- `status: optional string`

### Example

```http
curl https://api.getrotor.com/open-api/customers/$ID \
    -H "x-api-key: $ROTOR_API_KEY"
```

#### Response

```json
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "address": {
      "city": "city",
      "country": "country",
      "state": "state",
      "street1": "street1",
      "zip": "zip",
      "street2": "street2"
    },
    "company_name": "company_name",
    "created_at": "2019-12-27T18:11:19.117Z",
    "email": "dev@stainless.com",
    "first_name": "first_name",
    "is_auto_pay": true,
    "last_name": "last_name",
    "location": [
      0
    ],
    "notes": "notes",
    "phone": "phone",
    "source": "source",
    "status": "active",
    "tags": [
      "string"
    ]
  },
  "status": "success"
}
```