Customers API

Create and manage people and their tags.

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

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.

---

Create or update a person

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.

URL

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

Body

{
  "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"
}

Returns

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

---

Get a person

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

URL

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

Returns

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

---

List people by modified date

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

URL

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

Query parameters

Parameter	Required	Type
modified_start	No	string
modified_end	No	string

---

Add tags to a person

Adds tags to a person, leaving existing tags in place.

URL

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

Body

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

Returns

{
  "success": "boolean"
}

---

Remove tags from a person

Removes tags from a person, by tag ID or by name.

URL

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

Body

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

Returns

{
  "success": "boolean"
}

---

Set custom field values

Sets custom field values on a person.

URL

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

Body

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

---

Create or update a person (earlier platform)

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

URL

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

Body

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

Returns

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

---

Create a person (v2 platform)

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

URL

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

Body

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

Returns

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

---

Update a person (v2 platform)

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

URL

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

Body

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

Returns

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