# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.proto.cx/docs/developer-documentation/developer-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.