> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear Contacto

> Crea un nuevo contacto en tu base de datos

Agrega un nuevo contacto a tu CRM de Whaapy. El número de teléfono es el único campo requerido.

***

## Body Parameters

<ParamField body="phone_number" type="string" required>
  Número de teléfono en formato E.164. Ej: `+5215512345678`
</ParamField>

<ParamField body="name" type="string">
  Nombre completo del contacto
</ParamField>

<ParamField body="email" type="string">
  Email del contacto (debe ser válido)
</ParamField>

<ParamField body="avatar_url" type="string">
  URL de imagen de perfil
</ParamField>

<ParamField body="tags" type="string[]">
  Array de tags para categorizar. Ej: `["cliente", "premium"]`
</ParamField>

<ParamField body="custom_fields" type="object">
  Campos personalizados como objeto JSON. Ej: `{ "company": "Acme" }`
</ParamField>

<ParamField body="external_ids" type="object">
  IDs externos para integración con CRMs. Ej: `{ "hubspot": "abc123" }`
</ParamField>

<ParamField body="notes" type="string">
  Notas internas sobre el contacto
</ParamField>

<ParamField body="funnel_stage_id" type="string">
  UUID de la etapa del funnel donde colocar el contacto
</ParamField>

<ParamField body="source" type="string" default="api">
  Origen del contacto: `api`, `import`, `webhook`, `manual`, etc.
</ParamField>

<ParamField body="company" type="string">
  Nombre de la empresa
</ParamField>

<ParamField body="address" type="string">
  Dirección
</ParamField>

<ParamField body="city" type="string">
  Ciudad
</ParamField>

<ParamField body="state" type="string">
  Estado/Provincia
</ParamField>

<ParamField body="postal_code" type="string">
  Código postal
</ParamField>

<ParamField body="country" type="string" default="MX">
  Código de país ISO 3166-1 alpha-2 (2 letras)
</ParamField>

<ParamField body="assigned_agent_id" type="string">
  UUID del agente humano a asignar al contacto. Obtén IDs de agentes con [GET /team/v1](/api-reference/team/list). Las conversaciones futuras del contacto se asignarán automáticamente a este agente.
</ParamField>

***

## Ejemplos

### Contacto Básico

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/contacts/v1 \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number": "+5215512345678",
      "name": "Juan Pérez"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/contacts/v1', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: '+5215512345678',
      name: 'Juan Pérez'
    })
  });
  const data = await response.json();
  console.log(data.contact);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.whaapy.com/contacts/v1',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'phone_number': '+5215512345678',
          'name': 'Juan Pérez'
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.whaapy.com/contacts/v1');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'phone_number' => '+5215512345678',
      'name' => 'Juan Pérez'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  echo $response;
  ```
</RequestExample>

### Contacto Completo

<RequestExample>
  ```json Request theme={null}
  {
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "tags": ["cliente", "premium"],
    "custom_fields": { 
      "company": "Acme Inc",
      "role": "CEO",
      "contract_value": 50000
    },
    "external_ids": { 
      "hubspot": "abc123" 
    },
    "notes": "Contacto referido por María García",
    "source": "api",
    "company": "Acme Inc",
    "city": "Ciudad de México",
    "country": "MX"
  }
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "contact": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5215512345678",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "avatar_url": null,
      "tags": ["cliente", "premium"],
      "custom_fields": { "company": "Acme Inc" },
      "external_ids": { "hubspot": "abc123" },
      "notes": "Contacto referido por María García",
      "funnel_stage": null,
      "source": "api",
      "company": "Acme Inc",
      "address": null,
      "city": "Ciudad de México",
      "state": null,
      "postal_code": null,
      "country": "MX",
      "assigned_agent_id": null,
      "last_contact_at": null,
      "created_at": "2026-01-28T12:00:00Z",
      "updated_at": "2026-01-28T12:00:00Z"
    }
  }
  ```
</ResponseExample>

***

## Errores

### Contacto Duplicado

<ResponseExample>
  ```json 409 Conflict theme={null}
  {
    "error": "duplicate_contact",
    "message": "Ya existe un contacto con este número de teléfono",
    "existing_contact_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

<Tip>
  Si recibes este error, puedes usar [PATCH /contacts/v1/:id](/api-reference/contacts/update) para actualizar el contacto existente.
</Tip>

### Datos Inválidos

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "validation_error",
    "message": "Datos inválidos",
    "details": {
      "phone_number": ["Formato inválido. Usar E.164: +5215512345678"],
      "email": ["Email inválido"]
    }
  }
  ```
</ResponseExample>

***

## Webhooks

Cuando creas un contacto, se dispara el webhook `contact.created`:

```json theme={null}
{
  "event": "contact.created",
  "data": {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "tags": ["cliente", "premium"],
    "source": "api",
    "created_at": "2026-01-28T12:00:00Z"
  }
}
```

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Operaciones Masivas" icon="layer-group" href="/api-reference/contacts/bulk">
    Crear múltiples contactos a la vez
  </Card>

  <Card title="Actualizar Contacto" icon="pen" href="/api-reference/contacts/update">
    Modificar contacto existente
  </Card>

  <Card title="Enviar Mensaje" icon="paper-plane" href="/api-reference/messages/send">
    Enviar mensaje al nuevo contacto
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/events">
    Ver todos los eventos disponibles
  </Card>
</CardGroup>