Create or update a contact
curl --request POST \
--url https://api.chatsailer.com/v1/contacts/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"first_name": "<string>",
"phone": "<string>",
"address": "<string>",
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "crm-48213",
"job_title": "<string>",
"last_name": "<string>",
"on_match": "update",
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"state": "<string>",
"visibility": "company"
}
'import requests
url = "https://api.chatsailer.com/v1/contacts/upsert"
payload = {
"first_name": "<string>",
"phone": "<string>",
"address": "<string>",
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "crm-48213",
"job_title": "<string>",
"last_name": "<string>",
"on_match": "update",
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"state": "<string>",
"visibility": "company"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
first_name: '<string>',
phone: '<string>',
address: '<string>',
city: '<string>',
company_name: '<string>',
custom_fields: {},
email: '<string>',
external_id: 'crm-48213',
job_title: '<string>',
last_name: '<string>',
on_match: 'update',
organization: {id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4', name: '<string>'},
organization_id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
owner_id: 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
state: '<string>',
visibility: 'company'
})
};
fetch('https://api.chatsailer.com/v1/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.chatsailer.com/v1/contacts/upsert",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'first_name' => '<string>',
'phone' => '<string>',
'address' => '<string>',
'city' => '<string>',
'company_name' => '<string>',
'custom_fields' => [
],
'email' => '<string>',
'external_id' => 'crm-48213',
'job_title' => '<string>',
'last_name' => '<string>',
'on_match' => 'update',
'organization' => [
'id' => 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'name' => '<string>'
],
'organization_id' => 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'owner_id' => 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'state' => '<string>',
'visibility' => 'company'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.chatsailer.com/v1/contacts/upsert"
payload := strings.NewReader("{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.chatsailer.com/v1/contacts/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.chatsailer.com/v1/contacts/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"id": "con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"status": "open",
"updated_at": "2023-11-07T05:31:56Z",
"visibility": "private",
"address": "<string>",
"avatar_url": "<string>",
"channels": [
{
"identifier": "<string>",
"platform": "<string>",
"status": "<string>",
"username": "<string>"
}
],
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"lost_reason": "<string>",
"name": "<string>",
"object": "contact",
"organization": {
"created_at": "2023-11-07T05:31:56Z",
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"visibility": "private",
"custom_fields": {},
"external_id": "<string>",
"object": "organization",
"owner": {
"id": "<string>",
"kind": "user",
"name": "<string>",
"object": "owner"
},
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"tags": [
{
"id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"color": "<string>",
"object": "tag"
}
],
"website": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"organization_resolution": {
"outcome": "linked",
"candidates": [
{
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
}
],
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"reason": "<string>"
},
"owner": {
"id": "<string>",
"kind": "user",
"name": "<string>",
"object": "owner"
},
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"phone": "<string>",
"score": "cold",
"state": "<string>",
"tags": [
{
"id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"color": "<string>",
"object": "tag"
}
]
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}Contacts
Create or update a contact
The endpoint to build a sync on. Matches an existing contact by phone; creates one when there is no match.
Returns 201 when a contact was created and 200 when an existing one was matched. The update half is a patch: upsert never clears a field you did not send.
Accepts organization like POST /v1/contacts. On a match, a name only links a contact that has no organization yet.
Safe to run concurrently — two simultaneous upserts with the same phone produce one contact, not a duplicate.
POST
/
v1
/
contacts
/
upsert
Create or update a contact
curl --request POST \
--url https://api.chatsailer.com/v1/contacts/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"first_name": "<string>",
"phone": "<string>",
"address": "<string>",
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "crm-48213",
"job_title": "<string>",
"last_name": "<string>",
"on_match": "update",
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"state": "<string>",
"visibility": "company"
}
'import requests
url = "https://api.chatsailer.com/v1/contacts/upsert"
payload = {
"first_name": "<string>",
"phone": "<string>",
"address": "<string>",
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "crm-48213",
"job_title": "<string>",
"last_name": "<string>",
"on_match": "update",
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"state": "<string>",
"visibility": "company"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
first_name: '<string>',
phone: '<string>',
address: '<string>',
city: '<string>',
company_name: '<string>',
custom_fields: {},
email: '<string>',
external_id: 'crm-48213',
job_title: '<string>',
last_name: '<string>',
on_match: 'update',
organization: {id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4', name: '<string>'},
organization_id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
owner_id: 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
state: '<string>',
visibility: 'company'
})
};
fetch('https://api.chatsailer.com/v1/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.chatsailer.com/v1/contacts/upsert",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'first_name' => '<string>',
'phone' => '<string>',
'address' => '<string>',
'city' => '<string>',
'company_name' => '<string>',
'custom_fields' => [
],
'email' => '<string>',
'external_id' => 'crm-48213',
'job_title' => '<string>',
'last_name' => '<string>',
'on_match' => 'update',
'organization' => [
'id' => 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'name' => '<string>'
],
'organization_id' => 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'owner_id' => 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
'state' => '<string>',
'visibility' => 'company'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.chatsailer.com/v1/contacts/upsert"
payload := strings.NewReader("{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.chatsailer.com/v1/contacts/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.chatsailer.com/v1/contacts/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"first_name\": \"<string>\",\n \"phone\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"company_name\": \"<string>\",\n \"custom_fields\": {},\n \"email\": \"<string>\",\n \"external_id\": \"crm-48213\",\n \"job_title\": \"<string>\",\n \"last_name\": \"<string>\",\n \"on_match\": \"update\",\n \"organization\": {\n \"id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"name\": \"<string>\"\n },\n \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n \"state\": \"<string>\",\n \"visibility\": \"company\"\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"id": "con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"status": "open",
"updated_at": "2023-11-07T05:31:56Z",
"visibility": "private",
"address": "<string>",
"avatar_url": "<string>",
"channels": [
{
"identifier": "<string>",
"platform": "<string>",
"status": "<string>",
"username": "<string>"
}
],
"city": "<string>",
"company_name": "<string>",
"custom_fields": {},
"email": "<string>",
"external_id": "<string>",
"first_name": "<string>",
"job_title": "<string>",
"last_name": "<string>",
"lost_reason": "<string>",
"name": "<string>",
"object": "contact",
"organization": {
"created_at": "2023-11-07T05:31:56Z",
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"visibility": "private",
"custom_fields": {},
"external_id": "<string>",
"object": "organization",
"owner": {
"id": "<string>",
"kind": "user",
"name": "<string>",
"object": "owner"
},
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"tags": [
{
"id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"color": "<string>",
"object": "tag"
}
],
"website": "<string>"
},
"organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"organization_resolution": {
"outcome": "linked",
"candidates": [
{
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
}
],
"organization": {
"id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>"
},
"reason": "<string>"
},
"owner": {
"id": "<string>",
"kind": "user",
"name": "<string>",
"object": "owner"
},
"owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"phone": "<string>",
"score": "cold",
"state": "<string>",
"tags": [
{
"id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
"name": "<string>",
"color": "<string>",
"object": "tag"
}
]
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"type": "invalid_request_error",
"detail": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"documentation_url": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}Authorizations
A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.
Headers
A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a 409 idempotency_key_reused.
Maximum string length:
255Query Parameters
Comma-separated relationships to inline in the response, e.g. organization. Unexpanded relations are still identified by their *_id field.
Example:
"organization"
Body
application/json
Body for POST /v1/contacts/upsert.
Matched on external_id when you send one, otherwise on phone. Phones are
unique per workspace and normalized before comparison, so (11) 98765-4321
and +55 11 98765-4321 are the same key. A phone match without an
external_id yet is given yours. A deleted contact that matches is restored.
Required; a nameless contact is not useful.
Minimum string length:
1Required. Any format; normalized to E.164.
Legacy alias for organization. The text is kept on the contact, and a contact that has no organization yet is also linked to the organization this name matches, or to a new one when none does. To say which organization a contact belongs to, send organization, which also tells you how the name was resolved.
Your own id for this record, e.g. its id in your system. Unique per workspace and resource; send null to clear it.
Required string length:
1 - 255Example:
"crm-48213"
What to do when the contact already exists.
Available options:
update, ignore The organization this contact belongs to: {"id": ...} to link one you picked, or {"name": ...} to match or create it by name. Send exactly one. The response carries organization_resolution. Do not combine with organization_id.
Show child attributes
Show child attributes
Unique identifier for an organization.
Pattern:
^org_[0-9a-f]{32}$Example:
"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"
Unique identifier for an user.
Pattern:
^usr_[0-9a-f]{32}$Example:
"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"
Who in the workspace can see a record: only its owner, the owner's team, the team and its sub-teams, or everyone.
Available options:
private, team, team_and_subteams, company Response
Successful Response
A contact as returned by create, update and upsert.
The same object as on reads, plus organization_resolution when the request
carried organization.
Unique identifier for a contact.
Pattern:
^con_[0-9a-f]{32}$Example:
"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"
Where the contact stands.
Available options:
open, on_hold, won, lost Who in the workspace can see this record. A workspace token sees every record regardless; an OAuth token sees what the person who authorized it can see.
Available options:
private, team, team_and_subteams, company Short-lived signed URL; do not store it.
Show child attributes
Show child attributes
Legacy alias for organization. The text is kept on the contact, and a contact that has no organization yet is also linked to the organization this name matches, or to a new one when none does. To say which organization a contact belongs to, send organization, which also tells you how the name was resolved.
Every custom field defined on contacts in this workspace, keyed by field key and typed from its definition. Unset fields are null, so reading any contact shows the full set of keys in use.
Your own id for this record, when you set one.
Name of the reason, when status is lost.
Display name. Derived from first_name and last_name.
Allowed value:
"contact"Populated only when organization is in expand.
Show child attributes
Show child attributes
Unique identifier for an organization.
Pattern:
^org_[0-9a-f]{32}$Example:
"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"
How organization was resolved. Present only when the request sent organization.
Show child attributes
Show child attributes
Whoever is responsible for this record. Always populated when the record has an owner — this is not an expand target.
Show child attributes
Show child attributes
Unique identifier for an user.
Pattern:
^usr_[0-9a-f]{32}$Example:
"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"
E.164. Normalized on write.
How warm a contact is.
Available options:
cold, warm, hot Show child attributes
Show child attributes