Un contacto es una persona a la que puedes enviar mensajes. Los contactos pertenecen a una cuenta y se identifican por su número de teléfono, así que sincronizar el mismo número dos veces actualiza el registro existente en lugar de crear un duplicado.
Crea o combina un contacto
Envía un número de teléfono y los datos que conozcas. Los campos que omitas se conservan del registro existente, así que es seguro llamar a este endpoint repetidamente.
curl -X POST https://api.furcata.com/v0/account/acc_123/contacts/sync \
-H "Authorization: ******" \
-H "Content-Type: application/json" \
-d '{
"phone": "+15555550100",
"firstName": "Alex",
"lastName": "Rivera",
"email": "alex@example.com",
"language": "en",
"note": "Prefers a morning appointment"
}'{
"status": "created",
"id": "+15555550100",
"reason": null
}El estado de la respuesta es created cuando el contacto se creó o se combinó, y skipped cuando el número de teléfono no se pudo usar. Un número omitido no es un error: la llamada igual termina bien con 200, así que una importación masiva con algunas filas malas no falla por completo. reason explica la omisión cuando existe.
Campos aceptados:
- phone: obligatorio, hasta 32 caracteres, en formato E.164.
- email: hasta 254 caracteres.
- externalId: hasta 256 caracteres, para tu propio identificador.
- firstName, lastName: hasta 100 caracteres cada uno.
- note: hasta 1000 caracteres de texto libre.
- language: código de dos letras.
- unsubscribed: true para registrar que la persona se dio de baja.
Respeta las bajas
Si alguien pide que no lo contacten, pon unsubscribed en true y déjalo así. La sincronización no lo borra a menos que tú envíes el campo.
Lista los contactos
Devuelve los contactos recientes de la cuenta, con su idioma, nombre, correo electrónico, id externo, nota y estado de baja.
curl https://api.furcata.com/v0/account/acc_123/contact \
-H "Authorization: ******"[
{
"id": "+15555550100",
"email": "alex@example.com",
"external_id": "crm-4815",
"language": "en",
"first_name": "Alex",
"last_name": "Rivera",
"note": "Prefers a morning appointment",
"unsubscribed": false,
"timestamp": "2026-01-01T00:00:00.000Z"
}
]Recalcula los totales de contactos de un servicio
Cada servicio mantiene un conteo de sus contactos, desglosado por idioma, más el límite de contactos que le aplica. Llama a este endpoint después de una importación masiva para actualizar esos números. No crea, cambia ni elimina nada, y no envía ningún mensaje, así que no tiene costo.
Este endpoint requiere un administrador de la cuenta.
curl -X POST https://api.furcata.com/v0/account/acc_123/contact/count \
-H "Authorization: ******" \
-H "Content-Type: application/json" \
-d '{"service": "svc_123"}'{
"message": "Contact count updated",
"total": 1284,
"contacts": 1284,
"contactsLanguage": {
"en": 1100,
"es": 184
}
}service es obligatorio y puede contener letras, dígitos, guion o guion bajo.
Errores
- 400 cuando falta un campo obligatorio o tiene el tipo equivocado.
- 401 cuando el token falta o no se acepta.
- 403 cuando alguien que no es administrador de la cuenta solicita el conteo de contactos.
Siguientes pasos
Continúa con Mensajes para enviar a estos contactos, o con Informes para ver qué se entregó.