API Reference

La API REST de Zeph CRM permite integrar tus datos de leads, contactos, empresas, oportunidades y actividades con sistemas externos. Todas las peticiones usan JSON y requieren autenticación mediante API Key. La API no expone endpoints DELETE -- las eliminaciones se realizan desde la UI.

Base URL: https://zephcrm.com/api/v1

Autenticación

Todas las peticiones deben incluir un header Authorization con tu API key en formato Bearer token. Podes crear y administrar tus claves desde Settings > API Keys.

Header de autenticación

Authorization: Bearer vk_live_tu_api_key_aqui

Importante

Las API keys se muestran una sola vez al crearlas. Guardalas en un lugar seguro.
Cada key tiene scopes especificos (ej: leads:read, contacts:write). Solo podrás acceder a los endpoints para los que tengas permiso.
Nunca compartas tus claves ni las incluyas en código del lado del cliente.

Rate Limiting

Cada API key tiene un límite de 100 peticiones por minuto. Si excedes el límite, recibirás una respuesta 429 Too Many Requests.

Los headers de respuesta incluyen información sobre tu uso:

Headers de rate limit

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706745600

Response 429

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Has excedido el limite de 100 peticiones por minuto. Intenta de nuevo en 42 segundos.",
    "retryAfter": 42
  }
}

Formato de respuesta

Todas las respuestas son JSON. Los formatos varian según el tipo de operación:

Respuesta exitosa (objeto)

200 OK

{
  "data": {
    "id": "clx1234...",
    "firstName": "Juan",
    "lastName": "Perez",
    "email": "juan@empresa.com",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Respuesta de error

400 / 401 / 403 / 404 / 422 / 500

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Los datos enviados no son validos.",
    "details": {
      "email": ["El email no es valido"],
      "firstName": ["Este campo es obligatorio"]
    }
  }
}

Respuesta paginada (lista)

200 OK

{
  "data": [
    { "id": "clx1...", "firstName": "Juan", ... },
    { "id": "clx2...", "firstName": "Maria", ... }
  ],
  "pagination": {
    "nextCursor": "clx2...",
    "hasMore": true,
    "total": 150
  }
}

Paginación

La API usa paginación basada en cursor para listas. Usa el campo nextCursor de la respuesta como parámetro cursor en la siguiente peticion.

Ejemplo de paginación

# Primera pagina
curl "https://zephcrm.com/api/v1/leads?limit=20" \
  -H "Authorization: Bearer vk_live_..."

# Segunda pagina (usar nextCursor de la respuesta anterior)
curl "https://zephcrm.com/api/v1/leads?limit=20&cursor=clx2abc..." \
  -H "Authorization: Bearer vk_live_..."

Leads

GET/api/v1/leadsleads:read

Lista todos los leads de tu organización con paginación y filtros.

Query Parameters

Param	Tipo	Descripción
`cursor`	string	Cursor para paginación (ID del último item)
`limit`	number	Items por pagina (default 20, max 100)
`sort`	string	Campo por el que ordenar
`order`	asc \| desc	Dirección del orden (default desc)
`search`	string	Buscar en nombre, email, etc.
`created_after`	ISO 8601	Filtrar por fecha de creación
`created_before`	ISO 8601	Filtrar por fecha de creación
`status`	string	Filtrar por status: NEW, CONTACTED, QUALIFIED, CONVERTED, LOST

curl

curl "https://zephcrm.com/api/v1/leads?limit=20&status=NEW" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clx1abc...",
      "firstName": "Juan",
      "lastName": "Perez",
      "email": "juan@empresa.com",
      "phone": "+54 11 1234-5678",
      "company": "Acme SRL",
      "position": "Gerente Comercial",
      "status": "NEW",
      "notes": "Interesado en plan Enterprise",
      "customFields": {},
      "assignedToId": "clxuser1...",
      "source": "Zapier",
      "leadSourceId": "clxsrc1...",
      "leadSource": { "id": "clxsrc1...", "name": "Zapier" },
      "sourceDetail": "Typeform signup",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "clx1abc...",
    "hasMore": true,
    "total": 85
  }
}

GET/api/v1/leads/:idleads:read

Obtiene un lead por su ID.

curl

