Synupv1
Create a key
v1Resources/Clients

Clients

Create, read, update, and archive the clients (businesses) in your agency.

Returns a page of your agency's clients, most recently created first. All filters are optional and combine together (a client must match all of them); to page through more results, pass the returned nextCursor back in.

List / search clients

get/api/v1/clients
clients:read
Query parameters
searchstringoptional
Free-text search over the client's business name, industry, or primary contact email (case-insensitive, partial matches allowed).
statusarray of string (complete | draft)optional
Restrict to one or more statuses: complete (active, fully onboarded) or draft (still being set up).
representativeIdsarray of stringoptional
Restrict to clients assigned to one or more of these team-member ids — see GET /api/v1/team/members for your agency's member ids.
goalsarray of string (improve_rankings | get_reviews | fix_listings)optional
Restrict to one or more of the client's primary goals: improve_rankings, get_reviews, or fix_listings.
healthMinnumberoptional
Lowest health score to include, 0–100.
healthMaxnumberoptional
Highest health score to include, 0–100.
locationsMinnumberoptional
Fewest locations a client must have to be included.
locationsMaxnumberoptional
Most locations a client can have and still be included.
createdAfterstringoptional
Only clients created on or after this date.
createdBeforestringoptional
Only clients created on or before this date.
cursorstringoptional
Pagination cursor from a previous response's nextCursor. Leave empty for the first page.
limitintegeroptional
Clients to return per page, 1–200. Defaults to 50.
Response
dataobjectoptional
clientsarray of objectoptional
The matching clients for this page.
idstringoptional
Unique identifier for the client.
businessNamestringoptional
The client's business name.
industrystringoptional
The client's industry.
statusstring (complete | draft)optional
Onboarding status: complete (active) or draft.
goalstring (improve_rankings | get_reviews | fix_listings)optional
The client's primary goal, or null.
healthScorenumberoptional
A 0–100 score summarizing the client's account health, or null if not yet computed.
locationCountnumberoptional
Number of locations this client has, or null if unknown.
googleRatingnumberoptional
The client's current Google star rating, or null.
googleReviewCountnumberoptional
The client's current Google review count, or null.
planNamestringoptional
Name of the plan this client is on, if any.
createdAtstringoptional
When the client was created, as an ISO 8601 timestamp.
archivedbooleanoptional
Whether the client is archived.
archivedAtstringoptional
When the client was archived, as an ISO 8601 timestamp, or null.
scheduledArchiveAtstringoptional
When archival was requested (also the cohort token for cancelling it), as an ISO 8601 timestamp, or null if none is pending.
primaryRepresentativeobjectoptional
The team member responsible for this client, or null.
idstringoptional
firstNamestringoptional
lastNamestringoptional
emailstringoptional
nextCursorstringoptional
Pagination cursor for the next page, or null when there are no more results.
totalnumberoptional
Total number of clients matching the filters, across all pages.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/clients
Your API key
search
status
representativeIds
goals
healthMin
healthMax
locationsMin
locationsMax
createdAfter
createdBefore
cursor
limit
{
  "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
  }
}
v1Resources/Clients/postCreate a client

Creates a new client in your agency, plus a first location when address details resolve to a real place.

Create a client

post/api/v1/clients
clients:write
Request body
businessNamestringrequired
The business name for the new client.
primaryContactEmailstringrequired
Email address of the client's primary contact.
primaryRepresentativeIdstringrequired
ID of the team member responsible for this client — see GET /api/v1/team/members for your agency's member ids.
websitestringoptional
The client's website URL.
industrystringoptional
The client's industry.
goalstring (improve_rankings | get_reviews | fix_listings)optional
The client's primary goal: improve_rankings, get_reviews, or fix_listings.
gbpLinkstringoptional
The client's Google Business Profile URL.
placeIdstringoptional
The client's Google Place id, from Google's Places API — Synup has no places lookup of its own. Also creates the client's first location — do not follow this with a separate location create for the same business.
latitudenumberoptional
The client location's latitude. Required alongside placeId and longitude to also track a keyword.
longitudenumberoptional
The client location's longitude.
googleRatingnumberoptional
The client's current Google star rating, if known.
googleReviewCountnumberoptional
The client's current Google review count, if known.
trackingKeywordstringoptional
A keyword to track the client's local search rank for. Requires placeId, latitude, and longitude to also be set.
clientPlanIdstringoptional
Which customer-portal plan to assign. Defaults to your agency's default plan. There's no endpoint that lists plans — read a valid id off an existing client's clientPlan.id, or your agency's plan settings in Synup.
notesstringoptional
An internal note about the client — visible only to your team, never to the client.
Response
dataobjectoptional
clientobjectoptional
Additional internal fields may be present but are not part of the stable contract — rely only on the fields documented here.
idstringoptional
Unique identifier for the client.
businessNamestringoptional
The client's business name.
websitestringoptional
The client's website URL.
industrystringoptional
The client's industry.
primaryContactEmailstringoptional
Email address of the client's primary contact.
primaryRepresentativeIdstringoptional
ID of the team member responsible for this client — see GET /api/v1/team/members for your agency's member ids.
visibilitystring (public | private)optional
Whether the client is public or private within your agency.
goalstring (improve_rankings | get_reviews | fix_listings)optional
The client's primary goal, or null.
notesstringoptional
An internal note about the client — visible only to your team, never to the client.
gbpLinkstringoptional
The client's Google Business Profile URL, or null.
trackingKeywordstringoptional
A keyword tracked for this client's local search rank, or null.
healthScorenumberoptional
A 0–100 score summarizing the client's account health, or null if not yet computed.
planNamestringoptional
Name of the plan this client is on, if any.
archivedbooleanoptional
Whether the client is archived.
archivedAtstringoptional
When the client was archived, as an ISO 8601 timestamp, or null.
scheduledArchiveAtstringoptional
When archival was requested (also the cohort token for cancelling it), as an ISO 8601 timestamp, or null if none is pending.
createdAtstringoptional
When the client was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When the client was last updated, as an ISO 8601 timestamp.
locationIdstringoptional
ID of the first location created alongside this client, or null if none could be created yet.
locationSkippedstring (place_not_found | missing_country | location_limit | missing_category | failed)optional
Why no first location was created, when a placeId was supplied but no location resulted — for example location_limit means the agency is at its plan's location cap. Null when not applicable.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/clients
Your API key
Request body*
{
  "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
  }
}
v1Resources/Clients/getGet a client

