> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/developers/apis/customers-api.md).

# Customers API

Create and update people, read their profiles, and manage their tags and custom field values.

{% hint style="info" %}
The API refers to people as customers. Endpoints marked *earlier platform* serve the previous edition of the platform — new integrations should use the endpoints above them.
{% endhint %}

***

### [**Create or update a person**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/update_customer_v3_v1_customers__subcompany_id__update_customer__provided_unique_id__v3_patch)

Creates or updates a person, keyed on your own **provided\_unique\_id**. Tags and tag groups are added and removed incrementally, rather than replacing the whole set. Omitted fields are left unchanged.

{% code title="URL" overflow="wrap" %}

```
PATCH https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/update-customer/{provided_unique_id}/v3
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "add_tags_ids": "array",
  "remove_tags_ids": "array",
  "add_tag_groups_ids": "array",
  "remove_tag_groups_ids": "array"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "subcompany_id": "string",
  "provided_unique_id": "string",
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "tags": [object],
  "tag_groups": [object]
}
```

{% endcode %}

***

### [**Get a person**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/get_customer_v1_customers__subcompany_id__customer__provided_unique_id__get_customer_get)

Returns one person's full profile: contact details, notes, tags, tag groups, and their channel profiles.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/customer/{provided_unique_id}/get-customer
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "external_customer_id": "string",
  "provided_unique_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "notes": [object],
  "tags": [object],
  "tag_groups": [object],
  "gateway_profiles": [object],
  "customer_bans": [object]
}
```

{% endcode %}

***

### [**List people by modified date**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/get_customer_by_modified_at_range_v1_customers__subcompany_id__customer_get_customer_by_modified_at_range_get)

Lists people whose records changed within the given range. Use this to sync recent changes into an external system.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/customer/get-customer-by-modified-at-range
```

{% endcode %}

**Query parameters**

| Parameter        | Required | Type   |
| ---------------- | -------- | ------ |
| `modified_start` | No       | string |
| `modified_end`   | No       | string |

***

### [**Add tags to a person**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/add_customer_tags_v1_customers__subcompany_id__customer__provided_unique_id__add_tags_put)

Adds [tags](/docs/settings/teamspaces/tags.md) to a person, leaving existing tags in place.

{% code title="URL" overflow="wrap" %}

```
PUT https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/customer/{provided_unique_id}/add-tags
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "tags": [object] (required)
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "success": "boolean"
}
```

{% endcode %}

***

### [**Remove tags from a person**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/remove_customer_tags_v1_customers__subcompany_id__customer__provided_unique_id__remove_tags_put)

Removes [tags](/docs/settings/teamspaces/tags.md) from a person, by tag ID or by name.

{% code title="URL" overflow="wrap" %}

```
PUT https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/customer/{provided_unique_id}/remove-tags
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "ids": "array",
  "tags": "array"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "success": "boolean"
}
```

{% endcode %}

***

### [**Set custom field values**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/add_customer_custom_fields_v1_customers__subcompany_id__customer__provided_unique_id__add_custom_fields_put)

Sets [custom field](/docs/settings/teamspaces/custom-fields.md) values on a person.

{% code title="URL" overflow="wrap" %}

```
PUT https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/customer/{provided_unique_id}/add-custom-fields
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "custom_fields": [object] (required)
}
```

{% endcode %}

***

### [**Create or update a person (earlier platform)**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/upsert_customer_v1_customers__subcompany_id__create_customer__provided_unique_id__put)

Creates or updates a person without tag support. Serves the earlier platform edition.

{% code title="URL" overflow="wrap" %}

```
PUT https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/create-customer/{provided_unique_id}
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "subcompany_id": "string",
  "provided_unique_id": "string",
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string"
}
```

{% endcode %}

***

### [**Create a person (v2 platform)**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/upsert_customer_v2_v1_customers__subcompany_id__create_customer__provided_unique_id__v2_post)

Creates or updates a person, setting tags and tag groups wholesale. Serves the earlier platform edition.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/create-customer/{provided_unique_id}/v2
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "tag_ids": "array",
  "tag_group_ids": "array"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "subcompany_id": "string",
  "provided_unique_id": "string",
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "tags": [object],
  "tag_groups": [object]
}
```

{% endcode %}

***

### [**Update a person (v2 platform)**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/upsert_customer_v2_v1_customers__subcompany_id__update_customer__provided_unique_id__v2_put)

Updates a person, setting tags and tag groups wholesale. Serves the earlier platform edition.

{% code title="URL" overflow="wrap" %}

```
PUT https://v3-api.proto.cx/api/platform/v1/customers/{subcompany_id}/update-customer/{provided_unique_id}/v2
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "tag_ids": "array",
  "tag_group_ids": "array"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "subcompany_id": "string",
  "provided_unique_id": "string",
  "external_customer_id": "string",
  "name": "string",
  "location": "string",
  "email": "string",
  "phone_number": "string",
  "avatar": "string",
  "tags": [object],
  "tag_groups": [object]
}
```

{% endcode %}