curl "https://zephcrm.com/api/v1/leads/clx1abc..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "clx1abc...",
    "firstName": "Juan",
    "lastName": "Perez",
    "email": "juan@empresa.com",
    "phone": "+54 11 1234-5678",
    "company": "Acme SRL",
    "position": "Gerente Comercial",
    "status": "NEW",
    "notes": "Interesado en plan Enterprise",
    "customFields": {},
    "assignedToId": "clxuser1...",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

POST/api/v1/leadsleads:write

Crea un nuevo lead.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`firstName`	string	Si	Nombre
`lastName`	string	Si	Apellido
`email`	string	No	Email
`phone`	string	No	Teléfono
`company`	string	No	Nombre de empresa
`position`	string	No	Cargo
`status`	string	No	NEW (default), CONTACTED, QUALIFIED
`notes`	string	No	Notas
`customFields`	object	No	Campos personalizados
`assignedToId`	string	No	ID del usuario asignado
`source`	string	No	Nombre de la fuente del lead. Si no existe, se crea automáticamente.
`sourceDetail`	string	No	Detalle adicional sobre el origen (ej: nombre de campaña, webhook).

curl

curl -X POST "https://zephcrm.com/api/v1/leads" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Garcia",
    "email": "maria@empresa.com",
    "company": "Tech SA",
    "status": "NEW",
    "source": "Zapier",
    "sourceDetail": "Typeform signup"
  }'

Response

{
  "data": {
    "id": "clxnew1...",
    "firstName": "Maria",
    "lastName": "Garcia",
    "email": "maria@empresa.com",
    "company": "Tech SA",
    "status": "NEW",
    "source": "Zapier",
    "leadSourceId": "clxsrc1...",
    "leadSource": { "id": "clxsrc1...", "name": "Zapier" },
    "sourceDetail": "Typeform signup",
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

PATCH/api/v1/leads/:idleads:write

Actualiza un lead existente. Solo enviar los campos a modificar.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`firstName`	string	No	Nombre
`lastName`	string	No	Apellido
`email`	string	No	Email
`phone`	string	No	Teléfono
`company`	string	No	Nombre de empresa
`position`	string	No	Cargo
`status`	string	No	NEW, CONTACTED, QUALIFIED, CONVERTED, LOST
`notes`	string	No	Notas
`customFields`	object	No	Campos personalizados
`assignedToId`	string	No	ID del usuario asignado
`source`	string	No	Nombre de la fuente del lead. Si no existe, se crea automáticamente.
`sourceDetail`	string	No	Detalle adicional sobre el origen (ej: nombre de campaña, webhook).

curl

curl -X PATCH "https://zephcrm.com/api/v1/leads/clx1abc..." \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONTACTED",
    "notes": "Llamada realizada el 20/01"
  }'

Response

{
  "data": {
    "id": "clx1abc...",
    "firstName": "Juan",
    "lastName": "Perez",
    "status": "CONTACTED",
    "notes": "Llamada realizada el 20/01",
    "updatedAt": "2025-01-20T15:00:00.000Z"
  }
}

DELETE no disponible

La API no expone endpoints DELETE. Las eliminaciones se realizan exclusivamente desde la UI del CRM. Un DELETE a /api/v1/leads/:id retorna 405 Method Not Allowed.

Contactos

GET/api/v1/contactscontacts:read

Lista todos los contactos de tu organización.

Query Parameters

Param	Tipo	Descripción
`cursor`	string	Cursor para paginación (ID del último item)
`limit`	number	Items por pagina (default 20, max 100)
`sort`	string	Campo por el que ordenar
`order`	asc \| desc	Dirección del orden (default desc)
`search`	string	Buscar en nombre, email, etc.
`created_after`	ISO 8601	Filtrar por fecha de creación
`created_before`	ISO 8601	Filtrar por fecha de creación

curl

curl "https://zephcrm.com/api/v1/contacts?limit=20&search=garcia" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clxc1...",
      "firstName": "Maria",
      "lastName": "Garcia",
      "email": "maria@techsa.com",
      "phone": "+54 11 9876-5432",
      "mobile": "+54 9 11 9876-5432",
      "position": "CTO",
      "companyId": "clxcomp1...",
      "notes": null,
      "customFields": {},
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "clxc1...",
    "hasMore": false,
    "total": 12
  }
}

