# Create a contact

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.

Source: https://dev.alterestate.com/contacts/create
Last updated: 2026-10-13

> Use this endpoint only when you need a contact record and nothing else. If you are sending a lead from a website form, a landing page or an ad, use the Leads API. Leads creates or reuses the contact and opens a deal for the agent who receives it. Create a contact does not open a deal.

- [Leads API: send a lead to the CRM](https://dev.alterestate.com/leads)

```http
POST https://secure.alterestate.com/api/v1/contacts/new/
```

Authentication: `Authorization: Token your_api_key_here`

| Parameter | In | Type | Required | Group | Description |
| --- | --- | --- | --- | --- | --- |
| `full_name` | body | string | yes | Contact | Display name. |
| `email` | body | string | no | Contact | Stored lowercase. |
| `phone` | body | string | no | Contact | Main phone. Stored in E.164. |
| `is_company` | body | boolean | no | Contact | true when the contact is a company. |
| `language` | body | string | no | Contact | es_ES or en_US. Defaults to es_ES. |
| `description` | body | string | no | Contact | Notes. |
| `ctype` | body | number | no | Contact | Contact type id configured by the agency. |
| `tag` | body | string | no | Contact | Tag uid. |
| `via` | body | number | no | Contact | Lead source id. |
| `ced_rnc` | body | string | no | Identity | Identity document. Required only when the agency turned that requirement on. |
| `doc_type` | body | string | no | Identity | dni, passport, rnc, license or ssn. |
| `job_position` | body | string | no | Work | Job title. |
| `job_place` | body | string | no | Work | Company or workplace. |
| `address` | body | string | no | Work | Free-text address. |
| `birthdate` | body | date | no | Work | YYYY-MM-DD. |
| `related` | body | array | no | Agents | Numeric user ids of the assigned agents. Omit it to assign the token’s user. These are ids, not uids. |
| `phones` | body | array | no | Extra phones | Extra phones. Each item has phone and an optional description: 1 work, 2 home, 3 mobile, 4 other. |
| `custom_fields` | body | object | no | Custom fields | Keys must match active contact custom fields. List them with GET /api/v1/custom-fields/?app=contacts. |
| `integration_id` | body | string | no | External | Id from your own system. |

Example request:

```bash
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"
  }
}'
```

Response 201 Created:

```json
{
  "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"
    }
  ]
}
```

Response 403 Forbidden:

```json
"Este contacto ya se encuentra registrado."
```

Response 400 Bad Request:

```json
{
  "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. |

> The contact stays with the user who registered it. This call does not create a deal. Send the inquiry through the Leads API when the goal is a lead.

- [Retrieve a contact](https://dev.alterestate.com/contacts/retrieve)
- [Edit a contact](https://dev.alterestate.com/contacts/edit)
- [Create a lead](https://dev.alterestate.com/leads)

## FAQ

### 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.