Synupv1
Create a key
v1Resources/Locations

Locations

Create, read, update, and manage the archive lifecycle of the locations belonging to your clients.

Returns a page of locations, newest first. All filters are optional and combine together (a location must match all of them); to page through more results, pass the returned nextCursor back in.

List / search locations

get/api/v1/locations
locations:read
Query parameters
clientIdstringoptional
Restrict results to one client. When your key is scoped to specific clients, this must be one of them. Look it up with GET /api/v1/clients.
searchstringoptional
Free-text search over the location's name, street address, city, or phone (case-insensitive, partial matches allowed).
statusstring (all | active | archived | archival_pending | verification_pending | unapproved | requires_action)optional
A single status bucket: all, active (not archived), archived, archival_pending, verification_pending (Google approval pending), unapproved, or requires_action. Defaults to all.
tagsarray of stringoptional
Internal tags — matches a location that has any of these.
categoriesarray of stringoptional
Category display names — matches a location whose general or Google category is any of these.
verificationarray of string (verified | pending | unverified | unknown)optional
Google verification state: verified, pending, unverified, or unknown.
createdAfterstringoptional
Only locations created on or after this date.
createdBeforestringoptional
Only locations created on or before this date.
cursorstringoptional
Pagination cursor from a previous response's nextCursor. Leave empty for the first page.
limitintegeroptional
Locations to return per page, 1–200. Defaults to 50.
Response
dataobjectoptional
locationsarray of objectoptional
The matching locations for this page.
idstringoptional
Unique identifier for the location.
namestringoptional
The location's business name.
addressstringoptional
The location's street address (combined street lines), or null.
citystringoptional
City.
statestringoptional
State or region.
postalCodestringoptional
Postal or ZIP code, or null.
countrystringoptional
Country, as an ISO-3166-1 alpha-2 code, or null.
phonestringoptional
Primary phone number, or null.
websitestringoptional
The location's website URL, or null.
storeCodestringoptional
Your internal store code / reference for this location, or null.
categorystringoptional
The location's display category (per-publisher primary category if set, else the general category), or null.
tagsarray of stringoptional
Internal tags for your own organization — not shown publicly.
labelsarray of stringoptional
Internal labels for this location.
statusstring (active | archived | archival_pending | verification_pending | unapproved | requires_action)optional
Derived status: active, archived, archival_pending, verification_pending (Google approval pending), unapproved, or requires_action.
verificationStatusstring (verified | pending | unverified | unknown)optional
Google verification state: verified, pending, unverified, or unknown, or null.
pendingChangesnumberoptional
Number of saved edits queued to publish but not yet synced to the connected directories.
lastPublishedAtstringoptional
When this location's details last successfully synced to a publisher, as an ISO 8601 timestamp, or null.
clientIdstringoptional
ID of the client this location belongs to, or null.
clientNamestringoptional
Business name of the client this location belongs to, or null.
createdAtstringoptional
When the location was created, as an ISO 8601 timestamp.
nextCursorstringoptional
Pagination cursor for the next page, or null when there are no more results.
totalnumberoptional
Total number of locations 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/locations
Your API key
clientId
search
status
tags
categories
verification
createdAfter
createdBefore
cursor
limit
{
  "data": [
    {
      "id": "loc_456",
      "name": "Acme Dental — Downtown",
      "city": "Austin",
      "state": "TX",
      "clientId": "cli_123",
      "createdAt": "2026-01-15T10:05:00.000Z"
    }
  ]
}
v1Resources/Locations/postCreate a location

Creates a new location for an existing client and submits it for publishing.

Create a location

