curl --request POST 'https://api.brightalk.ai/contacts' \
--header "Authorization: Bearer $BRIGHTALK_API_KEY" \
--header "Brightalk-Version: 2026-07-16" \
--header "Content-Type: application/json" \
--data '{"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}'const response = await fetch("https://api.brightalk.ai/contacts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
"Brightalk-Version": "2026-07-16",
"Content-Type": "application/json",
},
body: JSON.stringify({"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}),
});
console.log(response.status, await response.json());import os
import requests
response = requests.request(
"POST",
"https://api.brightalk.ai/contacts",
headers={
"Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
"Brightalk-Version": "2026-07-16",
"Content-Type": "application/json",
},
json={"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"},
)
print(response.status_code, response.json())Create or adopt a contact
Creates, updates, or adopts the canonical organization contact for the supplied external identity and strict E.164 number. The raw JSON body is limited to 1 MiB. Every response includes Brightalk-Version and X-Request-Id; rate-limited responses also expose the effective bucket counters.
curl --request POST 'https://api.brightalk.ai/contacts' \
--header "Authorization: Bearer $BRIGHTALK_API_KEY" \
--header "Brightalk-Version: 2026-07-16" \
--header "Content-Type: application/json" \
--data '{"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}'const response = await fetch("https://api.brightalk.ai/contacts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
"Brightalk-Version": "2026-07-16",
"Content-Type": "application/json",
},
body: JSON.stringify({"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}),
});
console.log(response.status, await response.json());import os
import requests
response = requests.request(
"POST",
"https://api.brightalk.ai/contacts",
headers={
"Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
"Brightalk-Version": "2026-07-16",
"Content-Type": "application/json",
},
json={"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"},
)
print(response.status_code, response.json())Authorizations
Use a server-side Brightalk API key in the Authorization header.
Headers
Selects the date-based API version. Omission uses the organization’s pinned default.
"2026-07-16"A caller-generated correlation value matching [A-Za-z0-9._:-]{1,64}. Invalid values are replaced.
64^[A-Za-z0-9._:-]{1,64}$Body
JSON request body. The raw encoded body is limited to 1 MiB and unknown fields are rejected.
Leading and trailing whitespace is trimmed; the remaining value must contain 1–255 characters.
^\s*\S(?:[\s\S]{0,253}\S)?\s*$"customer-8421"
Leading and trailing whitespace is trimmed; the remaining value must contain 1–255 characters.
^\s*\S(?:[\s\S]{0,253}\S)?\s*$"Example Customer"
A strict E.164 phone number.
^\+[1-9]\d{7,14}$"+12025550123"
An allowlisted identity namespace. Omit to use public_api.
^[a-z][a-z0-9_-]{0,63}$"public_api"
320"customer@example.com"
Leading and trailing whitespace is trimmed; the remaining value may contain at most 255 characters.
^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$"Example Co."
Leading and trailing whitespace is trimmed; the remaining value may contain at most 255 characters.
^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$"Operations Manager"
Leading and trailing whitespace is trimmed; the remaining value may contain at most 255 characters.
^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$"Taipei"
Leading and trailing whitespace is trimmed; the remaining value may contain at most 255 characters.
^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$"TW"
Response
An existing contact was updated or adopted.
An opaque resource identifier.
1 - 255"con_demo_001"
The caller-managed external identity.
"customer-8421"
The external identity namespace.
"public_api"
"Example Customer"
^\+[1-9]\d{7,14}$"+12025550123"
The contact email address.
"customer@example.com"
The contact company.
"Example Co."
The contact role.
"Operations Manager"
The contact city.
"Taipei"
The contact country.
"TW"
When the contact was created.
"2026-07-20T01:00:00Z"
When the contact was last updated.
"2026-07-20T01:00:00Z"