API de Contactos

Endpoints para crear, leer, actualizar y eliminar contactos.

Objeto Contacto

{
  "id": "con_abc123",
  "email": "juan.perez@example.com",
  "firstName": "Juan",
  "lastName": "Pérez",
  "company": "Acme Corp",
  "jobTitle": "Director Comercial",
  "phone": "+34612345678",
  "website": "https://acme.com",
  "status": "active",
  "groups": [
    {
      "id": "grp_xyz789",
      "name": "Leads de LinkedIn"
    }
  ],
  "tags": ["prospecto", "fintech"],
  "customFields": {
    "sector": "Fintech",
    "tamano_empresa": "50-100"
  },
  "pipelineStage": {
    "id": "stg_qualified",
    "name": "Calificado"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:45:00Z"
}

Listar contactos

Recupera la lista paginada de contactos.

GET /contacts

Parámetros de consulta

Ejemplo

curl -X GET "https://api.fluenzr.co/v1/contacts?groupId=grp_xyz789&status=active&perPage=50" \
  -H "Authorization: Bearer flz_sk_xxx"

Respuesta

{
  "success": true,
  "data": [
    {
      "id": "con_abc123",
      "email": "juan.perez@example.com",
      "firstName": "Juan",
      ...
    },
    ...
  ],
  "meta": {
    "page": 1,
    "perPage": 50,
    "total": 234,
    "totalPages": 5
  }
}

Obtener un contacto

Recupera los detalles de un contacto específico.

GET /contacts/:id

Ejemplo

curl -X GET "https://api.fluenzr.co/v1/contacts/con_abc123" \
  -H "Authorization: Bearer flz_sk_xxx"

Respuesta

{
  "success": true,
  "data": {
    "id": "con_abc123",
    "email": "juan.perez@example.com",
    ...
  }
}

Crear un contacto

Crea un nuevo contacto.

POST /contacts

Cuerpo de la solicitud

Ejemplo

curl -X POST "https://api.fluenzr.co/v1/contacts" \
  -H "Authorization: Bearer flz_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.garcia@startup.io",
    "firstName": "María",
    "lastName": "García",
    "company": "StartupIO",
    "jobTitle": "CEO",
    "groupIds": ["grp_xyz789"],
    "tags": ["prospecto", "saas"],
    "customFields": {
      "sector": "SaaS",
      "tamano_empresa": "10-50"
    }
  }'

Respuesta (201 Created)

{
  "success": true,
  "data": {
    "id": "con_def456",
    "email": "maria.garcia@startup.io",
    ...
  }
}

Posibles errores

Actualizar un contacto

Actualiza un contacto existente.

PUT /contacts/:id

Cuerpo de la solicitud

Los mismos campos que para la creación. Solo se actualizan los campos proporcionados.

Ejemplo

curl -X PUT "https://api.fluenzr.co/v1/contacts/con_abc123" \
  -H "Authorization: Bearer flz_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitle": "VP Ventas",
    "customFields": {
      "tamano_empresa": "100-500"
    }
  }'

Respuesta

{
  "success": true,
  "data": {
    "id": "con_abc123",
    "jobTitle": "VP Ventas",
    ...
  }
}

Eliminar un contacto

Elimina permanentemente un contacto.

DELETE /contacts/:id

Ejemplo

curl -X DELETE "https://api.fluenzr.co/v1/contacts/con_abc123" \
  -H "Authorization: Bearer flz_sk_xxx"

Respuesta (200 OK)

{
  "success": true,
  "data": {
    "id": "con_abc123",
    "deleted": true
  }
}

Creación masiva

Crea múltiples contactos en una sola solicitud.

POST /contacts/bulk

Cuerpo de la solicitud

{
  "contacts": [
    {
      "email": "contacto1@example.com",
      "firstName": "Contacto",
      "lastName": "Uno"
    },
    {
      "email": "contacto2@example.com",
      "firstName": "Contacto",
      "lastName": "Dos"
    }
  ],
  "groupIds": ["grp_xyz789"],
  "onDuplicate": "skip"
}

Ejemplo

curl -X POST "https://api.fluenzr.co/v1/contacts/bulk" \
  -H "Authorization: Bearer flz_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"email": "a@example.com", "firstName": "A"},
      {"email": "b@example.com", "firstName": "B"}
    ],
    "onDuplicate": "skip"
  }'

Respuesta

{
  "success": true,
  "data": {
    "created": 2,
    "updated": 0,
    "skipped": 0,
    "errors": []
  }
}

Buscar contactos

Búsqueda avanzada de contactos.

POST /contacts/search

Cuerpo de la solicitud

{
  "query": "example.com",
  "filters": {
    "status": "active",
    "groups": ["grp_xyz789"],
    "customFields": {
      "sector": "Fintech"
    }
  },
  "sort": {
    "field": "createdAt",
    "order": "desc"
  }
}

Ejemplo

curl -X POST "https://api.fluenzr.co/v1/contacts/search" \
  -H "Authorization: Bearer flz_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "customFields": {
        "sector": "Fintech"
      }
    }
  }'

Gestionar grupos de contacto

Añadir a grupos

POST /contacts/:id/groups

{
  "groupIds": ["grp_abc", "grp_def"]
}

Quitar de grupos

DELETE /contacts/:id/groups

{
  "groupIds": ["grp_abc"]
}

Gestionar etiquetas

Añadir etiquetas

POST /contacts/:id/tags

{
  "tags": ["vip", "prioridad"]
}

Quitar etiquetas

DELETE /contacts/:id/tags

{
  "tags": ["prioridad"]
}