Listar contactos

GET /api/v1/contacts

Este endpoint permite obtener un listado paginado de los contactos registrados en la plataforma. Es útil para consultar y organizar la información de los contactos asociados a su equipo. Permite realizar una búsqueda general que cruza nombre, documento de identificación y otros campos relacionados.

La respuesta del endpoint incluye un conjunto de datos estructurados con la información principal de cada contacto y los metadatos de paginación para navegar de forma sencilla entre los resultados.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

⚠️ Contactos activos

Este endpoint solo devolverá los contactos que se encuentren activos en la plataforma.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
search	String	❌ No	Término de búsqueda general. Debe tener al menos 3 caracteres.
page	Integer	❌ No	Número de la página que se desea obtener. Por defecto es 1.
per_page	Integer	❌ No	Cantidad de resultados por página. El valor por defecto es 15 y el rango es de 1 a 20
from_date	String	❌ No	Fecha que permite aplicar el filtrado desde una fecha en particular (Aplicado en created_at). Formato: YYYY-MM-DD HH:MM:SS
to_date	String	❌ No	Fecha que permite aplicar el filtrado hasta una fecha en particular (Aplicado en created_at). Formato: YYYY-MM-DD HH:MM:SS

Criterios de Búsqueda (search)

El parámetro search es multifacético y buscará coincidencias en los siguientes campos:

• Nombre completo del contacto (name y last_name).
• Número de documento del contacto (doc_num).
• Nombre de la empresa asociada (company.name).
• RUC de la empresa asociada (company.ruc).
• Vías de contacto (contact_sources.source).
• Campos personalizados (extra_fields.value).

Ejemplo de solicitud

GET /api/v1/contacts?search=julian

Respuesta

La API devuelve un objeto JSON con la siguiente estructura.

Respuesta base 200

{
	"message": "Contactos obtenidos correctamente",
	"data": [
		{
			"id": 66,
			"name": "Julian",
			"last_name": "Ramirez",
			"doc_type": "OTROS",
			"doc_num": "90817456",
			"active": true,
			"details": null,
			"company": {
				"id": 2,
				"name": "Elemental Solutions SAC",
				"ruc": "20567898766"
			},
			"extra_fields": [
				{
					"id": 2,
					"name": "Canal preferido de contacto",
					"value": "Teléfono"
				},
				{
					"id": 20,
					"name": "Cargo laboral",
					"value": null
				},
				{
					"id": 21,
					"name": "Ingreso mensual aproximado",
					"value": "1200"
				},
				{
					"id": 22,
					"name": "Comentarios adicionales",
					"value": null
				},
				{
					"id": 23,
					"name": "Nivel de interés",
					"value": "Medio"
				},
				{
					"id": 24,
					"name": "Servicios de interés",
					"value": [
						"Ventas"
					]
				},
				{
					"id": 25,
					"name": "Género",
					"value": "M"
				},
				{
					"id": 26,
					"name": "Fecha de aceptación de términos",
					"value": "2025-09-08"
				}
			],
			"contact_sources": [
				{
					"type": "CELL_PHONE",
					"source": "+5112345678"
				},
				{
					"type": "CELL_PHONE",
					"source": "+51987654321"
				},
				{
					"type": "EMAIL",
					"source": "julian.ramirez@example.com"
				}
			],
			"created_at": "2025-09-09T02:01:13.000000Z",
			"addresses": [],
			"is_vip": false,
			"portfolio": {
				"id": 23,
				"name": "Cartera Navidad",
				"agent": "Karla Rodriguez"
			}
		}
	],
	"pagination": {
		"total_items": 1,
		"items_per_page": 15,
		"current_page": 1,
		"total_pages": 1
	}
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de respuesta del servidor.
data	Array	Lista de contactos obtenidos.
data.id	Integer	Identificador único del contacto.
data.name	String	Nombre(s) del contacto.
data.last_name	String	Apellido(s) del contacto.
data.doc_type	String | null	Tipo de documento de identidad (ej. DNI, RUC, PASAPORTE, OTROS).
data.doc_num	String | null	Número del documento de identidad.
data.active	Boolean	Indica si el contacto está activo (true) o inactivo (false).
data.details	String | null	Notas o detalles adicionales sobre el contacto.
data.company	Object | null	Objeto con la información de la empresa asociada.
data.company.id	Integer	Identificador único de la empresa.
data.company.name	String	Nombre de la empresa.
data.company.ruc	String	RUC de la empresa.
data.extra_fields	Array	Lista de objetos, donde cada objeto representa un campo adicional con su ID, nombre y valor..
data.contact_sources	Array	Lista de las vías de contacto asociadas (teléfonos, correos, etc.).
data.contact_sources.type	String	Tipo de vía de contacto (ej. PHONE, EMAIL, CELL_PHONE).
data.contact_sources.source	String	El valor de la vía de contacto (ej. 987654321).
data.created_at	String	Fecha y hora de creación del registro
data.addresses	Array	Lista de direcciones asociadas al contacto.
data.addresses.address	String	El texto de la dirección.
data.addresses.reference	String	Referencia para ubicar la dirección.
data.addresses.postal_code	String	Código postal.
data.addresses.department_name	String	Nombre del departamento.
data.addresses.province_name	String	Nombre de la provincia.
data.addresses.district_name	String	Nombre del distrito.
data.is_vip	Boolean	Indica si el contacto está marcado como VIP.
data.portfolio	Object/null	Objecto que contiene información de cartera o null si el contacto no tiene Cartera.
data.portfolio.id	Integer	Identificador de la cartera.
data.portfolio.name	String	Nombre de la cartera.
data.portfolio.agent	String/null	Nombre de agente asociado a la cartera o null si no hay agente asociado a la Cartera.
pagination	Object	Información de la paginación.
pagination.total_items	Integer	Total de elementos encontrados.
pagination.items_per_page	Integer	Elementos por página.
pagination.current_page	Integer	Página actual.
pagination.total_pages	Integer	Total de páginas.

Errores generales

Código HTTP	Tipo	Causa común
401	Unauthorized	El token de acceso no fue proporcionado en el encabezado Authorization, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
422	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, from_date no es una fecha válida); 2. Recurso inexistente (wa_number no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
500	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.