# Developer API

{% hint style="info" %}
API account access is available with the Total plan and above.
{% endhint %}

{% hint style="info" %}
Find the full developer API schema here: <https://v3-api.proto.cx/api/platform/docs>
{% endhint %}

***

## Authentication <a href="#authentication-api" id="authentication-api"></a>

{% hint style="warning" %}
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.
{% endhint %}

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 {takeover\_secret}**. This takeover secret can be found in the [teamspace](https://documentation.proto.cx/docs/settings/teamspaces) settings page.

<figure><img src="https://documentation.proto.cx/~gitbook/image?url=https%3A%2F%2F2581047078-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Few2P7M4OjewnGSuQi7Ht%252Fuploads%252Fwkds3bg8Lbs5Rnxpi1nL%252FScreenshot_2024-03-01_at_12.51.24.png%3Falt%3Dmedia%26token%3D83cb095f-4211-4de8-82ca-4d49ed2850df&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=e9df66ab&#x26;sv=2" alt=""><figcaption></figcaption></figure>

***

## Conversations API <a href="#conversations-api" id="conversations-api"></a>

### [**Create ticket**](https://v3-api.proto.cx/api/platform/docs#/v1/create_conversation_v1_conversations__subcompany_id__create_ticket_post)

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

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

{% endcode %}

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

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

{% endcode %}

{% hint style="warning" %}
One of **customer\_id**, **external\_customer\_id**, **gateway\_profile\_id**, or **provided\_unique\_id** must be provided to identify the customer.
{% endhint %}

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

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

{% endcode %}

***

## Customers API <a href="#customers-api" id="customers-api"></a>

{% hint style="warning" %}
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.
{% endhint %}

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

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

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

{% endcode %}

<table><thead><tr><th width="199">Parameters</th><th width="124">Data Type</th><th width="118" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>subcompany_id</td><td>string</td><td>true</td><td>subcompany_id from Proto</td></tr><tr><td>provided_unique_id</td><td>string</td><td>true</td><td>user's provided_unique_id</td></tr><tr><td>authorization</td><td></td><td>true</td><td></td></tr></tbody></table>

### [**Insert customer**](https://v3-api.proto.cx/api/platform/docs#/v1/upsert_customer_v1_customers__subcompany_id__create_customer__provided_unique_id__put)

{% 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" (optional),
  "name": "string" (optional),
  "location": "string" (optional),
  "email": "string" (optional),
  "phone_number": "string" (optional),
  "avatar": "string" (optional)
}
```

{% endcode %}

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

```
A JSON dictionary of the created customer.
```

{% endcode %}

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

{% code overflow="wrap" %}

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

{% endcode %}

{% hint style="warning" %}
Use **create\_if\_not\_exists** to also create any tags that do not exist before applying it to the customer.
{% endhint %}

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

{% code overflow="wrap" %}

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

{% endcode %}

{% hint style="warning" %}
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.
{% endhint %}

***

## Custom Fields API <a href="#custom-fields" id="custom-fields"></a>

### [**List custom fields**](https://v3-api.proto.cx/api/platform/docs#/v1/list_custom_fields_v1_custom_fields__subcompany_id__list_custom_fields_get)

{% code overflow="wrap" %}

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

{% endcode %}

### [**Create custom fields**](https://v3-api.proto.cx/api/platform/docs#/v1/create_custom_fields_v1_custom_fields__subcompany_id__create_custom_field_post)

{% code overflow="wrap" %}

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

{% endcode %}

{% hint style="warning" %}
**select\_options** must be provided only if **type** is **select**.
{% endhint %}

### [**Delete custom fields**](https://v3-api.proto.cx/api/platform/docs#/v1/delete_custom_fields_v1_custom_fields__subcompany_id__custom_field__custom_field_id__delete_custom_fields_delete)

{% code overflow="wrap" %}

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

{% endcode %}