Skip to main content
All CollectionsProduct GuidesIntegrations
Contact API
Contact API

This guide will help you create or update contact in your charles account using our API. The following instructions will walk you through the process step-by-step.

Updated over 2 weeks ago

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.

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_id which 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/json

  • x-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

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

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.id field).

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-8

  • x-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>

How to Obtain the Person ID

The personID parameter is returned in the response when creating or updating a contact via the API. You can find it in the data.id field of the response.

For example, when you create or update a contact, the response includes:

{ "data": { "id": "e4430422-f8d0-4912-aa0e-094e75e92e6c", // other contact information } }

In this case, e4430422-f8d0-4912-aa0e-094e75e92e6c is the personID you would use for deletion.

Response

Upon successful deletion, the API will return a success response. The contact will be permanently deleted from the system in compliance with GDPR requirements.

Payload

{ "data": { "jobId": "contacts-cleanup" }, "msg": "GDPR delete contact job scheduled successfully", "errors": [], "localized_messages": [], "messages": [], "status": 200, "request": { "host": "customername.hello-charles.com", "id": "101f5529-6b4e-4602-85ac-fdef6f1fa3c3" } }

Important Notes

  1. Irreversible Action: Contact deletion is permanent and cannot be undone. Make sure you're deleting the correct contact.

  2. Data Retention: While the deletion is immediate, some data might be retained in backups for a limited period as allowed by GDPR regulations.

Did this answer your question?