Clients
Cree, lea, actualice y archive los clientes (empresas) de su agencia.
Devuelve una página de los clientes de su agencia, empezando por los más recientes. Todos los filtros son opcionales y se combinan (un cliente debe cumplir con todos ellos); para avanzar a más resultados, vuelva a enviar el nextCursor devuelto.
Listar / buscar clientes
/api/v1/clients{
"data": {
"clients": [
{
"id": "cli_123",
"businessName": "Acme Dental",
"industry": "Dental",
"status": "complete",
"goal": "get_reviews",
"healthScore": 82,
"locationCount": 1,
"googleRating": 4.8,
"googleReviewCount": 26,
"archived": false,
"archivedAt": null,
"scheduledArchiveAt": null,
"packageType": null,
"planName": null,
"createdAt": "2026-01-15T10:00:00.000Z",
"primaryRepresentative": {
"id": "usr_123",
"firstName": "Jamie",
"lastName": "Lee",
"email": "jamie@youragency.com"
}
}
],
"nextCursor": null,
"total": 1
}
}Crea un nuevo cliente en su agencia, además de una primera ubicación cuando los datos de dirección corresponden a un lugar real.
Crear un cliente
/api/v1/clients{
"data": {
"client": {
"id": "cli_123",
"businessName": "Acme Dental",
"website": null,
"industry": null,
"primaryContactEmail": "owner@acmedental.com",
"primaryRepresentativeId": "usr_123",
"visibility": "public",
"goal": null,
"notes": null,
"gbpLink": null,
"trackingKeyword": null,
"healthScore": null,
"planName": null,
"archived": false,
"archivedAt": null,
"scheduledArchiveAt": null,
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-01-15T10:00:00.000Z"
},
"locationId": "loc_456",
"locationSkipped": null
}
}Devuelve todos los detalles de un cliente: perfil de negocio, representante asignado, creador, puntuación de salud y plan.
Obtener un cliente
/api/v1/clients/{id}{
"data": {
"id": "cli_123",
"businessName": "Acme Dental",
"website": "https://acmedental.com",
"industry": "Dental",
"primaryContactEmail": "owner@acmedental.com",
"primaryRepresentativeId": "usr_123",
"visibility": "public",
"goal": "get_reviews",
"notes": null,
"gbpLink": null,
"trackingKeyword": "dentist near me",
"healthScore": 82,
"planName": null,
"archived": false,
"archivedAt": null,
"scheduledArchiveAt": null,
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-01-15T10:00:00.000Z",
"primaryRepresentative": {
"id": "usr_123",
"firstName": "Jamie",
"lastName": "Lee",
"email": "jamie@youragency.com"
},
"createdBy": {
"id": "usr_123",
"firstName": "Jamie",
"lastName": "Lee",
"email": "jamie@youragency.com"
},
"clientPlan": null
}
}Edita los campos editables de un cliente existente. Envíe solo los campos que desea cambiar. El primaryContactEmail del cliente (su acceso al portal) solo puede establecerse aquí mientras esté vacío — nunca puede cambiarse una vez establecido.
Actualizar un cliente
/api/v1/clients/{id}{
"data": {
"id": "cli_123",
"businessName": "Acme Dental",
"website": "https://acmedental.com",
"industry": "Dental",
"primaryContactEmail": "owner@acmedental.com",
"primaryRepresentativeId": "usr_123",
"visibility": "public",
"goal": "get_reviews",
"notes": null,
"gbpLink": null,
"trackingKeyword": "dentist near me",
"healthScore": 82,
"planName": null,
"archived": false,
"archivedAt": null,
"scheduledArchiveAt": null,
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-02-01T09:30:00.000Z"
}
}Solicita el archivado de un cliente — esta API nunca lo elimina de forma permanente. Si el cliente tiene alguna ubicación, esto lo PROGRAMA: el cliente y todas sus ubicaciones se archivan al final del periodo de facturación actual, y hasta entonces todo permanece totalmente activo y facturado — el archivado puede cancelarse con el endpoint cancel-archive. Un cliente sin ninguna ubicación se archiva de inmediato en su lugar (no hay nada que diferir). El campo outcome de la respuesta indica cuál de los dos ocurrió realmente.
Archivar un cliente
/api/v1/clients/{id}{
"data": {
"outcome": "scheduled",
"clientId": "cli_123",
"businessName": "Acme Dental",
"scheduledArchiveAt": "2026-02-01T00:00:00.000Z",
"archiveAt": "2026-03-01T00:00:00.000Z",
"locationCount": 1
}
}Cancela un archivado de cliente pendiente, de modo que un cliente programado para archivarse al final del periodo de facturación continúe con normalidad. También libera las ubicaciones que estaban programadas junto con él. Solo funciona mientras el archivado esté aún pendiente — un cliente ya archivado por completo debe reactivarse en su lugar, mediante el endpoint reactivate.
Cancelar un archivado programado
/api/v1/clients/{id}/cancel-archive{
"data": {
"cancelled": true,
"locationsReleased": 1
}
}Envía (o reenvía) el correo de invitación al portal de clientes al contacto principal de un cliente — un enlace mágico sin contraseña. Reenviarlo invalida cualquier enlace enviado previamente. Falla si el cliente no tiene un primaryContactEmail configurado.
Enviar la invitación al portal del cliente
/api/v1/clients/{id}/invite{
"data": {
"portalLink": "https://portal.synup.com/invite/aB3dE9fGhJ"
}
}Restaura un cliente ya archivado, y todas las ubicaciones que se archivaron junto con él. Un cliente que no está archivado actualmente es un éxito sin efecto, no un error. Esta es la única forma de revertir un cliente con outcome archived — uno que todavía esté programado debe pasar por cancel-archive en su lugar.
Reactivar un cliente archivado
/api/v1/clients/{id}/reactivate{
"data": {
"archived": false,
"locationsArchived": 1,
"locationsFailed": 0,
"cancelledScheduledPosts": 0
}
}Devuelve una instantánea consolidada de un cliente: estadísticas agregadas de ubicaciones, reseñas y SEO.
Obtener resumen del cliente
/api/v1/clients/summary{
"data": {
"locations": {
"total": 1,
"byStatus": {
"approved": 1
},
"byVerification": {
"unknown": 1
}
},
"reviews": {
"avgRating": 4.8,
"total": 26
},
"seo": {
"avgRank": 3.2,
"top3Pct": 0.62
}
}
}