Create or update a contact

curl --request PUT \
  --url https://api.chatsailer.com/v1/contacts \
  --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>",
  "job_title": "<string>",
  "last_name": "<string>",
  "on_match": "update",
  "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "state": "<string>",
  "visibility": "company"
}
'

import requests

url = "https://api.chatsailer.com/v1/contacts"

payload = {
    "first_name": "<string>",
    "phone": "<string>",
    "address": "<string>",
    "city": "<string>",
    "company_name": "<string>",
    "custom_fields": {},
    "email": "<string>",
    "job_title": "<string>",
    "last_name": "<string>",
    "on_match": "update",
    "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "state": "<string>",
    "visibility": "company"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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>',
    job_title: '<string>',
    last_name: '<string>',
    on_match: 'update',
    organization_id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
    owner_id: 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
    state: '<string>',
    visibility: 'company'
  })
};

fetch('https://api.chatsailer.com/v1/contacts', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => '<string>',
    'phone' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'company_name' => '<string>',
    'custom_fields' => [
        
    ],
    'email' => '<string>',
    'job_title' => '<string>',
    'last_name' => '<string>',
    'on_match' => 'update',
    '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"

	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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\n  \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n  \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n  \"state\": \"<string>\",\n  \"visibility\": \"company\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://api.chatsailer.com/v1/contacts")
  .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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\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")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\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>",
  "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",
    "object": "organization",
    "owner": {
      "id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
      "email": "<string>",
      "name": "<string>",
      "object": "user"
    },
    "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "tags": [
      {
        "id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
        "name": "<string>",
        "color": "<string>",
        "object": "tag"
      }
    ],
    "website": "<string>"
  },
  "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "owner": {
    "id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "email": "<string>",
    "name": "<string>",
    "object": "user"
  },
  "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "phone": "<string>",
  "score": "cold",
  "state": "<string>",
  "tags": [
    {
      "id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
      "name": "<string>",
      "color": "<string>",
      "object": "tag"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

PUT

contacts

Create or update a contact

curl --request PUT \
  --url https://api.chatsailer.com/v1/contacts \
  --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>",
  "job_title": "<string>",
  "last_name": "<string>",
  "on_match": "update",
  "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "state": "<string>",
  "visibility": "company"
}
'

import requests

url = "https://api.chatsailer.com/v1/contacts"

payload = {
    "first_name": "<string>",
    "phone": "<string>",
    "address": "<string>",
    "city": "<string>",
    "company_name": "<string>",
    "custom_fields": {},
    "email": "<string>",
    "job_title": "<string>",
    "last_name": "<string>",
    "on_match": "update",
    "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "state": "<string>",
    "visibility": "company"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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>',
    job_title: '<string>',
    last_name: '<string>',
    on_match: 'update',
    organization_id: 'org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
    owner_id: 'usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4',
    state: '<string>',
    visibility: 'company'
  })
};

fetch('https://api.chatsailer.com/v1/contacts', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => '<string>',
    'phone' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'company_name' => '<string>',
    'custom_fields' => [
        
    ],
    'email' => '<string>',
    'job_title' => '<string>',
    'last_name' => '<string>',
    'on_match' => 'update',
    '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"

	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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\n  \"organization_id\": \"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n  \"owner_id\": \"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4\",\n  \"state\": \"<string>\",\n  \"visibility\": \"company\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://api.chatsailer.com/v1/contacts")
  .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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\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")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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  \"job_title\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"on_match\": \"update\",\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>",
  "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",
    "object": "organization",
    "owner": {
      "id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
      "email": "<string>",
      "name": "<string>",
      "object": "user"
    },
    "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "tags": [
      {
        "id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
        "name": "<string>",
        "color": "<string>",
        "object": "tag"
      }
    ],
    "website": "<string>"
  },
  "organization_id": "org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "owner": {
    "id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
    "email": "<string>",
    "name": "<string>",
    "object": "user"
  },
  "owner_id": "usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
  "phone": "<string>",
  "score": "cold",
  "state": "<string>",
  "tags": [
    {
      "id": "tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4",
      "name": "<string>",
      "color": "<string>",
      "object": "tag"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

Authorizations

Authorization

string

header

required

A workspace API token. Create one in Settings → API. Send it as Authorization: Bearer sk_live_....

Query Parameters

expand

string | null

Comma-separated relationships to inline in the response. Unexpanded relations are still identified by their *_id field.

Example:

"organization,owner"

Body

application/json

Body for PUT /v1/contacts.

Matched on phone, which is unique per workspace and canonicalized before comparison, so (11) 98765-4321 and +55 11 98765-4321 are the same key.

first_name

string

required

Required; a nameless contact is not useful.

Minimum string length: 1

phone

string

required

Required. Any format; normalized to E.164.

address

string | null

city

string | null

company_name

string | null

custom_fields

Custom Fields · object

string | null

job_title

string | null

last_name

string | null

on_match

enum<string>

default:update

What to do when a contact with this phone already exists.

Available options:

update,

ignore

organization_id

string | null

Unique identifier for an organization.

Pattern: ^org_[0-9a-f]{32}$

Example:

"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

owner_id

string | null

Unique identifier for an user.

Pattern: ^usr_[0-9a-f]{32}$

Example:

"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

state

string | null

visibility

enum<string>

default:company

CRM record visibility levels; resolved live against the owner's current teams.

Available options:

private,

team,

team_and_subteams,

company

Response

Successful Response

A person in your CRM.

created_at

string<date-time>

required

string

required

Unique identifier for a contact.

Pattern: ^con_[0-9a-f]{32}$

Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

status

enum<string>

required

Where the contact stands.

Available options:

open,

on_hold,

won,

lost

updated_at

string<date-time>

required

visibility

enum<string>

required

Governs who sees this record in the Sailer UI. API tokens are workspace-scoped and are not filtered by it.

Available options:

private,

team,

team_and_subteams,

company

address

string | null

avatar_url

string | null

Short-lived signed URL; do not store it.

channels

ContactChannel · object[]

Show child attributes

city

string | null

company_name

string | null

Free-text employer name. Unrelated to your workspace and to organization, which is a CRM record.

custom_fields

Custom Fields · object

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.

string | null

first_name

string | null

job_title

string | null

last_name

string | null

lost_reason

string | null

Name of the reason, when status is lost.

name

string | null

Display name. Derived from first_name and last_name.

object

string

default:contact

Allowed value: "contact"

organization

Organization · object | null

Populated only when organization is in expand.

Show child attributes

organization_id

string | null

Unique identifier for an organization.

Pattern: ^org_[0-9a-f]{32}$

Example:

"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

owner

User · object | null

Populated only when owner is in expand.

Show child attributes

owner_id

string | null

Unique identifier for an user.

Pattern: ^usr_[0-9a-f]{32}$

Example:

"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

phone

string | null

E.164. Normalized on write.

score

enum<string> | null

Available options:

cold,

warm,

hot

state

string | null

Heartbeat

Meta

Contacts

Create or update a contact

Authorizations

Query Parameters

Body

Response