GET/api/v1/contacts/:idcontacts:read

Obtiene un contacto por su ID.

curl

curl "https://zephcrm.com/api/v1/contacts/clxc1..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "clxc1...",
    "firstName": "Maria",
    "lastName": "Garcia",
    "email": "maria@techsa.com",
    "phone": "+54 11 9876-5432",
    "mobile": "+54 9 11 9876-5432",
    "position": "CTO",
    "companyId": "clxcomp1...",
    "notes": null,
    "customFields": {},
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-01-18T12:00:00.000Z"
  }
}

POST/api/v1/contactscontacts:write

Crea un nuevo contacto. El email debe ser unico dentro de la organización.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`firstName`	string	Si	Nombre
`lastName`	string	Si	Apellido
`email`	string	No	Email (unico por org)
`phone`	string	No	Teléfono fijo
`mobile`	string	No	Celular
`position`	string	No	Cargo
`companyId`	string	No	ID de la empresa
`notes`	string	No	Notas
`customFields`	object	No	Campos personalizados

curl

curl -X POST "https://zephcrm.com/api/v1/contacts" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Carlos",
    "lastName": "Lopez",
    "email": "carlos@empresa.com",
    "companyId": "clxcomp1..."
  }'

Response

{
  "data": {
    "id": "clxcnew1...",
    "firstName": "Carlos",
    "lastName": "Lopez",
    "email": "carlos@empresa.com",
    "companyId": "clxcomp1...",
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

PATCH/api/v1/contacts/:idcontacts:write

Actualiza un contacto existente.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`firstName`	string	No	Nombre
`lastName`	string	No	Apellido
`email`	string	No	Email (unico por org)
`phone`	string	No	Teléfono fijo
`mobile`	string	No	Celular
`position`	string	No	Cargo
`companyId`	string	No	ID de la empresa
`notes`	string	No	Notas
`customFields`	object	No	Campos personalizados

curl

curl -X PATCH "https://zephcrm.com/api/v1/contacts/clxc1..." \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "position": "VP Engineering",
    "mobile": "+54 9 11 5555-0000"
  }'

Response

{
  "data": {
    "id": "clxc1...",
    "firstName": "Maria",
    "lastName": "Garcia",
    "position": "VP Engineering",
    "mobile": "+54 9 11 5555-0000",
    "updatedAt": "2025-01-20T16:00:00.000Z"
  }
}

DELETE no disponible

La API no expone endpoints DELETE. Las eliminaciones se realizan exclusivamente desde la UI del CRM.

Empresas

GET/api/v1/companiescompanies:read

Lista todas las empresas de tu organización.

Query Parameters

Param	Tipo	Descripción
`cursor`	string	Cursor para paginación (ID del último item)
`limit`	number	Items por pagina (default 20, max 100)
`sort`	string	Campo por el que ordenar
`order`	asc \| desc	Dirección del orden (default desc)
`search`	string	Buscar en nombre, email, etc.
`created_after`	ISO 8601	Filtrar por fecha de creación
`created_before`	ISO 8601	Filtrar por fecha de creación

curl

curl "https://zephcrm.com/api/v1/companies?limit=20&search=tech" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clxcomp1...",
      "name": "Tech SA",
      "website": "https://techsa.com",
      "phone": "+54 11 4000-0000",
      "address": "Av. Corrientes 1234",
      "city": "Buenos Aires",
      "employeeCount": 50,
      "customFields": {},
      "createdAt": "2025-01-05T09:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "clxcomp1...",
    "hasMore": false,
    "total": 8
  }
}

GET/api/v1/companies/:idcompanies:read

Obtiene una empresa por su ID.

curl

curl "https://zephcrm.com/api/v1/companies/clxcomp1..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "clxcomp1...",
    "name": "Tech SA",
    "website": "https://techsa.com",
    "phone": "+54 11 4000-0000",
    "address": "Av. Corrientes 1234",
    "city": "Buenos Aires",
    "employeeCount": 50,
    "customFields": {},
    "createdAt": "2025-01-05T09:00:00.000Z",
    "updatedAt": "2025-01-15T11:00:00.000Z"
  }
}

POST/api/v1/companiescompanies:write