Returns full details for one client: business profile, assigned representative, creator, health score, and plan.

Get a client

get/api/v1/clients/{id}
clients:read
Query parameters
idstringrequired
The client to look up.
Response
dataobjectoptional
Everything in Client, plus the resolved representative, creator, and plan objects.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/clients/{id}
Your API key
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
  }
}
v1Resources/Clients/patchUpdate a client

Edits an existing client's editable fields. Pass only the fields you want to change. The client's primaryContactEmail (their portal login) can only be set here while it's still blank — it can never be changed once set.

Update a client

patch/api/v1/clients/{id}
clients:write
Query parameters
idstringrequired
The client to update.
Request body
businessNamestringoptional
The business name for the new client.
industrystringoptional
The client's industry.
websitestringoptional
The client's website URL.
primaryContactNamestringoptional
The primary contact's name.
phonestringoptional
The client's phone number.
locationCountnumberoptional
The client's reported location count — informational only, not the actual count of created locations.
citystringoptional
The client's city.
phoneCountryCodestringoptional
The ISO-3166-1 alpha-2 country the client's phone number belongs to (e.g. "US", "IN") — the region, not the dial code.
countrystringoptional
The client's country, as an ISO-3166-1 alpha-2 code.
statestringoptional
The client's state, province, or region.
trackingKeywordstringoptional
A keyword to track the client's local search rank for.
notesstringoptional
An internal note about the client — visible only to your team, never to the client.
gbpLinkstringoptional
The client's Google Business Profile URL.
packageTypestringoptional
The client's package type.
clientPlanIdstringoptional
Which customer-portal plan to assign. Defaults to your agency's default plan. There's no endpoint that lists plans — read a valid id off an existing client's clientPlan.id, or your agency's plan settings in Synup.
primaryRepresentativeIdstringoptional
The user id of the team member who owns this client — see GET /api/v1/team/members for your agency's member ids.
visibilitystring (public | private)optional
Whether the client is public or private within your agency.
primaryContactEmailstringoptional
Email address of the client's primary contact. Settable only while still blank — it becomes the portal login and can never be changed once set.
Response
dataobjectoptional
Additional internal fields may be present but are not part of the stable contract — rely only on the fields documented here.
idstringoptional
Unique identifier for the client.
businessNamestringoptional
The client's business name.
websitestringoptional
The client's website URL.
industrystringoptional
The client's industry.
primaryContactEmailstringoptional
Email address of the client's primary contact.
primaryRepresentativeIdstringoptional
ID of the team member responsible for this client — see GET /api/v1/team/members for your agency's member ids.
visibilitystring (public | private)optional
Whether the client is public or private within your agency.
goalstring (improve_rankings | get_reviews | fix_listings)optional
The client's primary goal, or null.
notesstringoptional
An internal note about the client — visible only to your team, never to the client.
gbpLinkstringoptional
The client's Google Business Profile URL, or null.
trackingKeywordstringoptional
A keyword tracked for this client's local search rank, or null.
healthScorenumberoptional
A 0–100 score summarizing the client's account health, or null if not yet computed.
planNamestringoptional
Name of the plan this client is on, if any.
archivedbooleanoptional
Whether the client is archived.
archivedAtstringoptional
When the client was archived, as an ISO 8601 timestamp, or null.
scheduledArchiveAtstringoptional
When archival was requested (also the cohort token for cancelling it), as an ISO 8601 timestamp, or null if none is pending.
createdAtstringoptional
When the client was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When the client was last updated, as an ISO 8601 timestamp.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
patch/api/v1/clients/{id}
Your API key
id *
Request body
{
  "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"
  }
}
v1Resources/Clients/deleteArchive a client