post/api/v1/locations
locations:write
Request body
clientIdstringrequired
ID of the client to create this location under. Look it up with GET /api/v1/clients.
namestringrequired
The location's business name.
countryIsostringrequired
ISO country code, e.g. US.
streetstringrequired
Street address.
street1stringoptional
Street address, line 2.
citystringrequired
City.
stateIsostringrequired
State or region code.
postalCodestringrequired
Postal or ZIP code.
phonestringoptional
Phone number.
additionalPhonesarray of stringoptional
Any additional phone numbers beyond the primary one.
websitestringoptional
Website URL.
categoryIdstringoptional
General category id — look it up with GET /api/v1/locations/categories.
categoryNamestringoptional
General category display name.
publisherCategoriesobjectoptional
Per-publisher categories, one per publisher, each an { id, name } looked up via GET /api/v1/locations/publisher-categories.
googleobjectoptional
idstringoptional
namestringoptional
facebookobjectoptional
idstringoptional
namestringoptional
appleobjectoptional
idstringoptional
namestringoptional
bingobjectoptional
idstringoptional
namestringoptional
additionalCategoriesarray of objectoptional
Up to 9 extra categories, each an { id?, name }. A bare name is accepted and its id is resolved from the category catalog where one matches. Look up ids yourself with GET /api/v1/locations/categories.
idstringoptional
namestringoptional
descriptionstringoptional
A short description of the business.
tagsarray of stringoptional
Internal tags for your own organization — not shown publicly.
latitudenumberoptional
Latitude, in decimal degrees. Derived automatically from the address if omitted.
longitudenumberoptional
Longitude, in decimal degrees. Derived automatically from the address if omitted.
customFieldsobjectoptional
Custom field values to set on this location, keyed by field id.
Response
dataobjectoptional
locationIdstringoptional
ID of the newly created location.
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/locations
Your API key
Request body*
{
  "data": {
    "locationId": "loc_456"
  }
}
v1Resources/Locations/getGet a location

Returns the full business profile for one location: address, hours, categories, attributes, services, media, and verification status.

Get a location

get/api/v1/locations/{id}
locations:read
Query parameters
idstringrequired
The location to look up.
Response
dataobjectoptional
The full business profile for one location: address, hours, categories, attributes, services, media, and status — everything update_location can change, plus what create returned.
idstringoptional
Unique identifier for the location.
namestringoptional
The location's business name.
descriptionstringoptional
A description of the business, or null.
taglinestringoptional
A short tagline/slogan for the business, or null.
storeCodestringoptional
Your internal store code / reference for this location, or null.
logoUrlstringoptional
URL of the location's logo image, or null.
streetstringoptional
Street address, line 1, or null.
street1stringoptional
Street address, line 2, or null.
citystringoptional
City.
statestringoptional
State or region.
postalCodestringoptional
Postal or ZIP code, or null.
countrystringoptional
Country, as an ISO-3166-1 alpha-2 code, or null.
latitudenumberoptional
Latitude, or null.
longitudenumberoptional
Longitude, or null.
phonestringoptional
Primary phone number, or null.
additionalPhonesarray of stringoptional
Any additional phone numbers beyond the primary one.
websitestringoptional
The location's website URL, or null.
businessEmailstringoptional
A public contact email for the business, or null.
categoryNamestringoptional
The general category's display name, or null.
primaryCategoryDisplaystringoptional
The effective primary category's display name — per-publisher (Google) if set, else general — or null.
primaryCategoryGooglestringoptional
The location's primary Google category id (gcid), or null.
additionalCategoriesarray of objectoptional
Up to 9 extra categories, each with an id (when resolved) and a display name.
idstringoptional
namestringoptional
attributesarray of objectoptional
Google Business Profile attributes, as the stored { id, value } list.
idstringoptional
valueobjectoptional
The attribute's value — a boolean for yes/no attributes, a string for single-choice ones, or an object with setValues/unsetValues for multi-select.
servicesarray of objectoptional
The services or products this location offers.
namestringoptional
descriptionstringoptional
pricenumberoptional
currencystringoptional
googleServiceTypeIdstringoptional
ownerNamestringoptional
The owner's name, or null.
menuUrlstringoptional
URL of the business's menu, or null.
yearEstablishednumberoptional
The year the business was established, or null.
tagsarray of stringoptional
Internal tags for your own organization — not shown publicly.
labelsarray of stringoptional
Internal labels for this location.
regularHoursarray of objectoptional
The weekly regular-hours schedule, or null.
daystring (MONDAY | TUESDAY | WEDNESDAY | THURSDAY | FRIDAY | SATURDAY | SUNDAY)optional
closedbooleanoptional
periodsarray of objectoptional
openstringoptional
closestringoptional
moreHoursarray of objectoptional
Extra hour types beyond regular hours (delivery, takeout, etc.), or null.
specialHoursarray of objectoptional
One-off date overrides — holiday closures or a single day's special hours — or null.
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
clientIdstringoptional
ID of the client this location belongs to, or null.
archivedbooleanoptional
Whether the location is archived.
scheduledArchiveAtstringoptional
When archival was requested (also the token cancel-archive matches on), as an ISO 8601 timestamp, or null if none is pending.
verificationStatusstring (verified | pending | unverified | unknown)optional
Google verification state: verified, pending, unverified, or unknown, or null.
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/locations/{id}
Your API key
id *
{
  "data": {
    "id": "loc_456",
    "name": "Acme Dental — Downtown",
    "description": null,
    "tagline": null,
    "storeCode": null,
    "logoUrl": null,
    "street": "123 Main St",
    "street1": null,
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "latitude": 30.2672,
    "longitude": -97.7431,
    "phone": "+15125551234",
    "additionalPhones": [],
    "website": "https://acmedental.com",
    "businessEmail": null,
    "categoryName": "Dentist",
    "primaryCategoryDisplay": "Dentist",
    "primaryCategoryGoogle": "gcid:dentist",
    "additionalCategories": [],
    "attributes": [
      {
        "id": "attributes/wi_fi",
        "value": true
      }
    ],
    "services": [
      {
        "name": "Teeth Whitening",
        "description": null,
        "price": 150,
        "currency": "USD",
        "googleServiceTypeId": null
      }
    ],
    "ownerName": null,
    "menuUrl": null,
    "yearEstablished": null,
    "tags": [
      "vip"
    ],
    "labels": [],
    "regularHours": [
      {
        "day": "MONDAY",
        "closed": false,
        "periods": [
          {
            "openTime": "09:00",
            "closeTime": "17:00"
          }
        ]
      }
    ],
    "moreHours": [],
    "specialHours": [],
    "mediaByCategory": {
      "EXTERIOR": [
        {
          "url": "https://cdn.synup.com/media/1.jpg"
        }
      ]
    },
    "clientId": "cli_123",
    "archived": false,
    "scheduledArchiveAt": null,
    "verificationStatus": "verified"
  }
}
v1Resources/Locations/patchUpdate a location