Crea una nueva empresa. El nombre se deduplica (case-insensitive) dentro de la organización.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`name`	string	Si	Nombre de la empresa
`website`	string	No	Sitio web
`phone`	string	No	Teléfono
`address`	string	No	Dirección
`city`	string	No	Ciudad
`employeeCount`	number	No	Cantidad de empleados
`customFields`	object	No	Campos personalizados

curl

curl -X POST "https://zephcrm.com/api/v1/companies" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Innovatech SRL",
    "website": "https://innovatech.com.ar",
    "city": "Cordoba",
    "employeeCount": 25
  }'

Response

{
  "data": {
    "id": "clxcompnew...",
    "name": "Innovatech SRL",
    "website": "https://innovatech.com.ar",
    "city": "Cordoba",
    "employeeCount": 25,
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

PATCH/api/v1/companies/:idcompanies:write

Actualiza una empresa existente.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`name`	string	No	Nombre de la empresa
`website`	string	No	Sitio web
`phone`	string	No	Teléfono
`address`	string	No	Dirección
`city`	string	No	Ciudad
`employeeCount`	number	No	Cantidad de empleados
`customFields`	object	No	Campos personalizados

curl

curl -X PATCH "https://zephcrm.com/api/v1/companies/clxcomp1..." \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "employeeCount": 75,
    "address": "Av. del Libertador 5000"
  }'

Response

{
  "data": {
    "id": "clxcomp1...",
    "name": "Tech SA",
    "employeeCount": 75,
    "address": "Av. del Libertador 5000",
    "updatedAt": "2025-01-20T16:00:00.000Z"
  }
}

DELETE no disponible

La API no expone endpoints DELETE. Las eliminaciones se realizan exclusivamente desde la UI del CRM.

Oportunidades

GET/api/v1/opportunitiesopportunities:read

Lista todas las oportunidades de tu organización.

Query Parameters

Param	Tipo	Descripción
`cursor`	string	Cursor para paginación (ID del último item)
`limit`	number	Items por pagina (default 20, max 100)
`sort`	string	Campo por el que ordenar
`order`	asc \| desc	Dirección del orden (default desc)
`search`	string	Buscar en nombre, email, etc.
`created_after`	ISO 8601	Filtrar por fecha de creación
`created_before`	ISO 8601	Filtrar por fecha de creación

curl

curl "https://zephcrm.com/api/v1/opportunities?limit=20&sort=value&order=desc" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clxopp1...",
      "title": "Implementacion CRM Enterprise",
      "value": 50000,
      "currency": "USD",
      "expectedCloseDate": "2025-03-15",
      "description": "Proyecto de implementacion completa",
      "stageId": "clxstage3...",
      "contactId": "clxc1...",
      "companyId": "clxcomp1...",
      "assignedToId": "clxuser1...",
      "customFields": {},
      "createdAt": "2025-01-12T10:00:00.000Z",
      "updatedAt": "2025-01-19T14:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "clxopp1...",
    "hasMore": true,
    "total": 34
  }
}

GET/api/v1/opportunities/:idopportunities:read

Obtiene una oportunidad por su ID.

curl

curl "https://zephcrm.com/api/v1/opportunities/clxopp1..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "clxopp1...",
    "title": "Implementacion CRM Enterprise",
    "value": 50000,
    "currency": "USD",
    "expectedCloseDate": "2025-03-15",
    "description": "Proyecto de implementacion completa",
    "stageId": "clxstage3...",
    "contactId": "clxc1...",
    "companyId": "clxcomp1...",
    "assignedToId": "clxuser1...",
    "customFields": {},
    "createdAt": "2025-01-12T10:00:00.000Z",
    "updatedAt": "2025-01-19T14:00:00.000Z"
  }
}

POST/api/v1/opportunitiesopportunities:write

Crea una nueva oportunidad.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`title`	string	Si	Título de la oportunidad
`value`	number	No	Valor monetario
`currency`	string	No	Moneda (default: USD)
`expectedCloseDate`	string	No	Fecha esperada de cierre (YYYY-MM-DD)
`description`	string	No	Descripción
`stageId`	string	Si	ID de la etapa del pipeline
`contactId`	string	No	ID del contacto
`companyId`	string	No	ID de la empresa
`assignedToId`	string	No	ID del usuario asignado
`customFields`	object	No	Campos personalizados

