Create person

Create person

curl --request POST \
  --url https://api.withallo.com/v2/api/crm/people \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "John",
  "last_name": "Doe",
  "job_title": "CEO",
  "website": "https://example.com",
  "address": "123 Main St",
  "numbers": [
    "+33612345678"
  ],
  "emails": [
    "[email protected]"
  ],
  "company_id": "com-xyz789",
  "custom_attributes": {
    "lead_source": "Webinar",
    "budget": 5000
  }
}
'

import requests

url = "https://api.withallo.com/v2/api/crm/people"

payload = {
    "name": "John",
    "last_name": "Doe",
    "job_title": "CEO",
    "website": "https://example.com",
    "address": "123 Main St",
    "numbers": ["+33612345678"],
    "emails": ["[email protected]"],
    "company_id": "com-xyz789",
    "custom_attributes": {
        "lead_source": "Webinar",
        "budget": 5000
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'John',
    last_name: 'Doe',
    job_title: 'CEO',
    website: 'https://example.com',
    address: '123 Main St',
    numbers: ['+33612345678'],
    emails: ['[email protected]'],
    company_id: 'com-xyz789',
    custom_attributes: {lead_source: 'Webinar', budget: 5000}
  })
};

fetch('https://api.withallo.com/v2/api/crm/people', 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.withallo.com/v2/api/crm/people",
  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([
    'name' => 'John',
    'last_name' => 'Doe',
    'job_title' => 'CEO',
    'website' => 'https://example.com',
    'address' => '123 Main St',
    'numbers' => [
        '+33612345678'
    ],
    'emails' => [
        '[email protected]'
    ],
    'company_id' => 'com-xyz789',
    'custom_attributes' => [
        'lead_source' => 'Webinar',
        'budget' => 5000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.withallo.com/v2/api/crm/people"

	payload := strings.NewReader("{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	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.withallo.com/v2/api/crm/people")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withallo.com/v2/api/crm/people")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "per-abc123",
    "name": "John",
    "last_name": "Doe",
    "job_title": "CEO",
    "website": "https://example.com",
    "address": "123 Main St",
    "numbers": [
      "+33612345678"
    ],
    "emails": [
      "[email protected]"
    ],
    "company": {
      "id": "com-xyz789",
      "name": "Acme Corp"
    },
    "interactions": 5,
    "last_activity_at": "2026-04-28T10:30:00",
    "created_at": "2026-04-01T09:00:00",
    "updated_at": "2026-04-28T10:30:00",
    "custom_attributes": {
      "lead_source": "Webinar",
      "budget": 5000
    }
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

POST

api

crm

people

Create person

curl --request POST \
  --url https://api.withallo.com/v2/api/crm/people \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "John",
  "last_name": "Doe",
  "job_title": "CEO",
  "website": "https://example.com",
  "address": "123 Main St",
  "numbers": [
    "+33612345678"
  ],
  "emails": [
    "[email protected]"
  ],
  "company_id": "com-xyz789",
  "custom_attributes": {
    "lead_source": "Webinar",
    "budget": 5000
  }
}
'

import requests

url = "https://api.withallo.com/v2/api/crm/people"

payload = {
    "name": "John",
    "last_name": "Doe",
    "job_title": "CEO",
    "website": "https://example.com",
    "address": "123 Main St",
    "numbers": ["+33612345678"],
    "emails": ["[email protected]"],
    "company_id": "com-xyz789",
    "custom_attributes": {
        "lead_source": "Webinar",
        "budget": 5000
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'John',
    last_name: 'Doe',
    job_title: 'CEO',
    website: 'https://example.com',
    address: '123 Main St',
    numbers: ['+33612345678'],
    emails: ['[email protected]'],
    company_id: 'com-xyz789',
    custom_attributes: {lead_source: 'Webinar', budget: 5000}
  })
};

fetch('https://api.withallo.com/v2/api/crm/people', 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.withallo.com/v2/api/crm/people",
  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([
    'name' => 'John',
    'last_name' => 'Doe',
    'job_title' => 'CEO',
    'website' => 'https://example.com',
    'address' => '123 Main St',
    'numbers' => [
        '+33612345678'
    ],
    'emails' => [
        '[email protected]'
    ],
    'company_id' => 'com-xyz789',
    'custom_attributes' => [
        'lead_source' => 'Webinar',
        'budget' => 5000
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.withallo.com/v2/api/crm/people"

	payload := strings.NewReader("{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	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.withallo.com/v2/api/crm/people")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withallo.com/v2/api/crm/people")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"job_title\": \"CEO\",\n  \"website\": \"https://example.com\",\n  \"address\": \"123 Main St\",\n  \"numbers\": [\n    \"+33612345678\"\n  ],\n  \"emails\": [\n    \"[email protected]\"\n  ],\n  \"company_id\": \"com-xyz789\",\n  \"custom_attributes\": {\n    \"lead_source\": \"Webinar\",\n    \"budget\": 5000\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "per-abc123",
    "name": "John",
    "last_name": "Doe",
    "job_title": "CEO",
    "website": "https://example.com",
    "address": "123 Main St",
    "numbers": [
      "+33612345678"
    ],
    "emails": [
      "[email protected]"
    ],
    "company": {
      "id": "com-xyz789",
      "name": "Acme Corp"
    },
    "interactions": 5,
    "last_activity_at": "2026-04-28T10:30:00",
    "created_at": "2026-04-01T09:00:00",
    "updated_at": "2026-04-28T10:30:00",
    "custom_attributes": {
      "lead_source": "Webinar",
      "budget": 5000
    }
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

Required scope: CRM_WRITE

Body fields

Field	Type	Required	Default	Description
`name`	string	no		First name
`last_name`	string	no		Last name
`job_title`	string	no		Job title
`website`	string	no		Website URL
`address`	string	no		Address
`numbers`	array	yes		Phone numbers in E.164 format. At least one number
`emails`	array	no		Email addresses
`company_id`	string	no		Associated company ID
`allow_duplicate_number`	boolean	no	`false`	Allow creating the person even if one or more phone numbers are already assigned to another person
`custom_attributes`	object	no		Values of your custom fields, keyed by field key

At least one of name or last_name is required. A request without numbers, or with an empty list, fails with 400 MISSING_FIELD.

Associations

Pass a company_id to link the person to an existing company. The company must exist or the request returns an error.

Duplicate phone numbers

By default, creating a person with phone numbers that already belong to another person in your team returns a 409 Conflict error. The error response includes the IDs of the existing people so you can update them instead. To create the person anyway, set allow_duplicate_number to true.

{
  "name": "John",
  "numbers": ["+33612345678"],
  "allow_duplicate_number": true
}

To find the existing person by phone number, use Search people with the phone_number filter.

Custom attributes

custom_attributes sets the values of your custom fields. Create the field first, then use its key here.

Attribute type	Accepted value
`TEXT`	A string
`NUMBER`	A finite JSON number. Strings are rejected. Read back as a decimal, so `180` is returned as `180.0`
`BOOLEAN`	A JSON boolean
`DATE`	`YYYY-MM-DD` or an ISO datetime. Stored as a date and returned as `YYYY-MM-DD`
`DROPDOWN`	An option key or label, case-insensitive. Always returned as the option key

Send null for a key to clear its value.
Keys you leave out are not changed. {}, or leaving out custom_attributes, changes nothing.
An unknown or archived key returns 400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN. A value of the wrong type returns 400 CUSTOM_ATTRIBUTE_VALUE_INVALID. In both cases param is custom_attributes.<key>.
The whole request is validated before anything is written, so a rejected request creates nothing.
The response always includes custom_attributes, {} when the person has none. Archived attributes and empty values are left out.
Values are also synced to your connected CRMs that create contacts. A value on an attribute that is synced from a CRM can be overwritten by the next CRM sync.

Example

The budget number is read back as a decimal.

{
  "name": "John",
  "numbers": ["+33612345678"],
  "custom_attributes": {
    "lead_source": "Webinar",
    "budget": 5000
  }
}

{
  "data": {
    "id": "per-abc123",
    "name": "John",
    "numbers": ["+33612345678"],
    "custom_attributes": {
      "lead_source": "Webinar",
      "budget": 5000.0
    }
  }
}

Authorizations

Authorization

string

header

required

Body

application/json

Request body for creating a person

numbers

string[]

required

Phone numbers in E.164 format. At least one number is required.

Minimum array length: 1

Example:

["+33612345678"]

name

string | null

First name

Example:

"John"

last_name

string | null

Last name

Example:

"Doe"

job_title

string | null

Job title

Example:

"CEO"

website

string | null

Website URL

Example:

"https://example.com"

address

string | null

Postal address

Example:

"123 Main St"

emails

string[] | null

Email addresses

Example:

["[email protected]"]

company_id

string | null

ID of the company to associate with

Example:

"com-xyz789"

allow_duplicate_number

boolean

default:false

When true, allows creating a person even if the phone numbers are already assigned to another person. Defaults to false.

custom_attributes

object | null

Values for the person's custom attributes, keyed by attribute key. TEXT takes a string, NUMBER a finite JSON number (numeric strings are rejected), BOOLEAN a JSON boolean, DATE a YYYY-MM-DD string or ISO datetime, and DROPDOWN an option key or label (case-insensitive). Send null to clear a value; keys you omit are left untouched, and {} or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with CUSTOM_ATTRIBUTE_KEY_UNKNOWN or CUSTOM_ATTRIBUTE_VALUE_INVALID.

Example:

{ "lead_source": "Webinar", "budget": 5000 }

Response

Person created

data

object

A person in the CRM

Show child attributes

API

Webhooks

Conversations

CRM

People

Custom fields

Views

Companies

Deals

Notes

Threads

Inboxes

Phone Numbers

AI Receptionist

Tags

Summary Templates

Users

SMS

Analytics

Power Dialer

Partner

Body fields

Associations

Duplicate phone numbers

Custom attributes

Example

Authorizations

Body

Response

​Body fields

​Associations

​Duplicate phone numbers

​Custom attributes

​Example

Authorizations

Body

Response

Body fields

Associations

Duplicate phone numbers

Custom attributes

Example