Edits an existing location's business details — address, categories, Google Business Profile attributes, services, and hours. Pass only the fields you want to change; a field you do pass replaces its current value entirely (an empty string clears a text field, a full new list replaces an existing one). The country can't be changed after creation. Saved changes are automatically queued to sync out to the connected directories and listings.

Update a location

patch/api/v1/locations/{id}
locations:write
Query parameters
idstringrequired
The location to update.
Request body
namestringoptional
The location's business name.
descriptionstringoptional
A short description of the business.
taglinestringoptional
A short tagline/slogan for the business.
storeCodestringoptional
Your internal store code / reference for this location.
logoUrlstringoptional
URL of the location's logo image.
languageCodestringoptional
The primary language of the listing, as a code (e.g. "en").
streetstringoptional
Street address.
street1stringoptional
Street address, line 2.
citystringoptional
City.
stateIsostringoptional
State or region, as an ISO code (e.g. "CA").
postalCodestringoptional
Postal or ZIP code.
latitudenumberoptional
Latitude. If you change the address without also setting this, it's re-derived automatically.
longitudenumberoptional
Longitude. If you change the address without also setting this, it's re-derived automatically.
phonestringoptional
Phone number.
additionalPhonesarray of stringoptional
Any additional phone numbers beyond the primary one.
websitestringoptional
Website URL.
businessEmailstringoptional
A public contact email for the business.
categoryIdstringoptional
General category id — look it up with GET /api/v1/locations/categories.
categoryNamestringoptional
General category display name.
publisherCategoriesobjectoptional
Per-publisher PRIMARY category — currently only google is supported here (an id and a name are both required; passing one alone would clear the category). Facebook/Apple/Bing can only be changed in the location editor. Look up google's id/name pair with GET /api/v1/locations/publisher-categories.
googleobjectoptional
idstringoptional
namestringoptional
additionalCategoriesarray of objectoptional
Up to 9 extra categories, each an { id?, name }. A bare name is accepted and its id is resolved from the category catalog where one matches. Look up ids yourself with GET /api/v1/locations/categories.
idstringoptional
namestringoptional
attributesobjectoptional
Google Business Profile attributes, as a map of attribute id to value (e.g. { "attributes/wi_fi": "free" }) — REPLACES the whole set, so read the current ones from GET /api/v1/locations/{id} and pass back everything you want kept. An id with no valid Google representation for this location's category is dropped and reported back in rejectedAttributes rather than failing the whole request. There's no endpoint listing which attribute ids are valid for a category — that's Google's own Business Profile attribute reference, not Synup's.
servicesarray of objectoptional
The services or products this location offers — replaces the existing list.
namestringoptional
descriptionstringoptional
pricenumberoptional
currencystringoptional
googleServiceTypeIdstringoptional
ownerNamestringoptional
The owner's name.
menuUrlstringoptional
URL of the business's menu.
yearEstablishednumberoptional
The year the business was established (e.g. 2012).
tagsarray of stringoptional
Internal tags for your own organization — not shown publicly. Replaces the existing list.
labelsarray of stringoptional
Internal labels for this location. Replaces the existing list.
regularHoursarray of objectoptional
The weekly regular-hours schedule — replaces the existing schedule entirely. One entry per day of the week.
daystring (MONDAY | TUESDAY | WEDNESDAY | THURSDAY | FRIDAY | SATURDAY | SUNDAY)optional
closedbooleanoptional
periodsarray of objectoptional
openstringoptional
closestringoptional
moreHoursarray of objectoptional
Extra hour types beyond regular hours (delivery, takeout, happy hour, etc.), replaces the existing list.
specialHoursarray of objectoptional
One-off date overrides — holiday closures or a single day's special hours — replaces the existing list. Any calendar date works, not just named holidays.
applyToPublishersarray of string (google | facebook | apple | bing)optional
Change these values for specific publishers only instead of the shared default every publisher inherits.
Response
dataobjectoptional
locationobjectoptional
The full business profile for one location: address, hours, categories, attributes, services, media, and status — everything update_location can change, plus what create returned.
idstringoptional
Unique identifier for the location.
namestringoptional
The location's business name.
descriptionstringoptional
A description of the business, or null.
taglinestringoptional
A short tagline/slogan for the business, or null.
storeCodestringoptional
Your internal store code / reference for this location, or null.
logoUrlstringoptional
URL of the location's logo image, or null.
streetstringoptional
Street address, line 1, or null.
street1stringoptional
Street address, line 2, or null.
citystringoptional
City.
statestringoptional
State or region.
postalCodestringoptional
Postal or ZIP code, or null.
countrystringoptional
Country, as an ISO-3166-1 alpha-2 code, or null.
latitudenumberoptional
Latitude, or null.
longitudenumberoptional
Longitude, or null.
phonestringoptional
Primary phone number, or null.
additionalPhonesarray of stringoptional
Any additional phone numbers beyond the primary one.
websitestringoptional
The location's website URL, or null.
businessEmailstringoptional
A public contact email for the business, or null.
categoryNamestringoptional
The general category's display name, or null.
primaryCategoryDisplaystringoptional
The effective primary category's display name — per-publisher (Google) if set, else general — or null.
primaryCategoryGooglestringoptional
The location's primary Google category id (gcid), or null.
additionalCategoriesarray of objectoptional
Up to 9 extra categories, each with an id (when resolved) and a display name.
idstringoptional
namestringoptional
attributesarray of objectoptional
Google Business Profile attributes, as the stored { id, value } list.
idstringoptional
valueobjectoptional
The attribute's value — a boolean for yes/no attributes, a string for single-choice ones, or an object with setValues/unsetValues for multi-select.
servicesarray of objectoptional
The services or products this location offers.
namestringoptional
descriptionstringoptional
pricenumberoptional
currencystringoptional
googleServiceTypeIdstringoptional
ownerNamestringoptional
The owner's name, or null.
menuUrlstringoptional
URL of the business's menu, or null.
yearEstablishednumberoptional
The year the business was established, or null.
tagsarray of stringoptional
Internal tags for your own organization — not shown publicly.
labelsarray of stringoptional
Internal labels for this location.
regularHoursarray of objectoptional
The weekly regular-hours schedule, or null.
daystring (MONDAY | TUESDAY | WEDNESDAY | THURSDAY | FRIDAY | SATURDAY | SUNDAY)optional
closedbooleanoptional
periodsarray of objectoptional
moreHoursarray of objectoptional
Extra hour types beyond regular hours (delivery, takeout, etc.), or null.
specialHoursarray of objectoptional
One-off date overrides — holiday closures or a single day's special hours — or null.
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
clientIdstringoptional
ID of the client this location belongs to, or null.
archivedbooleanoptional
Whether the location is archived.
scheduledArchiveAtstringoptional
When archival was requested (also the token cancel-archive matches on), as an ISO 8601 timestamp, or null if none is pending.
verificationStatusstring (verified | pending | unverified | unknown)optional
Google verification state: verified, pending, unverified, or unknown, or null.
rejectedAttributesarray of stringoptional
Attribute ids from the request that were NOT written — either they have a dedicated field of their own, or their value had no valid Google representation. Present only when at least one was rejected.
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/locations/{id}
Your API key
id *
Request body
{
  "data": {
    "location": {
      "id": "loc_456",
      "name": "Acme Dental — Downtown",
      "tagline": "Gentle care, on time",
      "city": "Austin",
      "state": "TX",
      "clientId": "cli_123"
    },
    "rejectedAttributes": []
  }
}
v1Resources/Locations/getList a location's services

