Listings API

Listing Visibility API

Use the Listing Visibility API to find a business listing, start a visibility scan, check status, and read a report that covers listing confidence, search presence, AI readiness, competitors, citations, and recommended next steps.

Give these docs to your AI agent

Copy or download a clean markdown version of the Listing Visibility API docs.

You are viewing the Listing Visibility API docs. For the main Ceyo platform API, see Main Ceyo Platform API. To try the public tool, see AI-Ready Business Listing.

Separate API surface. These endpoints use Listing Visibility API keys and live under /api/listings/v1.

Quick start

The base URL is:

https://api.ceyo.ai/api/listings/v1

Create a Listing Visibility API key in Ceyo and use it for every request.
Search for a business listing with places autocomplete and keep the returned place_id.
Create a scan with that place_id.
Poll the scan until status is succeeded or failed, then read scan.overall_score and scan.result.

Minimal flow

curl "https://api.ceyo.ai/api/listings/v1/places/autocomplete?q=Black%20Olive%20Amsterdam" \
  -H "X-Api-Key: ceyo_lva_..."

curl -X POST "https://api.ceyo.ai/api/listings/v1/visibility_scans" \
  -H "X-Api-Key: ceyo_lva_..." \
  -H "Content-Type: application/json" \
  -d '{"place_id":"ChIJ..."}'

curl "https://api.ceyo.ai/api/listings/v1/visibility_scans/123" \
  -H "X-Api-Key: ceyo_lva_..."

Authentication

Every request must include a Listing Visibility API key. Send the key in the X-Api-Key header.

Header	Example
`X-Api-Key`	`X-Api-Key: ceyo_lva_...`

Use server-side only. Listing Visibility API keys should stay on your server. Use publishable widget keys for the embeddable browser widget.

Scan lifecycle

Status	Meaning
`pending`	Scan row was created and background work is queued.
`running`	Ceyo is collecting listing, search, citation, competitor, and AI visibility signals.
`succeeded`	The report is complete. Read `scan.overall_score` and `scan.result`.
`failed`	The scan could not be completed. Check `scan.error_code` when present.

Most integrations create a scan, check GET /visibility_scans/:id until the scan reaches a terminal status, then read scan.overall_score and the report sections. Scans stuck in pending or running are automatically marked failed after the server timeout window.

Errors

Errors return JSON with an error message. Service-level validation errors include errors.error_code; auth/gate errors may return top-level error_code.

{
  "error": "place_id is required",
  "errors": {
    "error_code": "place_id_required"
  }
}

Error code	Meaning
`billing_inactive`	Billing is inactive for the workspace.
`place_id_required`	A scan create request did not include place_id.
`invalid_place_id`	The supplied place_id could not be resolved to a business listing.
`monthly_listing_visibility_scans_limit_reached`	The monthly scan allowance has been reached.
`rate_limited`	Too many requests. Check Retry-After before trying again.
`not_found`	The requested scan does not exist in this workspace.
`email_invalid`	Lead capture email is not valid.

Endpoints

GET/places/autocomplete

Search for business listings and return place candidates. Use the returned place_id to create a scan.

Query parameters

Name	Type	Required	Description
`q`	`string`	Yes	Search query. Must be at least 2 characters.
`limit`	`integer`	No	Maximum candidates to return. Defaults to `5`, maximum `10`.

Example request

curl "https://api.ceyo.ai/api/listings/v1/places/autocomplete?q=Black%20Olive%20Amsterdam&limit=5" \
  -H "X-Api-Key: ceyo_lva_..."

Response fields

Field	Type	Description
`places[]`	`object[]`	Matching business listing candidates.
`places[].place_id`	`string`	Stable listing identifier. Pass this to scan creation as place_id.
`places[].name`	`string`	Business or place display name.
`places[].formatted_address`	`string \| null`	Formatted address when available.
`places[].primary_type_display_name`	`string \| null`	Human-readable place category.
`places[].rating`	`number \| null`	Listing rating when available.
`places[].review_count`	`integer \| null`	Listing review count when available.
`places[].types`	`string[] \| null`	Listing category/type tags when available.

POST/visibility_scans

Create a Listing Visibility scan from a place_id. The response omits the full result while background work starts.

Body parameters

Name	Type	Required	Description
`place_id`	`string`	Yes	Listing identifier from places autocomplete.

Example request

curl -X POST "https://api.ceyo.ai/api/listings/v1/visibility_scans" \
  -H "X-Api-Key: ceyo_lva_..." \
  -H "Content-Type: application/json" \
  -d '{"place_id":"ChIJ..."}'

