Create a contact

POSThttps://secure.alterestate.com/api/v1/contacts/new/

Creates a contact in your agency. The only required field is the name. To send a lead from a form, use the Leads API instead.

Leads API: send a lead to the CRM

Authentication

Send Authorization: Token your_api_key_here. Account token. Keep it on your server.

Contact

Field	Type	Description
`full_name`required	string	Display name. Example: `Ana Martinez`.
`email`	string	Stored lowercase. Example: `ana@example.com`.
`phone`	string	Main phone. Stored in E.164. Example: `8095550123`.
`is_company`	boolean	true when the contact is a company. Example: `false`.
`language`	string	es_ES or en_US. Defaults to es_ES. Example: `es_ES`.
`description`	string	Notes. Example: `Looking for a 2-bedroom apartment in Naco.`.
`ctype`	number	Contact type id configured by the agency. Example: `37`.
`tag`	string	Tag uid. Example: `TAG01HOT`.
`via`	number	Lead source id. Example: `4`.

Identity

Field	Type	Description
`ced_rnc`	string	Identity document. Required only when the agency turned that requirement on. Example: `00100000000`.
`doc_type`	string	dni, passport, rnc, license or ssn. Example: `dni`.

Work

Field	Type	Description
`job_position`	string	Job title. Example: `Director`.
`job_place`	string	Company or workplace. Example: `Martinez Group`.
`address`	string	Free-text address. Example: `Naco, Santo Domingo`.
`birthdate`	date	YYYY-MM-DD. Example: `1990-04-12`.

Agents

Field	Type	Description
`related`	array	Numeric user ids of the assigned agents. Omit it to assign the token’s user. These are ids, not uids. Example: `[42]`.

Extra phones

Field	Type	Description
`phones`	array	Extra phones. Each item has phone and an optional description: 1 work, 2 home, 3 mobile, 4 other. Example: `[{"phone":"8095550999","description":"3"}]`.

Custom fields

Field	Type	Description
`custom_fields`	object	Keys must match active contact custom fields. List them with GET /api/v1/custom-fields/?app=contacts. Example: `{"original_source":"instagram"}`.

External

Field	Type	Description
`integration_id`	string	Id from your own system. Example: `crm-10021`.

Example request

POST

curl --request POST \
  --url 'https://secure.alterestate.com/api/v1/contacts/new/' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "full_name": "Ana Martinez",
  "email": "ana@example.com",
  "phone": "8095550123",
  "description": "Looking for a 2-bedroom apartment in Naco.",
  "phones": [
    {
      "phone": "8095550999",
      "description": "3"
    }
  ],
  "custom_fields": {
    "original_source": "instagram"
  }
}'

Example response

201 Created

{
  "uid": "D9dEML2g39",
  "full_name": "Ana Martinez",
  "email": "ana@example.com",
  "phone": "+18095550123",
  "language": "es_ES",
  "description": "Looking for a 2-bedroom apartment in Naco.",
  "custom_fields": {
    "original_source": "instagram"
  },
  "additional_phones": [
    {
      "phone": "+18095550999"
    }
  ]
}

403 Forbidden

"Este contacto ya se encuentra registrado."

400 Bad Request

{
  "full_name": [
    "This field is required."
  ]
}

Duplicates

When the agency does not allow duplicate contacts, a matching email, phone or WhatsApp username returns 403 and the body is the Spanish sentence "Este contacto ya se encuentra registrado." The same phone in phones returns 403 with "El teléfono +1… ya se encuentra registrado." Agencies that allow duplicates create the contact, including when an extra phone already exists on another contact.

Phone and email

email is stored lowercase.
phone and each extra phone are stored in E.164. You can send 8095550123; the response comes back as +18095550123 when the agency country is the Dominican Republic.
If you omit related, the user behind the token is assigned. Send numeric user ids, not uids.

Status codes

Status	Meaning
201	The contact was created.
400	A parameter or the body is invalid. The response names the field.
401	The token is missing or invalid.
403	The contact already exists, or this user cannot edit it.
404	The contact does not exist, or this account cannot open it.
429	Too many requests. Wait and retry.
500	Server error while processing the request.

Frequently asked questions

Should I use Create a contact to send a lead?

No. Use the Leads API (POST /api/v1/leads/). It creates or reuses the contact and opens a deal. Create a contact only stores the person and does not open a deal.

What is the minimum body to create a contact?

POST /api/v1/contacts/new/ with full_name. Email and phone are optional. The token’s user is assigned when you omit related.

What happens if the phone already exists?

If the agency does not allow duplicates, the API responds 403 and does not create a contact. If duplicates are allowed, a new contact is created.

Last updated 2026-10-13. Questions? Emailengineering@alterestate.com.