curl

curl -X POST "https://zephcrm.com/api/v1/opportunities" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Renovacion anual",
    "value": 12000,
    "currency": "USD",
    "expectedCloseDate": "2025-04-01",
    "stageId": "clxstage1...",
    "contactId": "clxc1...",
    "companyId": "clxcomp1..."
  }'

Response

{
  "data": {
    "id": "clxoppnew...",
    "title": "Renovacion anual",
    "value": 12000,
    "currency": "USD",
    "expectedCloseDate": "2025-04-01",
    "stageId": "clxstage1...",
    "contactId": "clxc1...",
    "companyId": "clxcomp1...",
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

PATCH/api/v1/opportunities/:idopportunities:write

Actualiza una oportunidad existente. Cambiar stageId mueve la oportunidad en el pipeline.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`title`	string	No	Título
`value`	number	No	Valor monetario
`currency`	string	No	Moneda
`expectedCloseDate`	string	No	Fecha esperada de cierre
`description`	string	No	Descripción
`stageId`	string	No	ID de la etapa del pipeline
`contactId`	string	No	ID del contacto
`companyId`	string	No	ID de la empresa
`assignedToId`	string	No	ID del usuario asignado
`customFields`	object	No	Campos personalizados

curl

curl -X PATCH "https://zephcrm.com/api/v1/opportunities/clxopp1..." \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": 55000,
    "stageId": "clxstage4..."
  }'

Response

{
  "data": {
    "id": "clxopp1...",
    "title": "Implementacion CRM Enterprise",
    "value": 55000,
    "stageId": "clxstage4...",
    "updatedAt": "2025-01-20T16:00:00.000Z"
  }
}

DELETE no disponible

La API no expone endpoints DELETE. Las eliminaciones se realizan exclusivamente desde la UI del CRM.

Actividades

GET/api/v1/activitiesactivities:read

Lista todas las actividades de tu organización con paginación y filtros.

Query Parameters

Param	Tipo	Descripción
`cursor`	string	Cursor para paginación (ID del último item)
`limit`	number	Items por pagina (default 20, max 100)
`sort`	string	Campo por el que ordenar
`order`	asc \| desc	Dirección del orden (default desc)
`search`	string	Buscar en nombre, email, etc.
`created_after`	ISO 8601	Filtrar por fecha de creación
`created_before`	ISO 8601	Filtrar por fecha de creación
`type`	string	Filtrar por tipo: TASK, CALL, MEETING, EMAIL, NOTE
`status`	string	PENDING o COMPLETED
`assigned_to`	string	ID del usuario asignado
`contact_id`	string	ID del contacto asociado
`company_id`	string	ID de la empresa asociada
`opportunity_id`	string	ID de la oportunidad asociada
`due_after`	ISO 8601	Actividades con vencimiento después de esta fecha
`due_before`	ISO 8601	Actividades con vencimiento antes de esta fecha

curl

curl "https://zephcrm.com/api/v1/activities?type=TASK&status=PENDING&limit=20" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clxact1...",
      "type": "TASK",
      "title": "Llamar a Juan Perez",
      "description": "Seguimiento de propuesta",
      "dueDate": "2025-02-01T10:00:00.000Z",
      "completedAt": null,
      "priority": "HIGH",
      "contactId": "clxc1...",
      "opportunityId": "clxopp1...",
      "assignedToId": "clxuser1...",
      "createdAt": "2025-01-20T14:00:00.000Z",
      "updatedAt": "2025-01-20T14:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "clxact1...",
    "hasMore": true,
    "total": 42
  }
}

GET/api/v1/activities/:idactivities:read

Obtiene una actividad por su ID con relaciones (contacto, oportunidad, usuario asignado).

curl

curl "https://zephcrm.com/api/v1/activities/clxact1..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "clxact1...",
    "type": "TASK",
    "title": "Llamar a Juan Perez",
    "description": "Seguimiento de propuesta",
    "dueDate": "2025-02-01T10:00:00.000Z",
    "completedAt": null,
    "priority": "HIGH",
    "contact": { "id": "clxc1...", "firstName": "Juan", "lastName": "Perez", "email": "juan@empresa.com" },
    "opportunity": { "id": "clxopp1...", "title": "Implementacion CRM" },
    "assignedTo": { "id": "clxuser1...", "name": "Admin" },
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