The Google Business Profile services this location offers.

List a location's services

get/api/v1/locations/{id}/services
locations:read
Query parameters
idstringrequired
Response
dataobjectoptional
servicesarray of objectoptional
namestringrequired
Service name.
descriptionstringoptional
Service description.
pricenumberoptional
Service price.
currencystringoptional
Currency code for the price.
googleServiceTypeIdstringoptional
Google's structured service-type id, if matched to one.
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/locations/{id}/services
Your API key
id *
{
  "data": {
    "services": [
      {
        "name": "Teeth Whitening",
        "description": null,
        "price": 150,
        "currency": "USD",
        "googleServiceTypeId": null
      }
    ]
  }
}
v1Resources/Locations/postAdd a service

Adds one service to the location's list and re-publishes the full list to Google (Google has no atomic add — every save replaces the whole array).

Add a service

post/api/v1/locations/{id}/services
locations:write
Query parameters
idstringrequired
Request body
namestringrequired
Service name.
descriptionstringoptional
Service description.
pricenumberoptional
Service price.
currencystringoptional
Currency code for the price.
googleServiceTypeIdstringoptional
Google's structured service-type id, if matched to one.
Response
dataobjectoptional
servicesarray of objectoptional
namestringrequired
Service name.
descriptionstringoptional
Service description.
pricenumberoptional
Service price.
currencystringoptional
Currency code for the price.
googleServiceTypeIdstringoptional
Google's structured service-type id, if matched to one.
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.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/locations/{id}/services
Your API key
id *
Request body*
{
  "data": {
    "services": [
      {
        "name": "Teeth Whitening",
        "description": null,
        "price": 150,
        "currency": "USD",
        "googleServiceTypeId": null
      }
    ]
  }
}
v1Resources/Locations/deleteRemove a service