Requests archival of a client — this API never permanently deletes one. If the client has any locations this SCHEDULES it: the client and every one of its locations archive at the end of the current billing period, and until then everything stays fully active and billed — the archival can be called off with the cancel-archive endpoint. A client with no locations at all is archived immediately instead (there's nothing to defer). The response's outcome field says which of the two actually happened.

Archive a client

delete/api/v1/clients/{id}
clients:write
Query parameters
idstringrequired
The client to archive.
Response
dataobjectoptional
Which fields are present depends on outcome: scheduled carries scheduledArchiveAt/archiveAt/locationCount; archived carries locationsArchived/locationsFailed/cancelledScheduledPosts.
outcomestring (scheduled | archived)required
What actually happened: archived (immediate — no locations existed, or none were live) or scheduled (archives at the end of the billing period).
clientIdstringrequired
Unique identifier for the client.
businessNamestringrequired
The client's business name.
scheduledArchiveAtstringoptional
When archival was requested (also the cohort token for cancelling it), as an ISO 8601 timestamp, or null if none is pending.
archiveAtstringoptional
When the scheduled archival will actually land — the agency's billing boundary. Null if the agency has none. Present only when outcome is scheduled.
locationCountnumberoptional
Number of locations this client has, or null if unknown.
locationsArchivednumberoptional
Number of locations archived along with the client. Present only when outcome is archived.
locationsFailednumberoptional
Number of locations that failed to archive. Present only when outcome is archived.
cancelledScheduledPostsnumberoptional
Number of scheduled posts cancelled as part of archiving. Present only when outcome is archived.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409The request conflicts with the current state of the resource — for example, changing the email or phone of a recipient who has already been messaged, or a team invite that was already accepted (or hasn't been accepted yet).
429Too many requests. Retry after the number of seconds in the Retry-After header.
delete/api/v1/clients/{id}
Your API key
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
  }
}
v1Resources/Clients/postCancel a scheduled archival

Calls off a pending client archival, so a client scheduled to archive at the end of the billing period carries on as normal. Also releases the locations that were scheduled along with it. Only works while the archival is still pending — a client already fully archived has to be reactivated instead, via the reactivate endpoint.

Cancel a scheduled archival

post/api/v1/clients/{id}/cancel-archive
clients:write
Query parameters
idstringrequired
The client whose pending archival should be cancelled.
Response
dataobjectoptional
cancelledbooleanoptional
Always true on success.
locationsReleasednumberoptional
Number of locations released from the cancelled archival schedule.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409The request conflicts with the current state of the resource — for example, changing the email or phone of a recipient who has already been messaged, or a team invite that was already accepted (or hasn't been accepted yet).
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/clients/{id}/cancel-archive
Your API key
id *
{
  "data": {
    "cancelled": true,
    "locationsReleased": 1
  }
}
v1Resources/Clients/postSend the client-portal invite

Sends (or resends) the customer-portal invite email to a client's primary contact — a passwordless magic link. Resending invalidates any previously sent link. Fails if the client has no primaryContactEmail set.

Send the client-portal invite

post/api/v1/clients/{id}/invite
clients:write
Query parameters
idstringrequired
The client to invite.
Response
dataobjectoptional
portalLinkstringoptional
The magic-link URL that was sent in the invite email.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/clients/{id}/invite
Your API key
id *
{
  "data": {
    "portalLink": "https://portal.synup.com/invite/aB3dE9fGhJ"
  }
}
v1Resources/Clients/postReactivate an archived client

Restores an already-archived client, and every location that archived along with it. A client that isn't currently archived is a no-op success, not an error. This is the only way back for a client with outcome archived — one that's still scheduled should go through cancel-archive instead.

Reactivate an archived client

post/api/v1/clients/{id}/reactivate
clients:write
Query parameters
idstringrequired
The client to reactivate.
Response
dataobjectoptional
archivedbooleanoptional
Whether the client is archived.
locationsArchivednumberoptional
Number of locations archived along with the client. Present only when outcome is archived.
locationsFailednumberoptional
Number of locations that failed to archive. Present only when outcome is archived.
cancelledScheduledPostsnumberoptional
Number of scheduled posts cancelled as part of archiving. Present only when outcome is archived.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/clients/{id}/reactivate
Your API key
id *
{
  "data": {
    "archived": false,
    "locationsArchived": 1,
    "locationsFailed": 0,
    "cancelledScheduledPosts": 0
  }
}
v1Resources/Clients/getGet client summary

Returns a rolled-up snapshot for one client: aggregate location, review, and SEO stats.

Get client summary

get/api/v1/clients/summary
clients:read
Query parameters
clientIdstringrequired
The client to summarize.
Response
dataobjectoptional
locationsobjectoptional
Aggregate location stats for this client.
reviewsobjectoptional
Aggregate review stats for this client.
seoobjectoptional
Aggregate SEO ranking stats for this client.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/clients/summary
Your API key
clientId *
{
  "data": {
    "locations": {
      "total": 1,
      "byStatus": {
        "approved": 1
      },
      "byVerification": {
        "unknown": 1
      }
    },
    "reviews": {
      "avgRating": 4.8,
      "total": 26
    },
    "seo": {
      "avgRank": 3.2,
      "top3Pct": 0.62
    }
  }
}