Skip to main content
POST
/
contacts
/
v1
/
bulk
curl -X POST https://api.whaapy.com/contacts/v1/bulk \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "contacts": [
      { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
      { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
      { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
    ]
  }'

{
  "operation": "add_tags",
  "success_count": 3,
  "error_count": 0,
  "results": [
    { "contact_id": "uuid-1", "success": true },
    { "contact_id": "uuid-2", "success": true },
    { "contact_id": "uuid-3", "success": true }
  ]
}
Realiza operaciones masivas sobre contactos: crear, actualizar, eliminar, gestionar tags y mover en el funnel.
Límites:
  • Máximo 100 contactos por request
  • Rate limit: 10 requests/minuto para operaciones bulk

​
Operaciones Disponibles

OperaciónDescripción
createCrear múltiples contactos
updateActualizar múltiples contactos
deleteEliminar múltiples contactos (soft delete)
add_tagsAgregar tags a múltiples contactos
remove_tagsRemover tags de múltiples contactos
set_funnel_stageMover contactos a una etapa del funnel

​
Body Parameters

​
operation
string
required
Tipo de operación: create, update, delete, add_tags, remove_tags, set_funnel_stage
​
contacts
array
Para create y update: Array de objetos de contacto
​
contact_ids
string[]
Para delete, add_tags, remove_tags, set_funnel_stage: Array de UUIDs
​
tags
string[]
Para add_tags y remove_tags: Tags a agregar/remover
​
funnel_stage_id
string
Para set_funnel_stage: UUID de la etapa destino

​
Ejemplos por Operación

​
Crear Múltiples Contactos

curl -X POST https://api.whaapy.com/contacts/v1/bulk \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "contacts": [
      { "phone_number": "+5215512345678", "name": "Juan", "tags": ["lead"] },
      { "phone_number": "+5215587654321", "name": "María", "tags": ["lead"] },
      { "phone_number": "+5215511223344", "name": "Pedro", "tags": ["lead"] }
    ]
  }'

​
Agregar Tags Masivamente

{
  "operation": "add_tags",
  "contact_ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ],
  "tags": ["campaña-enero", "newsletter"]
}

​
Remover Tags

{
  "operation": "remove_tags",
  "contact_ids": ["uuid-1", "uuid-2"],
  "tags": ["lead", "sin-atender"]
}

​
Mover a Etapa del Funnel

{
  "operation": "set_funnel_stage",
  "contact_ids": ["uuid-1", "uuid-2"],
  "funnel_stage_id": "stage-qualified-uuid"
}

​
Actualizar Múltiples Contactos

{
  "operation": "update",
  "contacts": [
    { 
      "id": "uuid-1", 
      "add_tags": ["verificado"],
      "custom_fields": { "verified_at": "2026-01-28" }
    },
    { 
      "id": "uuid-2", 
      "add_tags": ["verificado"],
      "custom_fields": { "verified_at": "2026-01-28" }
    }
  ]
}

​
Eliminar Múltiples Contactos

{
  "operation": "delete",
  "contact_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

​
Respuestas

​
Operación Exitosa

{
  "operation": "add_tags",
  "success_count": 3,
  "error_count": 0,
  "results": [
    { "contact_id": "uuid-1", "success": true },
    { "contact_id": "uuid-2", "success": true },
    { "contact_id": "uuid-3", "success": true }
  ]
}

​
Con Errores Parciales

{
  "operation": "create",
  "success_count": 2,
  "error_count": 1,
  "results": [
    { 
      "phone_number": "+5215512345678", 
      "success": true, 
      "contact_id": "new-uuid-1" 
    },
    { 
      "phone_number": "+5215587654321", 
      "success": true, 
      "contact_id": "new-uuid-2" 
    },
    { 
      "phone_number": "+5215511223344", 
      "success": false, 
      "error": "duplicate_contact",
      "existing_contact_id": "existing-uuid"
    }
  ]
}
El código 207 Multi-Status indica que algunas operaciones tuvieron éxito y otras fallaron. Revisa el array results para ver el detalle de cada una.

​
Errores Posibles en Results

ErrorDescripción
not_foundContacto no encontrado
duplicate_contactYa existe un contacto con ese teléfono
invalid_phone_numberNúmero de teléfono inválido
create_failedError al crear contacto
update_failedError al actualizar contacto
delete_failedError al eliminar contacto
add_tags_failedError al agregar tags
remove_tags_failedError al remover tags
set_funnel_failedError al asignar etapa del funnel

​
Casos de Uso

Después de parsear un archivo CSV, crea los contactos en lote:
const contacts = csvRows.map(row => ({
  phone_number: row.telefono,
  name: row.nombre,
  email: row.email,
  tags: ['importado-csv']
}));

// Dividir en chunks de 100
for (let i = 0; i < contacts.length; i += 100) {
  await api.post('/contacts/v1/bulk', {
    operation: 'create',
    contacts: contacts.slice(i, i + 100)
  });
}
Después de enviar una campaña, etiqueta los contactos:
{
  "operation": "add_tags",
  "contact_ids": ["...ids de la campaña..."],
  "tags": ["campaña-enero-2026", "email-enviado"]
}
Elimina contactos que no han interactuado en 1 año:
{
  "operation": "delete",
  "contact_ids": ["...ids de búsqueda avanzada..."]
}

​
Próximos Pasos

Búsqueda Avanzada

Encontrar contactos para operaciones masivas

Listar Contactos

Ver contactos actualizados

Fusionar Contactos

Combinar duplicados

Listar Tags

Ver tags disponibles