Removes one service by name and re-publishes the remaining list to Google.

Remove a service

delete/api/v1/locations/{id}/services
locations:write
Query parameters
idstringrequired
namestringrequired
Exact name of the service to remove.
Response
dataobjectoptional
servicesarray of objectoptional
namestringrequired
Service name.
descriptionstringoptional
Service description.
pricenumberoptional
Service price.
currencystringoptional
Currency code for the price.
googleServiceTypeIdstringoptional
Google's structured service-type id, if matched to one.
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.
429Too many requests. Retry after the number of seconds in the Retry-After header.
delete/api/v1/locations/{id}/services
Your API key
id *
name *
{
  "data": {
    "services": []
  }
}
v1Resources/Locations/postSchedule a location to archive

SCHEDULES a location to archive at the end of the current billing period. The location stays fully active, billable, and still counts against the plan's location limit until then — nothing is deleted, and scheduling does not free room to add another location until it actually archives. Call cancel-archive to call this off before it lands, or reactivate afterward to bring the location back.

Schedule a location to archive

post/api/v1/locations/{id}/archive
locations:write
Query parameters
idstringrequired
The location to schedule for archival.
Response
dataobjectoptional
scheduledbooleanoptional
Always true on success.
scheduledArchiveAtstringoptional
When archival was requested (also the token cancel-archive matches on), 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.
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/locations/{id}/archive
Your API key
id *
{
  "data": {
    "scheduled": true,
    "scheduledArchiveAt": "2026-02-01T00:00:00.000Z",
    "archiveAt": "2026-03-01T00:00:00.000Z"
  }
}
v1Resources/Locations/postCancel a scheduled archival

