Clients
Crie, leia, atualize e arquive os clientes (empresas) da sua agência.
Retorna uma página dos clientes da sua agência, os mais recentes primeiro. Todos os filtros são opcionais e se combinam (um cliente precisa corresponder a todos); para avançar para mais resultados, envie novamente o nextCursor retornado.
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
}
}Cria um novo cliente na sua agência, além de um primeiro local quando os dados de endereço correspondem a um lugar real.
Criar um 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
}
}Retorna todos os detalhes de um cliente: perfil comercial, representante atribuído, criador, pontuação de saúde e plano.
Obter um 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 os campos editáveis de um cliente existente. Envie apenas os campos que deseja alterar. O primaryContactEmail do cliente (o login do portal) só pode ser definido aqui enquanto ainda estiver vazio — nunca pode ser alterado depois de definido.
Atualizar um 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 o arquivamento de um cliente — esta API nunca exclui um cliente permanentemente. Se o cliente tiver algum local, isso é AGENDADO: o cliente e todos os seus locais são arquivados no final do período de faturamento atual, e até então tudo permanece totalmente ativo e faturado — o arquivamento pode ser cancelado com o endpoint cancel-archive. Já um cliente sem nenhum local é arquivado imediatamente (não há nada a postergar). O campo outcome da resposta informa qual dos dois realmente aconteceu.
Arquivar um 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 um arquivamento de cliente pendente, de modo que um cliente agendado para arquivar no final do período de faturamento continue normalmente. Também libera os locais que estavam agendados junto com ele. Só funciona enquanto o arquivamento ainda estiver pendente — um cliente já totalmente arquivado precisa ser reativado, através do endpoint reactivate.
Cancelar um arquivamento agendado
/api/v1/clients/{id}/cancel-archive{
"data": {
"cancelled": true,
"locationsReleased": 1
}
}Envia (ou reenvia) o e-mail de convite do portal do cliente ao contato principal de um cliente — um link mágico sem senha. Reenviar invalida qualquer link enviado anteriormente. Falha se o cliente não tiver um primaryContactEmail definido.
Enviar o convite do portal do cliente
/api/v1/clients/{id}/invite{
"data": {
"portalLink": "https://portal.synup.com/invite/aB3dE9fGhJ"
}
}Restaura um cliente já arquivado, e todos os locais que foram arquivados junto com ele. Um cliente que não está arquivado no momento é um sucesso sem efeito (no-op), não um erro. Esta é a única forma de reverter um cliente com outcome archived — um que ainda esteja scheduled deve passar pelo cancel-archive em vez disso.
Reativar um cliente arquivado
/api/v1/clients/{id}/reactivate{
"data": {
"archived": false,
"locationsArchived": 1,
"locationsFailed": 0,
"cancelledScheduledPosts": 0
}
}Retorna um retrato consolidado de um cliente: estatísticas agregadas de localizações, avaliações e SEO.
Obter resumo do 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
}
}
}