POST/api/v1/activitiesactivities:write

Crea una nueva actividad. Las tareas (TASK) requieren dueDate.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`type`	string	Si	TASK, CALL, MEETING, EMAIL, NOTE
`title`	string	Si	Título de la actividad
`description`	string	No	Descripción
`dueDate`	ISO 8601	No	Fecha de vencimiento (requerido para TASK)
`priority`	string	No	LOW, MEDIUM (default), HIGH
`contactId`	string	No	ID del contacto asociado
`opportunityId`	string	No	ID de la oportunidad asociada
`assignedToId`	string	No	ID del usuario asignado (default: usuario de la key)

curl

curl -X POST "https://zephcrm.com/api/v1/activities" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TASK",
    "title": "Enviar propuesta a cliente",
    "dueDate": "2025-02-05T10:00:00.000Z",
    "priority": "HIGH",
    "contactId": "clxc1...",
    "opportunityId": "clxopp1..."
  }'

Response

{
  "data": {
    "id": "clxactnew...",
    "type": "TASK",
    "title": "Enviar propuesta a cliente",
    "dueDate": "2025-02-05T10:00:00.000Z",
    "priority": "HIGH",
    "completedAt": null,
    "createdAt": "2025-01-20T14:00:00.000Z",
    "updatedAt": "2025-01-20T14:00:00.000Z"
  }
}

PATCH/api/v1/activities/:idactivities:write

Actualiza una actividad. Para marcar como completada, enviar completedAt con la fecha actual.

Request Body (JSON)

Campo	Tipo	Req	Descripción
`title`	string	No	Título
`description`	string	No	Descripción
`dueDate`	ISO 8601	No	Fecha de vencimiento
`priority`	string	No	LOW, MEDIUM, HIGH
`type`	string	No	TASK, CALL, MEETING, EMAIL, NOTE
`contactId`	string	No	ID del contacto asociado
`opportunityId`	string	No	ID de la oportunidad asociada
`assignedToId`	string	No	ID del usuario asignado
`completedAt`	ISO 8601 \| null	No	Fecha de completado (null para reabrir)

curl

curl -X PATCH "https://zephcrm.com/api/v1/activities/clxact1..." \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "completedAt": "2025-01-20T16:00:00.000Z"
  }'

Response

{
  "data": {
    "id": "clxact1...",
    "type": "TASK",
    "title": "Llamar a Juan Perez",
    "completedAt": "2025-01-20T16:00:00.000Z",
    "updatedAt": "2025-01-20T16:00:00.000Z"
  }
}

DELETE no disponible

La API no expone endpoints DELETE para actividades.

Pipeline Stages

GET/api/v1/pipeline-stagespipeline:read

Lista las etapas del pipeline de ventas ordenadas por posición. Usa esto para obtener los stageId al crear o mover oportunidades.

curl

curl "https://zephcrm.com/api/v1/pipeline-stages" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "clxstage1...",
      "name": "Prospeccion",
      "order": 0,
      "color": "#3b82f6",
      "probability": 10,
      "isDefault": true,
      "isWon": false,
      "isLost": false
    },
    {
      "id": "clxstage2...",
      "name": "Propuesta",
      "order": 1,
      "color": "#f59e0b",
      "probability": 50,
      "isDefault": false,
      "isWon": false,
      "isLost": false
    },
    {
      "id": "clxstage3...",
      "name": "Ganada",
      "order": 2,
      "color": "#22c55e",
      "probability": 100,
      "isDefault": false,
      "isWon": true,
      "isLost": false
    }
  ]
}

Secuencias de seguimiento

GET/api/v1/sequencessequences:read

Lista las secuencias de seguimiento de la organización.

curl

curl "https://zephcrm.com/api/v1/sequences" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "6f1b2c3d-...",
      "name": "Seguimiento leads nuevos",
      "description": "Para leads del formulario web",
      "isActive": true,
      "reviewMode": false,
      "language": "es",
      "stepCount": 3,
      "activeEnrollments": 12,
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  ]
}

GET/api/v1/sequences/{id}sequences:read