Response fields

Field	Type	Description
`scan.id`	`integer`	Listing Visibility scan ID.
`scan.place_id`	`string`	Listing identifier used for this scan.
`scan.name`	`string`	Resolved business name.
`scan.address`	`string`	Resolved business address.
`scan.website_url`	`string \| null`	Resolved website URL when available.
`scan.status`	`string`	One of `pending`, `running`, `succeeded`, or `failed`.
`scan.overall_score`	`integer \| null`	Weighted overall Listing Visibility score from 0 to 100. This is the same score shown in the embeddable widget and internal workspace UI.
`scan.progress.current`	`integer \| null`	Number of completed progress steps.
`scan.progress.total`	`integer \| null`	Total progress steps for the scan.
`scan.progress.label`	`string \| null`	Human-readable progress label.
`scan.completed_checks`	`string[]`	Completed scan modules.
`scan.queued_checks`	`string[]`	Scan modules queued for this workspace.
`scan.lead_email`	`string \| null`	Captured lead email when submitted through the lead endpoint.
`scan.lead_captured_at`	`string \| null`	Lead capture timestamp.
`scan.started_at`	`string \| null`	Scan start timestamp.
`scan.finished_at`	`string \| null`	Scan completion timestamp.
`scan.created_at`	`string`	Creation timestamp.
`scan.updated_at`	`string`	Last update timestamp.

GET/visibility_scans

List scans for the authenticated Listing Visibility workspace. Results are returned newest first and include result data.

Query parameters

Name	Type	Required	Description
`page`	`integer`	No	Page number. Defaults to `1`.
`per_page`	`integer`	No	Items per page. Defaults to `50`, maximum `50`.
`status`	`string`	No	Filter by `pending`, `running`, `succeeded`, or `failed`.
`from`	`string`	No	Inclusive created_at lower bound. Any parseable ISO timestamp is accepted.
`to`	`string`	No	Inclusive created_at upper bound. Any parseable ISO timestamp is accepted.

Example request

curl "https://api.ceyo.ai/api/listings/v1/visibility_scans?status=succeeded&page=1&per_page=25" \
  -H "X-Api-Key: ceyo_lva_..."

Response fields

Field	Type	Description
`scans`	`object[]`	Paginated scans.
`pagination.page`	`integer`	Current page.
`pagination.per_page`	`integer`	Items per page.
`pagination.total`	`integer`	Total matching scans.
`pagination.total_pages`	`integer`	Total pages.

Field	Type	Description
`scans[].id`	`integer`	Listing Visibility scan ID.
`scans[].place_id`	`string`	Listing identifier used for this scan.
`scans[].name`	`string`	Resolved business name.
`scans[].address`	`string`	Resolved business address.
`scans[].website_url`	`string \| null`	Resolved website URL when available.
`scans[].status`	`string`	One of `pending`, `running`, `succeeded`, or `failed`.
`scans[].overall_score`	`integer \| null`	Weighted overall Listing Visibility score from 0 to 100. This is the same score shown in the embeddable widget and internal workspace UI.
`scans[].progress.current`	`integer \| null`	Number of completed progress steps.
`scans[].progress.total`	`integer \| null`	Total progress steps for the scan.
`scans[].progress.label`	`string \| null`	Human-readable progress label.
`scans[].completed_checks`	`string[]`	Completed scan modules.
`scans[].queued_checks`	`string[]`	Scan modules queued for this workspace.
`scans[].lead_email`	`string \| null`	Captured lead email when submitted through the lead endpoint.
`scans[].lead_captured_at`	`string \| null`	Lead capture timestamp.
`scans[].started_at`	`string \| null`	Scan start timestamp.
`scans[].finished_at`	`string \| null`	Scan completion timestamp.
`scans[].created_at`	`string`	Creation timestamp.
`scans[].updated_at`	`string`	Last update timestamp.
`scans[].result`	`object`	Included on list/show responses. Omitted from create responses. Contains report sections such as `business_identity_confidence`, `ai_visibility_readiness`, `search_presence_check`, `competitor_snapshot`, and `quick_recommended_actions`.

GET/visibility_scans/:id

Fetch one scan by ID. Use this endpoint to retrieve scan status and the final report.

Path parameters

Name	Type	Required	Description
`id`	`integer`	Yes	Listing Visibility scan ID.

Example request

curl "https://api.ceyo.ai/api/listings/v1/visibility_scans/123" \
  -H "X-Api-Key: ceyo_lva_..."

Response fields

