Console API

Listings

11 endpoints.

GET/api/v1/admin/businesses/{business_id}/listings

List managed GBP listings grouped by internal location

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ManagedListingsData_

Field Type Description

request_idrequired string

success true default true

datarequired

ManagedListingsData

ManagedListingsData fields

Field	Type	Description
`groups`required	`ListingLocationGroup[]`	ListingLocationGroup[] fields ListingLocationGroup (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/listings/{listing_id}

Get managed listing detail (overview from GBP Business Information)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ListingDetailData_

Field Type Description

request_idrequired string

success true default true

datarequired

ListingDetailData

ListingDetailData fields

Field Type Description

listing_idrequired string (uuid)

business_idrequired string (uuid)

gbp_location_idrequired string

full_resource_namerequired string

internal_location_idrequired string (uuid) | null

is_managedrequired boolean

titlerequired string | null

store_coderequired string | null

overviewrequired

ListingOverviewData | null

ListingOverviewData fields

Field	Type	Description
`name`	`string \| null`
`address_formatted`	`string \| null`
`address`	`object \| null`
`service_area`	`object \| null`
`phone`	`string \| null`
`additional_phones`	`string[]`	string[] fields Nested object (not expanded)
`website`	`string \| null`
`category_primary`	`string \| null`
`categories_additional`	`string[]`	string[] fields Nested object (not expanded)
`status`	`string \| null`
`description`	`string \| null`
`regular_hours`	`object \| null`
`open_info`	`object \| null`
`store_code`	`string \| null`

platform_info

ListingPlatformInfo | null

ListingPlatformInfo fields

Field	Type	Description
`place_id`	`string \| null`
`maps_url`	`string \| null`
`new_review_uri`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/listings/{listing_id}/photos

List photos linked to a managed GBP listing

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ListingPhotoItem__

Field Type Description

request_idrequired string

success true default true

datarequired

ListingPhotoItem[]

ListingPhotoItem[] fields

Field	Type	Description
`association_id`required	`string (uuid)`
`photo_id`required	`string (uuid)`
`photo_url`	`string \| null`
`is_deleted`required	`boolean`	Library/photo row soft-delete; association is still active until removed.
`photo_source`required	`string`
`format`	`string \| null`
`width`	`integer \| null`
`height`	`integer \| null`
`duration`	`number \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/listings/{listing_id}/photos

Add a library photo to a GBP listing (uploads to GBP then links)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonAddListingPhotoBody

Field	Type	Description
`photo_id`required	`string (uuid)`

Responses

200Successful Response

application/jsonSuccessResponse_ListingPhotoItem_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ListingPhotoItem`	ListingPhotoItem fields ListingPhotoItem, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/businesses/{business_id}/listings/{listing_id}/photos/{photo_id}

Remove a photo from the listing (association soft-delete only)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`photo_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/listings/{listing_id}/photos/sync

Enqueue GBP listing media import for one managed listing

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonListingPhotosSyncBody

Field	Type	Description
`sync_type`	`ListingSyncType`	default "backfill"
`max_pages_per_channel`	`integer \| null`	Max list API pages per channel (owner ``media.list`` and customer ``media.customers.list``); omit for all pages until exhausted.
`page_size`	`integer`	Items per GBP list request (capped per provider). default 100 · min 1 · max 500

Responses

200Successful Response

application/jsonSuccessResponse_ListingPhotosSyncEnqueuedData_

Field Type Description

request_idrequired string

success true default true

datarequired

ListingPhotosSyncEnqueuedData

ListingPhotosSyncEnqueuedData fields

Field	Type	Description
`gbp_location_row_id`required	`string (uuid)`
`sync_log_id`required	`string (uuid)`
`sync_type`required	`ListingSyncType`
`title`	`string \| null`
`enqueued`	`boolean`	default true

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/listings/{listing_id}/photos/sync-logs/{sync_log_id}/resume

Resume or retry a PARTIAL/FAILED GBP listing media sync log (background)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`sync_log_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonListingPhotosSyncResumeBody

Field	Type	Description
`max_pages_per_channel`	`integer \| null`	Cap GBP list pages per channel for this resume segment.
`page_size`	`integer`	Items per GBP list request. default 100 · min 1 · max 500

Responses

200Successful Response

application/jsonSuccessResponse_ListingPhotosSyncResumeEnqueuedData_

Field Type Description

request_idrequired string

success true default true

datarequired

ListingPhotosSyncResumeEnqueuedData

ListingPhotosSyncResumeEnqueuedData fields

Field	Type	Description
`gbp_location_row_id`required	`string (uuid)`
`sync_log_id`required	`string (uuid)`
`title`	`string \| null`
`enqueued`	`boolean`	default true

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/businesses/{business_id}/listings/{listing_id}/reviews

List provider reviews stored for a managed listing

Parameters

Name	In	Type	Description
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`limit`	query	`integer`	default 20
`cursor`	query	`string \| null`
`sort_by`	query	`string`	default "updated_desc"
`rating_min`	query	`integer \| null`
`rating_max`	query	`integer \| null`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ListingReviewData__

Field Type Description

request_idrequired string

success true default true

datarequired

ListingReviewData[]

ListingReviewData[] fields

Field	Type	Description
`id`required	`string (uuid)`
`business_id`required	`string (uuid)`
`provider`required	`ListingProvider`
`listing_id`required	`string (uuid)`
`provider_review_id`required	`string`
`provider_resource_name`required	`string`
`reviewer_display_name`required	`string \| null`
`reviewer_profile_photo_url`required	`string \| null`
`reviewer_is_anonymous`required	`boolean`
`rating`required	`integer \| null`
`body`required	`string \| null`
`language`required	`string \| null`
`permalink_url`required	`string \| null`
`provider_created_at`required	`string (date-time) \| null`
`provider_updated_at`required	`string (date-time) \| null`
`status`required	`ListingReviewStatus`
`review_metadata`required	`object \| null`
`is_featured`	`boolean`	default false
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/listings/{listing_id}/reviews/sync

Enqueue provider review sync for one managed listing

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonListingReviewsSyncBody

Field	Type	Description
`sync_type`	`ListingSyncType`	default "incremental"
`max_pages`	`integer \| null`	Cap provider list pages for this run (omit for natural stop).
`page_size`	`integer`	Reviews per list page. default 50 · min 1 · max 100

Responses

200Successful Response

application/jsonSuccessResponse_ListingReviewsSyncEnqueuedData_

Field Type Description

request_idrequired string

success true default true

datarequired

ListingReviewsSyncEnqueuedData

ListingReviewsSyncEnqueuedData fields

Field	Type	Description
`listing_id`required	`string (uuid)`
`sync_log_id`required	`string (uuid)`
`sync_type`required	`ListingSyncType`
`title`	`string \| null`
`enqueued`	`boolean`	default true

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/listings/{listing_id}/reviews/sync-logs/{sync_log_id}/resume

Resume or retry a PARTIAL/FAILED listing review sync log

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`listing_id`required	path	`string (uuid)`
`sync_log_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonListingReviewsSyncResumeBody

Field	Type	Description
`max_pages`	`integer \| null`
`page_size`	`integer`	default 50 · min 1 · max 100

Responses

200Successful Response

application/jsonSuccessResponse_ListingReviewsSyncResumeEnqueuedData_

Field Type Description

request_idrequired string

success true default true

datarequired

ListingReviewsSyncResumeEnqueuedData

ListingReviewsSyncResumeEnqueuedData fields

Field	Type	Description
`listing_id`required	`string (uuid)`
`sync_log_id`required	`string (uuid)`
`title`	`string \| null`
`enqueued`	`boolean`	default true

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/listings/gbp/refresh-all

Re-fetch overview + platform metadata for EVERY GBP listing (all businesses)

Fleet-wide backfill: pull each GBP listing's live overview + ``metadata`` block (``placeId`` / ``mapsUri`` / ``newReviewUri``) and persist it. One call fixes every business whose ``location_metadata`` was frozen stale at discovery time, so the conversational agent's Google-review link resolves per business (KS-866). Returns ``{total, refreshed, failed}``; per-listing failures are isolated (savepoint) and do not abort the run.

Parameters

Name	In	Type	Description
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_dict_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`object`
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.