> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keebai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /v1/contacts
> Create a messaging contact on a channel. Company and project come from the token.
Creates a contact. Two fields are mandatory: `channel_type`, and `user_id` — the identifier of the person **inside that channel**. On WhatsApp, `user_id` is the phone number without the leading `+`.
The `company` and `project` are taken from your token and must **not** appear in the body. Sending them returns `400`.
Most contacts create themselves: the first time someone writes to one of your channels, Keebai records them automatically. Use this endpoint when you need a contact to exist *before* the first message — seeding an import, or pre-creating a record so you can attach a CRM ticket to it.
## Endpoint
```
POST https://api.keebai.com/v1/contacts
```
## Required scope
`contacts:write`
## Headers
| Header | Required | Value |
| --------------- | -------- | ------------------------ |
| `Authorization` | Yes | `Bearer kbai_pk_` |
| `Content-Type` | Yes | `application/json` |
## Body
| Field | Type | Required | Description |
| --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `channel_type` | `string` | Yes | One of `web`, `whatsapp`, `whatsapp_qr`, `facebook`, `messenger`, `instagram`, `tiktok`, `telegram`, `email`, `phone`. |
| `user_id` | `string` | Yes | Identifier inside that channel. On WhatsApp, the `wa_id` (phone without `+`). Up to 255 characters. |
| `channel` | `string` | No | `ObjectId` of a specific channel. Without it the contact is bound only to the channel *type*. |
| `username` | `string` | No | Handle on the channel. Up to 200 characters. |
| `first_name` | `string` | No | Up to 200 characters. |
| `last_name` | `string` | No | Up to 200 characters. |
| `phone` | `string` | No | Phone number in E.164, with the `+`. |
| `email` | `string` | No | Valid email address. |
| `profile_pic` | `string` | No | HTTPS URL of the avatar. |
| `custom_fields` | `object` | No | Free-form object matching the custom fields configured for your company. |
## Example request
```bash curl theme={null}
curl -X POST https://api.keebai.com/v1/contacts \
-H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"channel_type": "whatsapp",
"user_id": "56912345678",
"first_name": "Juan",
"last_name": "Pérez",
"phone": "+56912345678",
"email": "juan@example.com"
}'
```
```js JavaScript theme={null}
const response = await fetch("https://api.keebai.com/v1/contacts", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
channel_type: "whatsapp",
user_id: "56912345678",
first_name: "Juan",
last_name: "Pérez",
phone: "+56912345678",
}),
});
const { contact } = await response.json();
```
```python Python theme={null}
import os, requests
resp = requests.post(
"https://api.keebai.com/v1/contacts",
headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
json={
"channel_type": "whatsapp",
"user_id": "56912345678",
"first_name": "Juan",
"last_name": "Pérez",
"phone": "+56912345678",
},
timeout=10,
)
resp.raise_for_status()
contact = resp.json()["contact"]
```
## Response
### 201 Created
```json theme={null}
{
"contact": {
"_id": "65a1f2b3c4d5e6f7a8b9c0d1",
"channel_type": "whatsapp",
"user_id": "56912345678",
"first_name": "Juan",
"last_name": "Pérez",
"phone": "+56912345678",
"email": "juan@example.com",
"custom_fields": {},
"tags": [],
"is_attended": false,
"first_seen_at": "2026-05-02T14:31:07.221Z",
"last_seen_at": "2026-05-02T14:31:07.221Z",
"created_at": "2026-05-02T14:31:07.221Z",
"updated_at": "2026-05-02T14:31:07.221Z"
}
}
```
### 400 Bad Request
Missing `channel_type` or `user_id`, a `channel_type` outside the allowed set, a property the endpoint does not accept — including `company` and `project` — or **a contact that already exists** for that `user_id` and channel.
### 401 Unauthorized
Missing, invalid, revoked, or expired token.
### 403 Forbidden
The token does not have the `contacts:write` scope.
### 502 Bad Gateway
The messaging service could not complete the write.
## Operational notes
* **A duplicate returns `400`, not `409`.** Uniqueness is on `user_id` + channel within your company. Check with [`GET /v1/contacts`](/dev/endpoints/contacts-list) first, filtering by `phone` or `search`, if a collision is plausible.
* **`user_id` is not the same as `phone`.** On WhatsApp `user_id` is `56912345678` while `phone` is `+56912345678`. Getting this wrong creates a contact the inbound webhook will never match, so the same person shows up twice.
* **`playground` is not accepted** as a `channel_type` — it is the internal test channel and is filtered out of every read.
* **`first_seen_at` and `last_seen_at` are stamped at creation**, not left empty, so a seeded contact sorts as if it had just been active.
## OpenAPI
````yaml POST /v1/contacts
openapi: 3.0.0
info:
title: Keebai Public API
description: Superficie pública REST autenticada con Personal Access Tokens (PAT).
version: 1.0.0
contact: {}
servers:
- url: https://api.keebai.com
description: Production
security: []
tags: []
paths:
/v1/contacts:
post:
tags:
- contacts
summary: Crear un contacto
description: >-
La company y el project se toman del token; enviarlos en el body
devuelve 400. Un contacto ya existente con el mismo user_id y canal
devuelve 400.
operationId: PublicContactsController_create
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicContactCreateDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicContactEnvelopeDto'
security:
- PAT: []
components:
schemas:
PublicContactCreateDto:
type: object
properties:
channel_type:
type: string
enum:
- web
- whatsapp
- whatsapp_qr
- facebook
- messenger
- instagram
- tiktok
- telegram
- email
- phone
description: >-
Canal por el que existe el contacto. `playground` no se acepta en la
API pública.
user_id:
type: string
description: >-
Identificador del contacto dentro de ese canal. En WhatsApp es el
wa_id (el teléfono sin +).
channel:
type: string
description: >-
ObjectId del canal concreto. Sin él, el contacto queda asociado sólo
al tipo de canal.
username:
type: string
first_name:
type: string
last_name:
type: string
phone:
type: string
description: Teléfono en formato E.164
email:
type: string
profile_pic:
type: string
description: URL de la foto de perfil
custom_fields:
type: object
description: Campos personalizados de la company
required:
- channel_type
- user_id
PublicContactEnvelopeDto:
type: object
properties:
contact:
$ref: '#/components/schemas/PublicContactResponseDto'
required:
- contact
PublicContactResponseDto:
type: object
properties:
_id:
type: string
description: ObjectId del contacto
channel_type:
type: string
enum:
- web
- whatsapp
- whatsapp_qr
- facebook
- messenger
- instagram
- tiktok
- telegram
- email
- phone
description: Canal por el que existe el contacto
user_id:
type: string
description: Identificador del contacto dentro de su canal
channel_id:
type: string
description: ObjectId del canal concreto
external_id:
type: string
description: Identificador en un sistema externo
username:
type: string
first_name:
type: string
last_name:
type: string
phone:
type: string
email:
type: string
profile_pic:
type: string
custom_fields:
type: object
description: Campos personalizados de la company
tags:
description: Ids de tags
type: array
items:
type: string
is_attended:
type: boolean
description: true cuando un agente humano tomó la conversación
last_attended_at:
type: string
format: date-time
first_seen_at:
type: string
format: date-time
last_seen_at:
type: string
format: date-time
last_user_message_at:
type: string
format: date-time
last_bot_response_at:
type: string
format: date-time
last_agent_response_at:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- _id
- channel_type
- user_id
- custom_fields
- tags
- is_attended
- first_seen_at
- created_at
- updated_at
securitySchemes:
PAT:
scheme: bearer
bearerFormat: kbai_pk_
type: http
description: >-
Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal
con permiso `developer.manage_tokens`.
````