Field	Type	Description
`scan.id`	`integer`	Listing Visibility scan ID.
`scan.place_id`	`string`	Listing identifier used for this scan.
`scan.name`	`string`	Resolved business name.
`scan.address`	`string`	Resolved business address.
`scan.website_url`	`string \| null`	Resolved website URL when available.
`scan.status`	`string`	One of `pending`, `running`, `succeeded`, or `failed`.
`scan.overall_score`	`integer \| null`	Weighted overall Listing Visibility score from 0 to 100. This is the same score shown in the embeddable widget and internal workspace UI.
`scan.progress.current`	`integer \| null`	Number of completed progress steps.
`scan.progress.total`	`integer \| null`	Total progress steps for the scan.
`scan.progress.label`	`string \| null`	Human-readable progress label.
`scan.completed_checks`	`string[]`	Completed scan modules.
`scan.queued_checks`	`string[]`	Scan modules queued for this workspace.
`scan.lead_email`	`string \| null`	Captured lead email when submitted through the lead endpoint.
`scan.lead_captured_at`	`string \| null`	Lead capture timestamp.
`scan.started_at`	`string \| null`	Scan start timestamp.
`scan.finished_at`	`string \| null`	Scan completion timestamp.
`scan.created_at`	`string`	Creation timestamp.
`scan.updated_at`	`string`	Last update timestamp.
`scan.result`	`object`	Included on list/show responses. Omitted from create responses. Contains report sections such as `business_identity_confidence`, `ai_visibility_readiness`, `search_presence_check`, `competitor_snapshot`, and `quick_recommended_actions`.

PATCH/visibility_scans/:id/lead

Attach a lead email to a scan. This is optional for public API integrations; it exists so API customers can store lead capture alongside scan records when useful.

Path parameters

Name	Type	Required	Description
`id`	`integer`	Yes	Listing Visibility scan ID.

Body parameters

Name	Type	Required	Description
`email`	`string`	Yes	Lead email address.

Example request

curl -X PATCH "https://api.ceyo.ai/api/listings/v1/visibility_scans/123/lead" \
  -H "X-Api-Key: ceyo_lva_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"founder@example.com"}'

Response fields

Field	Type	Description
`scan.id`	`integer`	Listing Visibility scan ID.
`scan.place_id`	`string`	Listing identifier used for this scan.
`scan.name`	`string`	Resolved business name.
`scan.address`	`string`	Resolved business address.
`scan.website_url`	`string \| null`	Resolved website URL when available.
`scan.status`	`string`	One of `pending`, `running`, `succeeded`, or `failed`.
`scan.overall_score`	`integer \| null`	Weighted overall Listing Visibility score from 0 to 100. This is the same score shown in the embeddable widget and internal workspace UI.
`scan.progress.current`	`integer \| null`	Number of completed progress steps.
`scan.progress.total`	`integer \| null`	Total progress steps for the scan.
`scan.progress.label`	`string \| null`	Human-readable progress label.
`scan.completed_checks`	`string[]`	Completed scan modules.
`scan.queued_checks`	`string[]`	Scan modules queued for this workspace.
`scan.lead_email`	`string \| null`	Captured lead email when submitted through the lead endpoint.
`scan.lead_captured_at`	`string \| null`	Lead capture timestamp.
`scan.started_at`	`string \| null`	Scan start timestamp.
`scan.finished_at`	`string \| null`	Scan completion timestamp.
`scan.created_at`	`string`	Creation timestamp.
`scan.updated_at`	`string`	Last update timestamp.
`scan.result`	`object`	Included on list/show responses. Omitted from create responses. Contains report sections such as `business_identity_confidence`, `ai_visibility_readiness`, `search_presence_check`, `competitor_snapshot`, and `quick_recommended_actions`.

Scan object

Field	Type	Description
`scan.id`	`integer`	Listing Visibility scan ID.
`scan.place_id`	`string`	Listing identifier used for this scan.
`scan.name`	`string`	Resolved business name.
`scan.address`	`string`	Resolved business address.
`scan.website_url`	`string \| null`	Resolved website URL when available.
`scan.status`	`string`	One of `pending`, `running`, `succeeded`, or `failed`.
`scan.overall_score`	`integer \| null`	Weighted overall Listing Visibility score from 0 to 100. This is the same score shown in the embeddable widget and internal workspace UI.
`scan.progress.current`	`integer \| null`	Number of completed progress steps.
`scan.progress.total`	`integer \| null`	Total progress steps for the scan.
`scan.progress.label`	`string \| null`	Human-readable progress label.
`scan.completed_checks`	`string[]`	Completed scan modules.
`scan.queued_checks`	`string[]`	Scan modules queued for this workspace.
`scan.lead_email`	`string \| null`	Captured lead email when submitted through the lead endpoint.
`scan.lead_captured_at`	`string \| null`	Lead capture timestamp.
`scan.started_at`	`string \| null`	Scan start timestamp.
`scan.finished_at`	`string \| null`	Scan completion timestamp.
`scan.created_at`	`string`	Creation timestamp.
`scan.updated_at`	`string`	Last update timestamp.
`scan.result`	`object`	Included on list/show responses. Omitted from create responses. Contains report sections such as `business_identity_confidence`, `ai_visibility_readiness`, `search_presence_check`, `competitor_snapshot`, and `quick_recommended_actions`.