Detalle de una secuencia con sus pasos (briefing y delays).

curl

curl "https://zephcrm.com/api/v1/sequences/6f1b2c3d-..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "id": "6f1b2c3d-...",
    "name": "Seguimiento leads nuevos",
    "isActive": true,
    "reviewMode": false,
    "tone": "profesional cercano",
    "language": "es",
    "sendWindow": { "days": [1, 2, 3, 4, 5], "startHour": 9, "endHour": 18 },
    "steps": [
      { "order": 1, "briefing": "Presentarme y proponer una llamada", "delayValue": 1, "delayUnit": "hours" },
      { "order": 2, "briefing": "Reforzar valor con un caso de éxito", "delayValue": 3, "delayUnit": "days" }
    ]
  }
}

POST/api/v1/sequences/{id}/enrollmentssequences:write

Enrola leads en la secuencia. Los emails se generan con AI y se envían desde la casilla del dueño de la API key. Los leads con un seguimiento ya activo se omiten (skipped).

curl

curl -X POST "https://zephcrm.com/api/v1/sequences/6f1b2c3d-.../enrollments" \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "leadIds": ["a1b2c3d4-..."] }'

Response

{
  "data": {
    "enrolled": 1,
    "skipped": [
      { "leadId": "e5f6a7b8-...", "reason": "Ya tiene una secuencia activa" }
    ]
  }
}

GET/api/v1/enrollments?leadId={leadId}sequences:read

Estado de los seguimientos de un lead (o de una secuencia con ?sequenceId=). Estados: ACTIVE, WAITING_APPROVAL, REPLIED, COMPLETED, CANCELLED.

curl

curl "https://zephcrm.com/api/v1/enrollments?leadId=a1b2c3d4-..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": [
    {
      "id": "9c8d7e6f-...",
      "status": "ACTIVE",
      "currentStep": 1,
      "totalSteps": 3,
      "nextSendAt": "2026-07-25T13:00:00.000Z",
      "repliedAt": null,
      "sequence": { "id": "6f1b2c3d-...", "name": "Seguimiento leads nuevos", "reviewMode": false },
      "lead": { "id": "a1b2c3d4-...", "firstName": "Ana", "lastName": "García", "email": "ana@empresa.com" }
    }
  ]
}

DELETE/api/v1/enrollments/{id}sequences:write

Cancela un seguimiento en curso. No se envían más emails al lead.

curl

curl -X DELETE "https://zephcrm.com/api/v1/enrollments/9c8d7e6f-..." \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": { "id": "9c8d7e6f-...", "status": "CANCELLED" }
}

Search

GET/api/v1/search(cualquier :read)

Busca en todas las entidades para las que la API key tenga scope de lectura. Retorna resultados agrupados por tipo.

Query Parameters

Param	Tipo	Descripción
`q`	string	Texto de búsqueda (requerido, mínimo 2 caracteres)
`types`	string	Tipos a buscar separados por coma (ej: leads,contacts). Por defecto busca en todos.
`limit`	number	Max resultados por tipo (default 5, max 20)

curl

curl "https://zephcrm.com/api/v1/search?q=garcia&limit=5" \
  -H "Authorization: Bearer vk_live_..."

Response

{
  "data": {
    "leads": [
      { "id": "clx1...", "firstName": "Maria", "lastName": "Garcia", "email": "maria@empresa.com", "status": "QUALIFIED" }
    ],
    "contacts": [
      { "id": "clxc1...", "firstName": "Maria", "lastName": "Garcia", "email": "maria@techsa.com", "position": "CTO" }
    ],
    "companies": [],
    "opportunities": [],
    "activities": []
  }
}

OpenClaw / Agentes IA

Zeph CRM expone un skill spec publico compatible con OpenClaw y otros frameworks de agentes IA. El endpoint no requiere autenticación -- describe las herramientas disponibles para que un agente las descubra automáticamente.

Skill Spec URL: https://zephcrm.com/api/openclaw/skill

curl

curl "https://zephcrm.com/api/openclaw/skill"

Para configurar un agente, crea una API key con los scopes necesarios en Settings > API Keys y apunta tu agente al skill spec URL.

Necesitas ayuda? Contacta a soporte o visita el Centro de Ayuda.