Calls off a pending location archival, so a location scheduled to archive at the end of the billing period carries on as normal. Only works while the archival is still pending — a location that has already archived has to be reactivated instead.

Cancel a scheduled archival

post/api/v1/locations/{id}/cancel-archive
locations:write
Query parameters
idstringrequired
The location whose pending archival should be cancelled.
Response
dataobjectoptional
cancelledbooleanoptional
Always true on success.
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/locations/{id}/cancel-archive
Your API key
id *
{
  "data": {
    "cancelled": true
  }
}
v1Resources/Locations/postReactivate an archived location

Restores an already-archived location — and every listing under it — and clears any pending archival schedule. A location that isn't currently archived is a no-op success, not an error.

Reactivate an archived location

post/api/v1/locations/{id}/reactivate
locations:write
Query parameters
idstringrequired
The location to reactivate.
Response
dataobjectoptional
archivedbooleanoptional
Whether the location is archived.
cancelledScheduledPostsnumberoptional
Number of scheduled posts cancelled as part of reactivating away from an archived state, if any.
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/locations/{id}/reactivate
Your API key
id *
{
  "data": {
    "archived": false,
    "cancelledScheduledPosts": 0
  }
}
v1Resources/Locations/getGet locations summary

Returns aggregate location counts across your agency (or one client), broken down by status, package tier, and verification state.

Get locations summary

get/api/v1/locations/summary
locations:read
Query parameters
clientIdstringoptional
Limit to one client's locations. Omitted, this summarizes every location your key can see. Look it up with GET /api/v1/clients.
tagsstringoptional
Limit to locations carrying any of these comma-separated internal tags.
Response
dataobjectoptional
totalnumberoptional
Total number of matching locations.
byStatusobjectoptional
Location counts grouped by status.
byVerificationobjectoptional
Location counts grouped by verification state.
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/locations/summary
Your API key
clientId
tags
{
  "data": {
    "total": 12,
    "byStatus": {
      "approved": 10,
      "pending_verification": 1,
      "archival_pending": 1
    },
    "byVerification": {
      "verified": 9,
      "pending": 1,
      "unknown": 2
    }
  }
}
v1Resources/Locations/postCreate a tag

Creates a new internal tag, scoped to one client.

Create a tag

post/api/v1/locations/tags
locations:write
Request body
clientIdstringrequired
The client this tag belongs to. Look it up with GET /api/v1/clients.
namestringrequired
The tag's name.
Response
dataobjectoptional
idstringoptional
Unique identifier for the newly created tag.
namestringoptional
The tag's name.
clientIdstringoptional
The client this tag belongs to. Look it up with GET /api/v1/clients.
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.
post/api/v1/locations/tags
Your API key
Request body*
{
  "data": {
    "id": "tag_789",
    "name": "VIP",
    "clientId": "cli_123"
  }
}
v1Resources/Locations/deleteDelete a tag

Deletes an internal tag. This does not delete the locations it was applied to. locationsUnassigned in the response says how many locations lost this tag.

Delete a tag

delete/api/v1/locations/tags/{id}
locations:write
Query parameters
idstringrequired
ID of the tag to delete.
Response
dataobjectoptional
locationsUnassignednumberoptional
Number of locations that had this tag — all of them lost the assignment when the tag was deleted.
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.
delete/api/v1/locations/tags/{id}
Your API key
id *
{
  "data": {
    "locationsUnassigned": 3
  }
}
v1Resources/Locations/postAdd locations to a tag

Applies an existing tag to one or more locations.

Add locations to a tag