Result sections

scan.result is an object keyed by section. Sections may be absent when a check is not enabled or could not complete.

business_identity_confidence

Business identity, listing details, and consistency signals.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`checks[]`	`object[]`	Individual checks.
`checks[].key`	`string`	Check identifier.
`checks[].label`	`string`	Human-readable check label.
`checks[].status`	`string`	Check status.
`checks[].score`	`number \| null`	Check score when available.
`checks[].max_score`	`number \| null`	Maximum check score when available.
`checks[].message`	`string \| null`	Check explanation.
`strengths[]`	`object[]`	Positive findings.
`strengths[].key`	`string`	Strength identifier.
`strengths[].message`	`string`	Strength explanation.
`issues[]`	`object[]`	Issues found in the section.
`issues[].key`	`string`	Issue identifier.
`issues[].severity`	`string`	Issue severity.
`issues[].message`	`string`	Issue explanation.
`place`	`object`	Resolved listing details.
`place.place_id`	`string`	Listing identifier.
`place.name`	`string`	Business name.
`place.address`	`string \| null`	Business address.
`place.website_url`	`string \| null`	Business website.
`place.phone`	`string \| null`	Business phone.
`place.primary_type_display_name`	`string \| null`	Primary listing category.
`place.rating`	`number \| null`	Listing rating.
`place.review_count`	`integer \| null`	Listing review count.
`place.photo_count`	`integer \| null`	Number of listing photos found.

listing_visibility_audit

Listing completeness, review strength, photo coverage, and listing quality checks.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`checks[]`	`object[]`	Individual checks.
`checks[].key`	`string`	Check identifier.
`checks[].label`	`string`	Human-readable check label.
`checks[].status`	`string`	Check status.
`checks[].score`	`number \| null`	Check score when available.
`checks[].max_score`	`number \| null`	Maximum check score when available.
`checks[].message`	`string \| null`	Check explanation.
`strengths[]`	`object[]`	Positive findings.
`strengths[].key`	`string`	Strength identifier.
`strengths[].message`	`string`	Strength explanation.
`issues[]`	`object[]`	Issues found in the section.
`issues[].key`	`string`	Issue identifier.
`issues[].severity`	`string`	Issue severity.
`issues[].message`	`string`	Issue explanation.

ai_visibility_readiness

Signals that help answer engines understand, trust, and cite the business.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`checks[]`	`object[]`	Individual checks.
`checks[].key`	`string`	Check identifier.
`checks[].label`	`string`	Human-readable check label.
`checks[].status`	`string`	Check status.
`checks[].score`	`number \| null`	Check score when available.
`checks[].max_score`	`number \| null`	Maximum check score when available.
`checks[].message`	`string \| null`	Check explanation.
`strengths[]`	`object[]`	Positive findings.
`strengths[].key`	`string`	Strength identifier.
`strengths[].message`	`string`	Strength explanation.
`issues[]`	`object[]`	Issues found in the section.
`issues[].key`	`string`	Issue identifier.
`issues[].severity`	`string`	Issue severity.
`issues[].message`	`string`	Issue explanation.

search_presence_check

Queries and source results used to understand how the business appears in search.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`queries[]`	`object[]`	Search checks run for the business.
`queries[].query`	`string`	Search query text.
`queries[].official_site_found`	`boolean \| null`	Whether the official site was found.
`queries[].official_site_position`	`integer \| null`	Official site position when found.
`queries[].brand_result_found`	`boolean \| null`	Whether a branded result was found.
`queries[].brand_result_position`	`integer \| null`	Branded result position when found.
`queries[].top_sources[]`	`object[]`	Top sources found for the query.
`queries[].top_sources[].position`	`integer \| null`	Source position.
`queries[].top_sources[].title`	`string \| null`	Source title.
`queries[].top_sources[].domain`	`string \| null`	Source domain.
`queries[].top_sources[].url`	`string \| null`	Source URL.

