Developer API

Connect to Proto AICX directly through an easy API.

API account access is available with the Total plan and above.

Find the full developer API schema here: https://v3-api.proto.cx/api/platform/docs

---

Authentication

Note that "sub-companies" is a legacy term for a unit within a workspace, now referred to as "teamspaces" in the current platform and documentation.

Each request to the developer API must include a bearer token in the Authorization header. This bearer token should be in the form of Authorization: Bearer {subcompany_takeover_secret}. This takeover secret can be found in the teamspace settings page.

---

Conversations API

Create ticket

URL

POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/create-ticket

Body

{
  "subject": "string" (required),
  "customer_id": "string",
  "external_customer_id": "string",
  "gateway_profile_id": "string",
  "provided_unique_id": "string"
}

One of customer_id, external_customer_id, gateway_profile_id, or provided_unique_id must be provided to identify the customer.

Returns

{
  "id": "The id of the created conversation."
}

---

Customers API

Note that "customer" is a legacy term for an audience member, now referred to more generically as "people" or "persons" in the current platform and documentation.

Get customer

URL

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

Returns

A JSON dictionary of all customer information other than their associated custom field values. 

Parameters	Data Type	Required	Description
subcompany_id	string		subcompany_id from Proto
provided_unique_id	string		user's provided_unique_id
authorization

Insert customer

URL

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

Body

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

Returns

A JSON dictionary of the created customer.

Add tags

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

Use create_if_not_exists to also create any tags that do not exist before applying it to the customer.

Add custom fields

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

One of id or name must be provided for each custom field element in the request body. The id of a custom field can be retrieved from listing or creating a new custom field.

---

Custom Fields API

List custom fields

GET https://v3-api.proto.cx/api/platform/v1/custom-fields/{subcompany_id}/list-custom-fields

Create custom fields

POST https://v3-api.proto.cx/api/platform/v1/custom-fields/{subcompany_id}/create-custom-field

select_options must be provided only if type is select.

Delete custom fields

DELETE https://v3-api.proto.cx/api/platform/v1/custom-fields/{subcompany_id}/custom-field/{custom_field_id}/delete-custom-fields