post/api/v1/locations/tags/{id}/locations
locations:write
Query parameters
idstringrequired
ID of the tag.
Request body
locationIdsarray of stringrequired
IDs of the locations to tag.
Response
dataobjectoptional
addedarray of stringoptional
IDs of the locations the tag was actually added to.
skippedarray of stringoptional
IDs of the locations skipped because they already carried this tag.
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.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/locations/tags/{id}/locations
Your API key
id *
Request body*
{
  "data": {
    "added": [
      "loc_456"
    ],
    "skipped": []
  }
}
v1Resources/Locations/deleteRemove a location from a tag

Removes a single location, by id, from a tag.

Remove a location from a tag

delete/api/v1/locations/tags/{id}/locations
locations:write
Query parameters
idstringrequired
ID of the tag.
locationIdstringrequired
ID of the location to untag.
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.
429Too many requests. Retry after the number of seconds in the Retry-After header.
delete/api/v1/locations/tags/{id}/locations
Your API key
id *
locationId *
{}
v1Resources/Locations/getSearch the general category taxonomy

Searches the general business category taxonomy (mirrors Google's, thousands of entries) — global reference data, not scoped to your agency. The returned id is a Category id to set as a location's categoryId on create or update. For a specific publisher's own catalog, use GET /api/v1/locations/publisher-categories instead. Omit search entirely to list the full taxonomy, uncapped.

Search the general category taxonomy

get/api/v1/locations/categories
locations:read
Query parameters
searchstringoptional
Category name substring to match. Omit to list the entire taxonomy, uncapped (limit is ignored in that case).
limitintegeroptional
Rows to return, 1–100. Defaults to 25.
Response
dataobjectoptional
categoriesarray of objectoptional
The matching general categories.
idstringoptional
The Category id — pass this as categoryId on create or update.
namestringoptional
The category's display name.
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/locations/categories
Your API key
search
limit
{
  "data": {
    "categories": [
      {
        "id": "cat_dentist",
        "name": "Dentist"
      },
      {
        "id": "cat_orthodontist",
        "name": "Orthodontist"
      }
    ]
  }
}
v1Resources/Locations/getSearch a publisher's own category catalog

Searches one publisher's own (GABF) category catalog — global reference data, not scoped to your agency. Use the returned id for a location's publisherCategories on create or update. Omit query entirely to list the publisher's whole catalog, uncapped.

Search a publisher's own category catalog

get/api/v1/locations/publisher-categories
locations:read
Query parameters
publisherstring (google | facebook | apple | bing)required
Which publisher's catalog to search: google, apple, bing, or facebook.
querystringoptional
Category name substring to match. Omit to list the publisher's entire catalog, uncapped.
countrystringoptional
ISO-3166-1 alpha-2 country — recommended for apple, whose categories are country-specific.
Response
dataobjectoptional
categoriesarray of objectoptional
The matching categories in the requested publisher's own catalog.
idstringoptional
The publisher's own category id — pass this in publisherCategories on create or update. Null is possible for a catalog entry with no id.
displayNamestringoptional
The category's display name in that publisher's catalog.
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/locations/publisher-categories
Your API key
publisher *
query
country
{
  "data": {
    "categories": [
      {
        "id": "gcid:dentist",
        "displayName": "Dentist"
      }
    ]
  }
}
v1Resources/Locations/getList locations with their media

Lists locations together with their photos, newest first — same filters as GET /api/v1/locations. Use this for questions like "which locations have no photos?", rather than GET /api/v1/media, which returns only ONE location's media at a time.

List locations with their media

get/api/v1/locations/media
media:read
Query parameters
clientIdstringoptional
Limit to one client's locations. Required when your key is scoped to specific clients — there is no per-row client field here to check a merged, unscoped result against, so an omitted clientId is refused rather than guessed at. Look it up with GET /api/v1/clients.
searchstringoptional
Free-text search over the location's name, street address, city, or phone (case-insensitive, partial matches allowed).
statusstring (all | active | archived | archival_pending | verification_pending | unapproved | requires_action)optional
A single status bucket: all, active (not archived), archived, archival_pending, verification_pending (Google approval pending), unapproved, or requires_action. Defaults to all.
tagsarray of stringoptional
Internal tags — matches a location that has any of these.
categoriesarray of stringoptional
Category display names — matches a location whose general or Google category is any of these.
verificationarray of string (verified | pending | unverified | unknown)optional
Google verification state: verified, pending, unverified, or unknown.
createdAfterstringoptional
Only locations created on or after this date.
createdBeforestringoptional
Only locations created on or before this date.
cursorstringoptional
Pagination cursor from a previous response's nextCursor. Leave empty for the first page.
limitintegeroptional
Locations to return per page, 1–100. Defaults to 100.
Response
dataobjectoptional
locationsarray of objectoptional
The matching locations for this page.
idstringoptional
Unique identifier for the location.
namestringoptional
The location's business name.
logoUrlstringoptional
URL of the location's logo, or null.
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
totalnumberoptional
Total number of photos across every category for this location.
nextCursorstringoptional
Pagination cursor for the next page, or null when there are no more results.
totalnumberoptional
Total number of locations matching the filters, across all pages.
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/locations/media
Your API key
clientId
search
status
tags
categories
verification
createdAfter
createdBefore
cursor
limit
{
  "data": {
    "locations": [
      {
        "id": "loc_456",
        "name": "Acme Dental — Downtown",
        "logoUrl": null,
        "mediaByCategory": {
          "EXTERIOR": [
            {
              "url": "https://cdn.synup.com/media/1.jpg"
            }
          ]
        },
        "total": 1
      }
    ],
    "nextCursor": null,
    "total": 1
  }
}
v1Resources/Locations/postUpload photos to a location

Adds one or more photos to a location, in a given category. Provide each image as a public https URL (fetched and re-hosted) or as base64 bytes. Only images are supported (jpeg, png, gif, webp), max 5 MB each. The LOGO category holds a single logo — uploading to LOGO replaces the current one. Every other category appends. Saved photos are automatically queued to publish to Google.

Upload photos to a location

post/api/v1/locations/{id}/media
locations:write
Query parameters
idstringrequired
The location to add photos to.
Request body
categorystring (COVER | PROFILE | LOGO | EXTERIOR | INTERIOR | PRODUCT | FOOD_AND_DRINK | MENU | AT_WORK | TEAMS | ROOMS | COMMON_AREA | ADDITIONAL)required
The photo category to add to. LOGO replaces the current logo; every other category appends.
imagesarray of objectrequired
One or more images to add. Each needs a url or base64.
urlstringoptional
A public https URL to the image — it is fetched and re-hosted.
base64stringoptional
The image bytes as base64 (a data: URL prefix is accepted). Use this instead of url when you have the bytes.
labelstringoptional
Optional caption/label for the photo.
Response
dataobjectoptional
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
addedarray of objectoptional
The photo(s) that were actually added, each with the category it landed in and its hosted URL.
categorystringoptional
urlstringoptional
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.
post/api/v1/locations/{id}/media
Your API key
id *
Request body*
{
  "data": {
    "mediaByCategory": {
      "EXTERIOR": [
        {
          "url": "https://cdn.synup.com/media/1.jpg",
          "source": "agent_upload"
        }
      ]
    },
    "added": [
      {
        "category": "EXTERIOR",
        "url": "https://cdn.synup.com/media/1.jpg"
      }
    ]
  }
}
v1Resources/Locations/deleteDelete a location's photos

Removes photos from a location. Pass urls to delete specific photos, or category to clear a whole category. The logo can never be deleted through this endpoint — by url or by category — upload a new LOGO image to replace it instead. This removes the photos in the app; it does not delete them from Google.

Delete a location's photos

delete/api/v1/locations/{id}/media
locations:write
Query parameters
idstringrequired
The location to remove photos from.
Request body
urlsarray of stringoptional
Specific photo URLs to remove (from a location's mediaByCategory).
categorystring (COVER | PROFILE | EXTERIOR | INTERIOR | PRODUCT | FOOD_AND_DRINK | MENU | AT_WORK | TEAMS | ROOMS | COMMON_AREA | ADDITIONAL)optional
Clear every photo in this category. LOGO is not an allowed value — the logo can't be deleted.
Response
dataobjectoptional
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
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.
delete/api/v1/locations/{id}/media
Your API key
id *
Request body
{
  "data": {
    "mediaByCategory": {
      "EXTERIOR": []
    },
    "removed": [
      "https://cdn.synup.com/media/1.jpg"
    ]
  }
}