citation_source_footprint

Source and citation coverage connected to the business.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`sources[]`	`object[]`	Sources checked for the business.
`sources[].type`	`string \| null`	Source category.
`sources[].label`	`string \| null`	Source label.
`sources[].found`	`boolean \| null`	Whether the source was found.
`sources[].url`	`string \| null`	Source URL.
`sources[].domain`	`string \| null`	Source domain.

quick_homepage_audit

Homepage availability and business-signal checks.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`url`	`string \| null`	Submitted or resolved website URL.
`final_url`	`string \| null`	Final URL after redirects.
`http_status`	`integer \| null`	HTTP status when available.
`checks[]`	`object[]`	Individual homepage checks.
`checks[].key`	`string`	Check identifier.
`checks[].label`	`string`	Human-readable check label.
`checks[].status`	`string`	Check status.
`checks[].score`	`number \| null`	Check score when available.
`checks[].max_score`	`number \| null`	Maximum check score when available.
`checks[].message`	`string \| null`	Check explanation.
`strengths[]`	`object[]`	Positive findings.
`strengths[].key`	`string`	Strength identifier.
`strengths[].message`	`string`	Strength explanation.
`issues[]`	`object[]`	Issues found in the section.
`issues[].key`	`string`	Issue identifier.
`issues[].severity`	`string`	Issue severity.
`issues[].message`	`string`	Issue explanation.

competitor_snapshot

Nearby competitor signals and comparison metrics.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`competitors[]`	`object[]`	Competitor listings returned for comparison.
`competitors[].place_id`	`string \| null`	Competitor listing identifier.
`competitors[].name`	`string \| null`	Competitor name.
`competitors[].address`	`string \| null`	Competitor address.
`competitors[].website_url`	`string \| null`	Competitor website.
`competitors[].primary_type_display_name`	`string \| null`	Competitor category.
`competitors[].rating`	`number \| null`	Competitor rating.
`competitors[].review_count`	`integer \| null`	Competitor review count.
`competitors[].photo_count`	`integer \| null`	Competitor photo count.
`competitors[].completeness_score`	`number \| null`	Listing completeness score.
`competitors[].same_category`	`boolean \| null`	Whether the competitor is in the same category.
`comparison.subject.rating`	`number \| null`	Subject business rating.
`comparison.subject.review_count`	`integer \| null`	Subject business review count.
`comparison.subject.completeness_score`	`number \| null`	Subject business completeness score.
`comparison.competitor_medians.rating`	`number \| null`	Median competitor rating.
`comparison.competitor_medians.review_count`	`integer \| null`	Median competitor review count.
`comparison.competitor_medians.completeness_score`	`number \| null`	Median competitor completeness score.

quick_ai_visibility_probe

Example answer-engine prompts and whether the business was mentioned or cited.

Field	Type	Description
`score`	`number`	Section score from 0 to 100.
`grade`	`string`	Letter-style grade for the section.
`summary`	`string`	Short section summary.
`prompts[]`	`object[]`	Prompt checks.
`prompts[].prompt`	`string`	Prompt text.
`prompts[].answer_preview`	`string \| null`	Short answer preview.
`prompts[].business_mentioned`	`boolean \| null`	Whether the business was mentioned.
`prompts[].mention_position`	`integer \| null`	Mention position when available.
`prompts[].official_citation_found`	`boolean \| null`	Whether an official citation was found.
`prompts[].official_citation.title`	`string \| null`	Official citation title.
`prompts[].official_citation.url`	`string \| null`	Official citation URL.
`prompts[].official_citation.domain`	`string \| null`	Official citation domain.
`prompts[].citations[]`	`object[]`	Citations returned for the prompt.
`prompts[].citations[].title`	`string \| null`	Citation title.
`prompts[].citations[].url`	`string \| null`	Citation URL.
`prompts[].citations[].domain`	`string \| null`	Citation domain.
`prompts[].fan_out_queries`	`string[] \| null`	Related queries used for the prompt.

quick_recommended_actions

Prioritized actions for improving the business listing and related web presence.

Field	Type	Description
`summary`	`string`	Short summary of the recommendations.
`actions[]`	`object[]`	Recommended actions.
`actions[].id`	`string \| integer`	Action identifier.
`actions[].priority`	`string \| integer`	Action priority.
`actions[].category`	`string`	Action category.
`actions[].title`	`string`	Action title.
`actions[].why`	`string \| null`	Why the action matters.
`actions[].how_to_fix`	`string \| null`	How to address it.