This API is in closed beta. If you’re interested in using it, please reach out to your success manager.
Overview
Our API allows you to manage contacts efficiently. This is particularly useful for maintaining accurate and up-to-date records of your contacts from external systems. Below is the detailed information on how to use the API to update these properties.
Look up a contact's ID
If you store your own identifier for a contact (for example a CRM or customer-data-platform ID) but not the Charles personID, you can look the personID up on demand instead of storing it.
GET /api/v0/people?external_person_reference_id=<your-id>
Returns the contact(s) matching an external reference ID, including the internal id — this is the personID you use to delete a contact.
Pass one value, or repeat the parameter for several:
?external_person_reference_id=id1&external_person_reference_id=id2Send at most 100 IDs per request. The response returns up to 100 results per page, and longer requests can hit URL-length limits.
For larger sets, page through results with
limit(default 100, max 100) andoffset.external_person_reference_idis the only filter on this endpoint.source_typeis not a filter here — to filter by channel, use/api/v0/people/{id}/channel_users.
Example response:
[
{ "id": "1f2a…", "external_person_reference_id": "ext-12345", "first_name": "Max" }
]
Create or Update Contacts
Prerequisites
API Key: Make sure you have your API key ready. This is required to authenticate your requests.
Contact Details: Ensure you have the correct contact details, including the
external_reference_idwhich is typically the contact's phone number.
API Endpoint
To update contact properties, you will use the following endpoint:
PUT <https://customer-name.hello-charles.com/api/v1beta/contacts>
Request Headers
Ensure your request includes the following headers:
Content-Type: application/jsonx-api-key: your-api-key
Request Body
The request body should be in JSON format and include the following fields:
external_reference_id: (Required) The unique identifier for the contact, usually the phone number.source_type: (Required) The source of the contact, e.g., “segment”, “salesforce”.custom_properties: A JSON object containing the custom properties you wish to update.phone_numbers: A JSON array of objects containing the phone numbers you want to associate with the profile.email_address: A JSON array of objects containing the email addresses you want to associate with the profile.first_name: A string with the customer’s first name.middle_name: A string with the customer’s middle name.last_name: A string with the customer’s last name.tags: A JSON array of tags to associate with the customer.
You can find the technical name of the 🎨Custom properties in Settings.
Example Request
Here is an example of a curl command to update contact properties:
curl --location --request PUT 'https://customer-name.hello-charles.com/api/v1beta/contacts' \
--header 'Content-Type: application/json' \
--header 'x-api-key: you-api-key' \
--data '{
"external_reference_id": "+4911111111",
"source_type": "segment",
"custom_properties": {
"a": "a",
"b": "b2"
},
"phone_numbers":[
{
"type":"mobile",
"value":"+4911111122"
}
],
"email_addresses":[
{
"type":"main",
"value":"[email protected]"
},
],
"first_name":"molestias",
"last_name":"repellendus",
"middle_name":"est",
"tags":[
"atque"
],
}'
Response
Upon a successful request, the API will return a response indicating the updated properties of the contact.
Payload
Payload
{
"status": 200,
"msg": "Upserted contact successfully.",
"messages": [],
"localized_messages": [],
"errors": [],
"request": {
"host": "customer-name.hello-charles.com",
"id": "40e8e39c-7072-4e95-b86b-928505ea248d"
},
"data": {
"id": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"kind": "Contact",
"first_name": "molestias",
"nickname": null,
"middle_name": "est",
"last_name": "repellendus",
"name": null,
"avatar": null,
"email": null,
"date_of_birth": null,
"created_at": "2025-01-23T10:26:15.847Z",
"updated_at": "2025-01-23T10:26:16.388Z",
"gender": null,
"comment": null,
"deleted": false,
"active": true,
"measurements": null,
"annotations": null,
"custom_properties": {},
"tags": [
"atque",
"at",
"enim",
"possimus",
"error",
"pariatur",
"voluptatum"
],
"name_preference": null,
"language_preference": null,
"parents": [],
"default_address": null,
"assumed_language": null,
"addresses": [],
"phonenumbers": [
{
"id": "5e3e1c77-4d3f-4988-b77e-8aea277fd5c2",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "mobile",
"value": "49111111111",
"created_at": "2025-01-23T10:26:15.914",
"updated_at": "2025-01-23T10:26:41.988",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "017f807d-e0df-46b5-9f65-a4b6f0f68083",
"is_proxy": false,
"proxy_vendor": "",
"is_portable": null,
"portability": null
}
],
"channel_users": [
{
"id": "017f807d-e0df-46b5-9f65-a4b6f0f68083",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"updated_at": "2025-01-23T10:26:41.964",
"created_at": "2025-01-23T10:26:15.848",
"last_source_fetch_at": "2025-01-23T10:26:15.848",
"broker": "charles_messaging_whatsapp",
"external_person_reference_id": "49111111111",
"last_external_person_reference_id": null,
"external_person_custom_id": "49111111111",
"external_channel_reference_id": "4911111111",
"source_type": "whatsapp",
"payload_name": null,
"first_name": null,
"middle_name": null,
"last_name": null,
"email": null,
"phone": null,
"name": null,
"payload": null,
"source_api": "charles_messaging_whatsapp",
"active": true,
"deleted": false,
"external_organization_reference_ids": null,
"organizations": null,
"comment": null,
"links": null,
"verified": false,
"last_verified_at": null,
"last_cached_at": null,
"custom_properties": null,
"channel_profile": null
},
{
"id": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"updated_at": "2025-01-23T10:26:41.964",
"created_at": "2025-01-23T10:26:15.848",
"last_source_fetch_at": "2025-01-23T10:26:15.848",
"broker": "debitis",
"external_person_reference_id": "sequi",
"last_external_person_reference_id": null,
"external_person_custom_id": null,
"external_channel_reference_id": "quasi",
"source_type": "debitis",
"payload_name": null,
"first_name": "molestias",
"middle_name": "est",
"last_name": "repellendus",
"email": null,
"phone": null,
"name": null,
"payload": {
"tags": [
"atque"
],
"last_name": "repellendus",
"first_name": "molestias",
"middle_name": "est",
"source_type": "debitis",
"phone_numbers": [
{
"type": "mobile",
"value": "+4911111111"
}
],
"email_addresses": [
{
"type": "main",
"value": "[email protected]"
},
{
"type": "main",
"value": "[email protected]"
},
{
"type": "other",
"value": "[email protected]"
},
{
"type": "personal",
"value": "[email protected]"
},
{
"type": "personal",
"value": "[email protected]"
}
],
"custom_properties": {
"corrupti": "quas"
},
"external_reference_id": "sequi",
"external_channel_reference_id": "quasi"
},
"source_api": "debitis",
"active": true,
"deleted": false,
"external_organization_reference_ids": null,
"organizations": null,
"comment": null,
"links": null,
"verified": false,
"last_verified_at": null,
"last_cached_at": null,
"custom_properties": {},
"channel_profile": null
}
],
"emails": [
{
"id": "ed196749-9e7e-4fa4-b3a0-f81614eded9b",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "other",
"value": "[email protected]",
"created_at": "2025-01-23T10:26:15.915",
"updated_at": "2025-01-23T10:26:41.988",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"proxy_vendor": ""
},
{
"id": "8acf51e3-8700-4a45-9124-1ee965995eaf",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "main",
"value": "[email protected]",
"created_at": "2025-01-23T10:26:15.915",
"updated_at": "2025-01-23T10:26:41.988",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"proxy_vendor": ""
},
{
"id": "4030ecb2-b3c6-4ce3-a068-49cfcde559de",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "personal",
"value": "[email protected]",
"created_at": "2025-01-23T10:26:15.915",
"updated_at": "2025-01-23T10:26:41.988",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"proxy_vendor": ""
},
{
"id": "11c8c439-c377-43cd-a478-6142cadd2013",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "main",
"value": "[email protected]",
"created_at": "2025-01-23T10:26:15.915",
"updated_at": "2025-01-23T10:26:41.988",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"proxy_vendor": ""
},
{
"id": "718341c2-f29a-40ef-8ab2-8de22149259d",
"person": "e4430422-f8d0-4912-aa0e-094e75e92e6c",
"type": "personal",
"value": "[email protected]",
"created_at": "2025-01-23T10:26:15.915",
"updated_at": "2025-01-23T10:26:41.989",
"comment": null,
"deleted": false,
"active": true,
"channel_user": "f4620600-6427-43fa-9eb3-dd0ee33f28b8",
"proxy_vendor": ""
}
],
"direct_feed": "56360679-5624-4256-a4fd-23122e97a11e"
}
}
Batch Operations
To update multiple contacts in a single request, use PUT /v1beta/batched-contacts with an array of contacts (1-1000). The request and response format is identical except the input is an array and the response returns an array of results.
Duplicate contacts in a single request
Each contact in a batch is identified by its external_reference_id together with its source_type. If one request contains more than one entry with the same pair, those entries are skipped — we don't try to guess which version is correct. Every other contact in the request is still created or updated.
The request still returns 200, and the skipped entries are listed in the errors array so you can see exactly what wasn't applied (each entry also includes a plain-language reason):
{
"status": 200,
"msg": "Upserted 5 contact(s). Skipped 1 ambiguous duplicate key(s) within the request — see errors.",
"errors": [
{
"external_reference_id": "ext-12345",
"source_type": "my_crm",
"occurrences": 2
}
]
}
Best practice: send each contact only once per request. To update a contact you've already sent, send it in a later request.
Delete contacts in bulk (GDPR)
To delete many contacts at once, use the bulk endpoint (single-contact deletion is documented above).
DELETE /api/v0/people?gdpr=true
Deletes up to 2,000 contacts by personID in one call.
The
gdprquery parameter is required (trueorfalse).Body:
{ "people": ["uuid1", "uuid2", …] }As with single-contact deletion, data may be retained in backups for a limited period, as permitted under GDPR.
If you only store your own IDs, resolve them to personIDs first using the lookup endpoint above, then bulk-delete.
Delete contacts
The GDPR (General Data Protection Regulation) requires businesses to provide users with the right to be forgotten. For customers managing their contacts via API, the following explains how to delete contacts from your charles account using our API, ensuring GDPR compliance.
Prerequisites
API Key: You must have a valid API key with appropriate permissions.
Person ID: You need the ID of the contact to be deleted. This is returned in the response data when creating or updating a contact (
data.idfield).
API Endpoint
To delete a contact for GDPR compliance, use the following DELETE endpoint:
DELETE <https://customer-name.hello-charles.com/api/v0/people/cleanup/gdpr/${personID}>Request Header
Ensure your request includes the following headers:
Content-Type: application/json; charset=utf-8x-api-key: your-api-key
Example Request
Here's an example of how to make a DELETE request using JavaScript:
curl -s \\ -X DELETE \\ -H 'Content-Type: application/json; charset=utf-8' \\ -H 'x-api-key: you-api-key' \\ <https://customer-name.hello-charles.com/api/v0/people/cleanup/gdpr/REPLACE_PERSON_ID_HERE>
Rate limits
We don't enforce a formal published rate limit at this time. As a guideline, plan for up to ~10,000 requests per 15 minutes — effective capacity is higher. For large one-off backfills, contact us first so we can confirm capacity or set up a dedicated throughput target.
Important Notes
Irreversible Action: Contact deletion is permanent and cannot be undone. Make sure you're deleting the correct contact.
Data Retention: While the deletion is immediate, some data might be retained in backups for a limited period as allowed by GDPR regulations.