Signal API
Locations as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Locations

Provision and manage locations in the selected project.

Provisioning is synchronous and separate from onboarding. A successful create request returns the complete resource with HTTP 201. Set start: true on a standard project or location to start onboarding immediately after provisioning. Location container projects require start: false. Onboarding creates 80% of the package prompt limit by default. Set use_full_prompt_limit: true to create 100%; both modes are capped at 100 prompts.
Authentication and scopeSend Authorization: Bearer ceyo_platform_... on every request. The API key selects the workspace, so paths never require a workspace identifier.
Packages and project modesA standard project selects an active project package with package_id. Every location selects an active location package. A locations_only project is a container for locations, has no project package, and is not itself a tracking scope. Package assignments cannot be changed through resource updates.
Model availabilityThe selected country must support every visibility model in the package. This is validated on create, country updates, and each bulk item. Unsupported combinations return 422 unsupported_model_country_combination with the unsupported model keys in the error details.
Pagination, filters, and orderingList endpoints use 1-based page and per_page, return pagination metadata, and return an empty array when the page is beyond the result set. Filters combine with AND. Search is trimmed, case-insensitive, and limited to 200 characters. Sorts are stable and use resource ID as the final ascending tie-breaker.
GET
/projects/{project_id}/locations

Returns locations in a project. Filters combine with AND and the selected sort is deterministic.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
Parameters

Query parameters

qstring

Case-insensitive search across name, external_id, formatted address, city, state, postal code, country, phone, email, folder, and tag. Maximum: 200 characters.

Optional
folderstring

Match one folder, case-insensitively.

Optional
tagstring

Match one tag, case-insensitively.

Optional
statusactive | inactive | archived

Return locations in one lifecycle status.

Optional
country_codeISO 3166-1 alpha-2 string

Match the location’s explicit country code.

Optional
sortcreated_at | updated_at | name

Field used for ordering.

OptionalDefault: created_at
directionasc | desc

Sort direction.

OptionalDefault: desc
pageinteger

The 1-based page number.

OptionalDefault: 1
per_pageinteger

Number of records per page, from 1 through 100. Values outside this range return 422.

OptionalDefault: 25
Response

Response envelope

locations:Location[]pagination:Pagination
locationsLocation[]

Matching locations in the requested deterministic sort order.

paginationPagination

Pagination metadata.

Object

Location

iduuid

Location identifier.

project_iduuid

Identifier of the containing project.

external_idstring | null

Case-sensitive identifier supplied by the partner.

namestring

Location display name.

folderstring | null

Optional organization folder.

tagsstring[]

Up to three organization tags.

descriptionstring | null

Location description.

websitestring | null

Normalized HTTP or HTTPS location website.

brand_aliasesstring[]

Normalized alternative names for the location brand.

languageISO 639-1 string | null

Location content language, or null when not overridden.

action_languageISO 639-1 string | null

Location action language, or null when not overridden.

effective_action_languageISO 639-1 string

Final action language after applying inheritance.

include_parent_brandboolean | null

Whether the parent project brand is included.

competitorsCompetitor[]

Active tracked competitors. Compatible tracked projection of the dedicated Competitors contract; suggested and dismissed records are excluded.

phonestring | null

Partner-supplied contact phone number.

emailstring | null

Normalized contact email address.

metadataobject

Partner-owned JSON metadata. Keys and values are returned without interpretation.

local_contextobject

Partner-supplied local facts used to contextualize processing.

focusglobal | country | region | city

Configured geographic targeting focus.

google_place_idstring | null

Google place identifier.

google_place_sourceprovided | discovered | null

Whether the Google place was supplied by the customer or matched during onboarding.

google_place_namestring | null

Business name associated with the Google place.

google_maps_urlstring | null

Google Maps URL for the location.

google_place_resolutionobject

Place resolution with state (resolved, ambiguous, unresolved, mismatch, or no_listing), source (customer or automatic), customer confirmation time, and ambiguous candidates containing only place_id, name, address, and google_maps_url.

formatted_addressstring | null

Formatted physical address.

address_line_2string | null

Optional second address line.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

postal_codestring | null

Normalized postal code.

countrystring | null

Normalized country name.

country_codestring | null

Explicit uppercase ISO 3166-1 alpha-2 country code, or null when not configured. Locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90.

longitudenumber | null

Longitude from -180 through 180.

statusactive | inactive | archived

Current location lifecycle status.

packagePackageReference

Assigned location package.

created_atdatetime

Location creation time in ISO 8601 format.

updated_atdatetime

Most recent location update time in ISO 8601 format.

Object

PackageReference

iduuid

Assigned package identifier.

namestring

Assigned package name.

Object

Competitor

iduuid

Competitor identifier.

kindcompetitor

Entity role. Always competitor in this projection.

namestring

Competitor display name.

domainstring

Normalized hostname without a scheme, path, query, leading www, or trailing dot. Required for tracked competitors.

aliasesstring[]

Additional names recognized for the competitor.

statusactive

Tracked competitors always participate in current processing.

competitor_statetracked

Management lifecycle state. This projection contains tracked competitors only.

created_atdatetime

Competitor creation time in ISO 8601 format.

updated_atdatetime

Most recent competitor update time in ISO 8601 format.

Object

Metadata and local context object

additional propertiesJSON value

Arbitrary partner-owned keys with string, number, boolean, null, object, or array values.

maximum size16 KB

Limit measured after JSON serialization.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Number of records requested per page.

totalinteger

Total records matching the request.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations?q=amsterdam&status=active&sort=name&direction=asc&page=1&per_page=25' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "locations": [
    {
      "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
      "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
      "external_id": "partner-location-amsterdam",
      "name": "Acme Amsterdam",
      "folder": "Europe",
      "tags": [
        "Flagship",
        "Airport"
      ],
      "description": "Acme flagship store in Amsterdam.",
      "website": "https://acme.example/amsterdam",
      "brand_aliases": [
        "acme amsterdam"
      ],
      "language": "en",
      "action_language": "en",
      "effective_action_language": "en",
      "include_parent_brand": true,
      "competitors": [
        {
          "id": "63ec8dad-c12f-43c8-89e4-06eb629d0977",
          "kind": "competitor",
          "name": "Example Rival",
          "domain": "example-rival.com",
          "aliases": [
            "rival"
          ],
          "status": "active",
          "competitor_state": "tracked",
          "created_at": "2026-07-02T11:20:00Z",
          "updated_at": "2026-07-30T09:10:00Z"
        }
      ],
      "phone": "+31 20 555 0100",
      "email": "amsterdam@acme.example",
      "metadata": {
        "partner_region_id": "nl-west"
      },
      "local_context": {
        "neighborhood": "Centrum",
        "service_area": "Amsterdam"
      },
      "focus": "city",
      "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "google_place_source": "provided",
      "google_place_name": "Acme Amsterdam",
      "google_maps_url": "https://maps.google.com/?cid=123456789",
      "google_place_resolution": {
        "state": "resolved",
        "source": "customer",
        "confirmed_at": "2026-07-31T08:10:00Z",
        "candidates": []
      },
      "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
      "address_line_2": null,
      "city": "Amsterdam",
      "state": "North Holland",
      "postal_code": "1012 JS",
      "country": "Netherlands",
      "country_code": null,
      "latitude": 52.3728,
      "longitude": 4.8936,
      "status": "active",
      "package": {
        "id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
        "name": "Local Growth Weekly"
      },
      "created_at": "2026-07-31T08:10:00Z",
      "updated_at": "2026-07-31T08:10:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

POST
/projects/{project_id}/locations

Synchronously provisions a location under a project and returns it. Optionally starts onboarding after creation.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
Request

Request body

namestring

Required location name. Maximum: 200 characters.

package_iduuid

Required active location package identifier from the same workspace.

external_idstring | null

Optional partner identifier, unique among locations in this project.

descriptionstring | null

Optional description. Maximum: 5,000 characters.

websitestring | null

Valid HTTP or HTTPS URL; maximum 2,048 characters.

brand_aliasesstring[]

Up to 10 alternative names, each at most 200 characters. Values are normalized and deduplicated.

languageISO 639-1 string | null

Optional lowercase content-language override. If omitted, Signal infers it from a clear country_code; null uses the project location default, then en.

action_languageISO 639-1 string | null

Optional lowercase action-language override. Null uses the project location default, then the effective content language.

include_parent_brandboolean | null

Optional parent-brand override. Null uses the project location default.

phonestring | null

Contact phone number; maximum 50 characters.

emailstring | null

Valid contact email; maximum 320 characters.

metadataobject

Partner-owned JSON object, maximum serialized size 16 KB. Defaults to {}.

local_contextobject

Local context JSON object, maximum serialized size 16 KB. Defaults to {}.

focusglobal | country | region | city

Geographic targeting focus. Defaults to city.

google_place_idstring | null

Google place identifier, unique in the project. When supplied, Ceyo validates it and resolves canonical place details. Maximum: 500 characters.

google_place_namestring | null

Google place business name. Maximum: 200 characters.

google_maps_urlstring | null

Google Maps URL. Maximum: 2,048 characters.

formatted_addressstring | null

Formatted physical address. Maximum: 500 characters.

address_line_2string | null

Optional suite, unit, or floor. Preserved separately from the canonical address. Maximum: 200 characters.

citystring | null

City. Maximum: 200 characters.

statestring | null

Region or state. Maximum: 200 characters.

postal_codestring | null

Postal code. Maximum: 200 characters.

countrystring | null

Country name. Maximum: 200 characters.

country_codestring | null

ISO 3166-1 alpha-2 code. Null leaves the location country code unset; locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90. Latitude and longitude must be supplied together.

longitudenumber | null

Longitude from -180 through 180. Latitude and longitude must be supplied together.

folderstring | null

Optional organization folder. Maximum: 30 characters.

tagsstring[]

Up to three organization tags. Each tag is 1–25 characters.

startboolean

When true, starts onboarding after provisioning. Supply either google_place_id or both city and country_code. Defaults to false.

use_full_prompt_limitboolean

When start is true, creates 100% instead of 80% of the package prompt limit during onboarding. Both modes are capped at 100 prompts. Defaults to false.

onboarding_topicsOnboardingTopics | null

Optional topic choices for automatic onboarding. Used only when start is true.

Object

OnboardingTopics

topicsstring[]

Up to five topic names. Each must contain 1–120 characters and be unique and brand-safe.

fill_remainingboolean

When true, Signal suggests topics for the remaining slots. Defaults to true; false requires at least one supplied topic.

Location packagepackage_id must identify an active location package in the same workspace. The location can provide its own country_code. If omitted, the location country code remains unset; it does not inherit the project country.
Automatic or manual place dataWith google_place_id, Ceyo validates the place and fills canonical place details. Without it, provide your own location data. For start: true, city and country_code are enough; onboarding then tries to find a high-confidence Google match in the background.
Best-effort listing matchCustomer-supplied fields are kept when a match is found. If no clear match exists, onboarding continues and listing analysis is skipped.
Topics and prompt countWith start: true, optionally supply up to five topic names in onboarding_topics. Set fill_remaining: false to use only the supplied topics. Onboarding creates 80% of the package prompt limit by default. Set use_full_prompt_limit: true to create 100%. The maximum is always 100 prompts.
Response

Response envelope

location:Locationonboarding_operation:OnboardingOperation | null
locationLocation

The provisioned location.

onboarding_operationOnboardingOperation | null

Polling operation when start is true; null when onboarding was not requested.

Object

Location

iduuid

Location identifier.

project_iduuid

Identifier of the containing project.

external_idstring | null

Case-sensitive identifier supplied by the partner.

namestring

Location display name.

folderstring | null

Optional organization folder.

tagsstring[]

Up to three organization tags.

descriptionstring | null

Location description.

websitestring | null

Normalized HTTP or HTTPS location website.

brand_aliasesstring[]

Normalized alternative names for the location brand.

languageISO 639-1 string | null

Location content language, or null when not overridden.

action_languageISO 639-1 string | null

Location action language, or null when not overridden.

effective_action_languageISO 639-1 string

Final action language after applying inheritance.

include_parent_brandboolean | null

Whether the parent project brand is included.

competitorsCompetitor[]

Active tracked competitors. Compatible tracked projection of the dedicated Competitors contract; suggested and dismissed records are excluded.

phonestring | null

Partner-supplied contact phone number.

emailstring | null

Normalized contact email address.

metadataobject

Partner-owned JSON metadata. Keys and values are returned without interpretation.

local_contextobject

Partner-supplied local facts used to contextualize processing.

focusglobal | country | region | city

Configured geographic targeting focus.

google_place_idstring | null

Google place identifier.

google_place_sourceprovided | discovered | null

Whether the Google place was supplied by the customer or matched during onboarding.

google_place_namestring | null

Business name associated with the Google place.

google_maps_urlstring | null

Google Maps URL for the location.

google_place_resolutionobject

Place resolution with state (resolved, ambiguous, unresolved, mismatch, or no_listing), source (customer or automatic), customer confirmation time, and ambiguous candidates containing only place_id, name, address, and google_maps_url.

formatted_addressstring | null

Formatted physical address.

address_line_2string | null

Optional second address line.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

postal_codestring | null

Normalized postal code.

countrystring | null

Normalized country name.

country_codestring | null

Explicit uppercase ISO 3166-1 alpha-2 country code, or null when not configured. Locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90.

longitudenumber | null

Longitude from -180 through 180.

statusactive | inactive | archived

Current location lifecycle status.

packagePackageReference

Assigned location package.

created_atdatetime

Location creation time in ISO 8601 format.

updated_atdatetime

Most recent location update time in ISO 8601 format.

Object

PackageReference

iduuid

Assigned package identifier.

namestring

Assigned package name.

Object

Competitor

iduuid

Competitor identifier.

kindcompetitor

Entity role. Always competitor in this projection.

namestring

Competitor display name.

domainstring

Normalized hostname without a scheme, path, query, leading www, or trailing dot. Required for tracked competitors.

aliasesstring[]

Additional names recognized for the competitor.

statusactive

Tracked competitors always participate in current processing.

competitor_statetracked

Management lifecycle state. This projection contains tracked competitors only.

created_atdatetime

Competitor creation time in ISO 8601 format.

updated_atdatetime

Most recent competitor update time in ISO 8601 format.

Object

Metadata and local context object

additional propertiesJSON value

Arbitrary partner-owned keys with string, number, boolean, null, object, or array values.

maximum size16 KB

Limit measured after JSON serialization.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Acme Amsterdam",
  "external_id": "partner-location-amsterdam",
  "package_id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
  "website": "https://acme.example/amsterdam",
  "language": "nl",
  "action_language": "en",
  "include_parent_brand": true,
  "phone": "+31 20 555 0100",
  "email": "amsterdam@acme.example",
  "metadata": {
    "partner_region_id": "nl-west"
  },
  "local_context": {
    "neighborhood": "Centrum",
    "service_area": "Amsterdam"
  },
  "focus": "city",
  "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "address_line_2": "Suite 4",
  "start": true,
  "use_full_prompt_limit": true,
  "onboarding_topics": {
    "topics": [
      "Emergency dental care",
      "Cosmetic dentistry"
    ],
    "fill_remaining": true
  }
}'
Example responseJSON
HTTP/1.1 201 Created

{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam",
    "folder": "Europe",
    "tags": [
      "Flagship",
      "Airport"
    ],
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "action_language": "en",
    "effective_action_language": "en",
    "include_parent_brand": true,
    "competitors": [
      {
        "id": "63ec8dad-c12f-43c8-89e4-06eb629d0977",
        "kind": "competitor",
        "name": "Example Rival",
        "domain": "example-rival.com",
        "aliases": [
          "rival"
        ],
        "status": "active",
        "competitor_state": "tracked",
        "created_at": "2026-07-02T11:20:00Z",
        "updated_at": "2026-07-30T09:10:00Z"
      }
    ],
    "phone": "+31 20 555 0100",
    "email": "amsterdam@acme.example",
    "metadata": {
      "partner_region_id": "nl-west"
    },
    "local_context": {
      "neighborhood": "Centrum",
      "service_area": "Amsterdam"
    },
    "focus": "city",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "google_place_source": "provided",
    "google_place_name": "Acme Amsterdam",
    "google_maps_url": "https://maps.google.com/?cid=123456789",
    "google_place_resolution": {
      "state": "resolved",
      "source": "customer",
      "confirmed_at": "2026-07-31T08:10:00Z",
      "candidates": []
    },
    "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
    "address_line_2": "Suite 4",
    "city": "Amsterdam",
    "state": "North Holland",
    "postal_code": "1012 JS",
    "country": "Netherlands",
    "country_code": null,
    "latitude": 52.3728,
    "longitude": 4.8936,
    "status": "active",
    "package": {
      "id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "name": "Local Growth Weekly"
    },
    "created_at": "2026-07-31T08:10:00Z",
    "updated_at": "2026-07-31T08:10:00Z"
  },
  "onboarding_operation": {
    "id": "1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "status": "queued",
    "resource_type": "location",
    "resource_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "progress": {
      "completed": 0,
      "total": 6
    },
    "message": "Onboarding is queued.",
    "steps": [
      {
        "key": "enrichment",
        "status": "pending"
      },
      {
        "key": "topics",
        "status": "pending"
      },
      {
        "key": "prompts",
        "status": "pending"
      },
      {
        "key": "competitors",
        "status": "pending"
      },
      {
        "key": "visibility",
        "status": "pending"
      },
      {
        "key": "diagnosis",
        "status": "pending"
      }
    ],
    "status_url": "/v1/onboarding-operations/1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "created_at": "2026-08-04T15:00:00Z",
    "updated_at": "2026-08-04T15:00:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

409conflict

The external ID is already in use or the resource cannot accept this operation in its current state.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

503place_details_unavailable

A supplied Google Place ID could not be resolved because place details are temporarily unavailable.

POST
/projects/{project_id}/locations/bulk

Accepts up to 100 location create records and provisions them asynchronously under one project.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
Request

Request body

locationsLocationCreate[]

Between 1 and 100 records using the same fields and validation as Create location.

Idempotency requiredSend a unique Idempotency-Key header. Repeating the same request returns the existing operation. Reusing the key with a different body returns 409.
Independent onboardingSet start separately on each record. Successful records with start: true enqueue location onboarding; one failed record does not roll back the others. Each started record may set use_full_prompt_limit: true and onboarding_topics.
Response

Response envelope

bulk_operation:BulkOperation

Accepted operation summary with an ID and status_url for polling.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/bulk' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Idempotency-Key: provision-2026-08-04-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "locations": [
    {
      "name": "Acme Amsterdam",
      "external_id": "partner-location-amsterdam",
      "package_id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "website": "https://acme.example/amsterdam",
      "language": "nl",
      "action_language": "en",
      "include_parent_brand": true,
      "phone": "+31 20 555 0100",
      "email": "amsterdam@acme.example",
      "metadata": {
        "partner_region_id": "nl-west"
      },
      "local_context": {
        "neighborhood": "Centrum",
        "service_area": "Amsterdam"
      },
      "focus": "city",
      "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "address_line_2": "Suite 4",
      "start": true,
      "use_full_prompt_limit": true,
      "onboarding_topics": {
        "topics": [
          "Emergency dental care",
          "Cosmetic dentistry"
        ],
        "fill_remaining": true
      }
    },
    {
      "name": "Acme Rotterdam",
      "external_id": "partner-location-rotterdam",
      "package_id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "website": "https://acme.example/amsterdam",
      "language": "nl",
      "action_language": "en",
      "include_parent_brand": true,
      "phone": "+31 20 555 0100",
      "email": "amsterdam@acme.example",
      "metadata": {
        "partner_region_id": "nl-west"
      },
      "local_context": {
        "neighborhood": "Centrum",
        "service_area": "Amsterdam"
      },
      "focus": "city",
      "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "address_line_2": "Suite 4",
      "start": true,
      "use_full_prompt_limit": true,
      "onboarding_topics": {
        "topics": [
          "Emergency dental care",
          "Cosmetic dentistry"
        ],
        "fill_remaining": true
      },
      "city": "Rotterdam"
    }
  ]
}'
Example responseJSON
HTTP/1.1 202 Accepted

{
  "bulk_operation": {
    "id": "f9bc15cc-e9c9-4e93-a93e-b713c92c7315",
    "type": "locations",
    "status": "pending",
    "parent_project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "total": 2,
    "pending": 2,
    "succeeded": 0,
    "failed": 0,
    "created_at": "2026-08-04T15:00:00Z",
    "started_at": null,
    "completed_at": null,
    "status_url": "/v1/bulk-operations/f9bc15cc-e9c9-4e93-a93e-b713c92c7315"
  }
}

Poll the shared Get bulk operation endpoint for per-record results.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

409conflict

The external ID is already in use or the resource cannot accept this operation in its current state.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/locations/{location_id}

Returns one location by its Ceyo UUID within the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
Response

Response envelope

location:Location

The requested, created, or updated location. The envelope is identical for UUID and external-ID lookup.

Object

Location

iduuid

Location identifier.

project_iduuid

Identifier of the containing project.

external_idstring | null

Case-sensitive identifier supplied by the partner.

namestring

Location display name.

folderstring | null

Optional organization folder.

tagsstring[]

Up to three organization tags.

descriptionstring | null

Location description.

websitestring | null

Normalized HTTP or HTTPS location website.

brand_aliasesstring[]

Normalized alternative names for the location brand.

languageISO 639-1 string | null

Location content language, or null when not overridden.

action_languageISO 639-1 string | null

Location action language, or null when not overridden.

effective_action_languageISO 639-1 string

Final action language after applying inheritance.

include_parent_brandboolean | null

Whether the parent project brand is included.

competitorsCompetitor[]

Active tracked competitors. Compatible tracked projection of the dedicated Competitors contract; suggested and dismissed records are excluded.

phonestring | null

Partner-supplied contact phone number.

emailstring | null

Normalized contact email address.

metadataobject

Partner-owned JSON metadata. Keys and values are returned without interpretation.

local_contextobject

Partner-supplied local facts used to contextualize processing.

focusglobal | country | region | city

Configured geographic targeting focus.

google_place_idstring | null

Google place identifier.

google_place_sourceprovided | discovered | null

Whether the Google place was supplied by the customer or matched during onboarding.

google_place_namestring | null

Business name associated with the Google place.

google_maps_urlstring | null

Google Maps URL for the location.

google_place_resolutionobject

Place resolution with state (resolved, ambiguous, unresolved, mismatch, or no_listing), source (customer or automatic), customer confirmation time, and ambiguous candidates containing only place_id, name, address, and google_maps_url.

formatted_addressstring | null

Formatted physical address.

address_line_2string | null

Optional second address line.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

postal_codestring | null

Normalized postal code.

countrystring | null

Normalized country name.

country_codestring | null

Explicit uppercase ISO 3166-1 alpha-2 country code, or null when not configured. Locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90.

longitudenumber | null

Longitude from -180 through 180.

statusactive | inactive | archived

Current location lifecycle status.

packagePackageReference

Assigned location package.

created_atdatetime

Location creation time in ISO 8601 format.

updated_atdatetime

Most recent location update time in ISO 8601 format.

Object

PackageReference

iduuid

Assigned package identifier.

namestring

Assigned package name.

Object

Competitor

iduuid

Competitor identifier.

kindcompetitor

Entity role. Always competitor in this projection.

namestring

Competitor display name.

domainstring

Normalized hostname without a scheme, path, query, leading www, or trailing dot. Required for tracked competitors.

aliasesstring[]

Additional names recognized for the competitor.

statusactive

Tracked competitors always participate in current processing.

competitor_statetracked

Management lifecycle state. This projection contains tracked competitors only.

created_atdatetime

Competitor creation time in ISO 8601 format.

updated_atdatetime

Most recent competitor update time in ISO 8601 format.

Object

Metadata and local context object

additional propertiesJSON value

Arbitrary partner-owned keys with string, number, boolean, null, object, or array values.

maximum size16 KB

Limit measured after JSON serialization.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam",
    "folder": "Europe",
    "tags": [
      "Flagship",
      "Airport"
    ],
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "action_language": "en",
    "effective_action_language": "en",
    "include_parent_brand": true,
    "competitors": [
      {
        "id": "63ec8dad-c12f-43c8-89e4-06eb629d0977",
        "kind": "competitor",
        "name": "Example Rival",
        "domain": "example-rival.com",
        "aliases": [
          "rival"
        ],
        "status": "active",
        "competitor_state": "tracked",
        "created_at": "2026-07-02T11:20:00Z",
        "updated_at": "2026-07-30T09:10:00Z"
      }
    ],
    "phone": "+31 20 555 0100",
    "email": "amsterdam@acme.example",
    "metadata": {
      "partner_region_id": "nl-west"
    },
    "local_context": {
      "neighborhood": "Centrum",
      "service_area": "Amsterdam"
    },
    "focus": "city",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "google_place_source": "provided",
    "google_place_name": "Acme Amsterdam",
    "google_maps_url": "https://maps.google.com/?cid=123456789",
    "google_place_resolution": {
      "state": "resolved",
      "source": "customer",
      "confirmed_at": "2026-07-31T08:10:00Z",
      "candidates": []
    },
    "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
    "address_line_2": null,
    "city": "Amsterdam",
    "state": "North Holland",
    "postal_code": "1012 JS",
    "country": "Netherlands",
    "country_code": null,
    "latitude": 52.3728,
    "longitude": 4.8936,
    "status": "active",
    "package": {
      "id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "name": "Local Growth Weekly"
    },
    "created_at": "2026-07-31T08:10:00Z",
    "updated_at": "2026-07-31T08:10:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/locations/{location_id}/facts

Returns the business facts Signal has reconciled for a location, including source details.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
Response

Response envelope

facts:BusinessFact[]

Facts ordered with disputed values first.

Object

BusinessFact

claim_typestring

Fact type, such as name, phone, website, address, hours, reservations, takeout, delivery, menu_url, booking_url, or meal service.

qualifierstring | null

Lowercase weekday for hours; null for other fact types.

valueJSON value

Current reconciled value.

verification_stateverified | supported | disputed | unverified | customer_confirmed

How the available sources currently support the fact.

publishableboolean

Whether Signal may use the value in generated recommendations.

observationsBusinessFactObservation[]

Source observations used to reconcile the fact.

updated_atdatetime

Most recent reconciliation time.

Object

BusinessFactObservation

source_kindstring

Stable source category.

source_labelstring

Customer-readable source name.

source_hoststring | null

Third-party host when relevant.

valueJSON value

Value reported by this source.

stanceassert | dispute

Whether the source supports or disputes the value.

observed_atdatetime

When the value was observed.

expires_atdatetime | null

When a customer confirmation expires.

page_urlstring | null

Public evidence page when available.

reasonstring | null

Customer-supplied dispute reason when available.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/facts' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "facts": [
    {
      "claim_type": "phone",
      "qualifier": null,
      "value": "+31 20 555 0100",
      "verification_state": "disputed",
      "publishable": false,
      "observations": [
        {
          "source_kind": "official_page",
          "source_label": "Your website",
          "value": "+31 20 555 0100",
          "stance": "assert",
          "observed_at": "2026-09-07T10:00:00Z",
          "page_url": "https://acme.example/amsterdam"
        },
        {
          "source_kind": "google_verified",
          "source_label": "Google Business Profile",
          "value": "+31 20 555 0199",
          "stance": "assert",
          "observed_at": "2026-09-07T10:05:00Z"
        }
      ],
      "updated_at": "2026-09-07T10:05:00Z"
    }
  ]
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

429rate_limit_exceeded

Too many requests were made.

POST
/projects/{project_id}/locations/{location_id}/facts/{claim_type}/confirm

Confirms the correct value for one location business fact and immediately reconciles dependent findings.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
claim_typestring

Supported business fact type.

Required
Request

Request body

valuestring | boolean | object

Required value to confirm or dispute. Hours use opens/closes or periods.

qualifierweekday

Required for hours and not accepted for other fact types.

reasonstring

Optional explanation, up to 500 characters.

Response

Response envelope

fact:BusinessFactreconciled:boolean
factBusinessFact

Updated fact.

reconciledboolean

Whether dependent findings were reconciled immediately.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/facts/phone/confirm' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "+31 20 555 0100"
}'
Example responseJSON
{
  "fact": {
    "claim_type": "phone",
    "qualifier": null,
    "value": "+31 20 555 0100",
    "verification_state": "customer_confirmed",
    "publishable": true,
    "observations": [],
    "updated_at": "2026-09-07T10:10:00Z"
  },
  "reconciled": true
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

POST
/projects/{project_id}/locations/{location_id}/facts/{claim_type}/dispute

Records that a reported value is incorrect and immediately reconciles dependent findings.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
claim_typestring

Supported business fact type.

Required
Request

Request body

valuestring | boolean | object

Required value to confirm or dispute. Hours use opens/closes or periods.

qualifierweekday

Required for hours and not accepted for other fact types.

reasonstring

Optional explanation, up to 500 characters.

Response

Response envelope

fact:BusinessFactreconciled:boolean
factBusinessFact

Updated fact.

reconciledboolean

Whether dependent findings were reconciled immediately.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/facts/phone/dispute' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "+31 20 555 0199",
  "reason": "This number belongs to another branch."
}'
Example responseJSON
{
  "fact": {
    "claim_type": "phone",
    "qualifier": null,
    "value": "+31 20 555 0199",
    "verification_state": "unverified",
    "publishable": false,
    "observations": [],
    "updated_at": "2026-09-07T10:10:00Z"
  },
  "reconciled": true
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/locations/overview

Returns a paginated location comparison view and map markers for the filtered result set.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
Parameters

Query parameters

qstring

Case-insensitive search across location name, external_id, formatted address, city, state, postal code, and country. Maximum: 200 characters.

Optional
statusactive | inactive

Return one non-archived lifecycle status. Archived locations are excluded.

Optional
country_codeISO 3166-1 alpha-2 string

Match the location’s explicit country code.

Optional
sortname | visibility_rate | avg_position

Field used for ordering. Null metrics sort after non-null values in either direction.

OptionalDefault: name
directionasc | desc

Sort direction. When sort is not name and direction is omitted, the default is desc.

OptionalDefault: asc
pageinteger

The 1-based page number.

OptionalDefault: 1
per_pageinteger

Number of records per page, from 1 through 100. Values outside this range return 422.

OptionalDefault: 25
Response

Response envelope

locations:LocationOverview[]pagination:Paginationmap:LocationMap
locationsLocationOverview[]

The requested page of matching locations.

paginationPagination

Pagination over the filtered and sorted location set.

mapLocationMap

Markers for the complete filtered set.

Object

LocationOverview

iduuid

Location identifier.

external_idstring | null

Partner-supplied location identifier.

namestring

Location display name.

statusactive | inactive

Current non-archived lifecycle status.

formatted_addressstring | null

Formatted physical address.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

country_codestring

Effective uppercase ISO 3166-1 alpha-2 country code.

latitudenumber | null

Latitude, or null when unavailable.

longitudenumber | null

Longitude, or null when unavailable.

visibility_summaryVisibilitySummary

Latest completed 30-day location visibility summary.

Object

VisibilitySummary

visibility_ratenumber | null

Percentage of included responses that mentioned the brand; null when unavailable.

avg_positionnumber | null

Average 1-based brand position when present; null when no ranked mention is available.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Number of records requested per page.

totalinteger

Total records matching the request.

total_pagesinteger

Total available pages.

Object

LocationMap

markersLocationMarker[]

Markers ordered by location name, then location ID. Only active locations with both coordinates are eligible.

Object

LocationMarker

iduuid

Location identifier.

external_idstring | null

Partner-supplied location identifier.

namestring

Location display name.

formatted_addressstring | null

Formatted address used in map labels.

latitudenumber

Marker latitude.

longitudenumber

Marker longitude.

visibility_ratenumber | null

Latest 30-day brand visibility percentage.

avg_positionnumber | null

Latest 30-day average brand position.

Metrics, map, and sortingVisibility fields use the latest completed 30-day window for each location. The page and marker set use the same search and filters. Pagination affects locations only. Every sort uses name and then location ID as ascending tie-breakers.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/overview?q=amsterdam&status=active&sort=visibility_rate&direction=desc&page=1&per_page=25' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "locations": [
    {
      "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
      "external_id": "partner-location-amsterdam",
      "name": "Acme Amsterdam",
      "status": "active",
      "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
      "city": "Amsterdam",
      "state": "North Holland",
      "country_code": "NL",
      "latitude": 52.3728,
      "longitude": 4.8936,
      "visibility_summary": {
        "visibility_rate": 68.4,
        "avg_position": 2.7
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  },
  "map": {
    "markers": [
      {
        "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
        "external_id": "partner-location-amsterdam",
        "name": "Acme Amsterdam",
        "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
        "latitude": 52.3728,
        "longitude": 4.8936,
        "visibility_rate": 68.4,
        "avg_position": 2.7
      }
    ]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

GET
/projects/{project_id}/locations/by-external-id/{external_id}

Returns the location whose external_id exactly matches the URL-encoded value within the selected project.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
external_idstring

URL-encoded, case-sensitive external ID previously assigned to the resource.

Required
Project-scoped lookupLocation external IDs are unique within a project and matching is case-sensitive. An empty or malformed path value returns 400; an unknown value or a value assigned in another project returns 404.
Response

Response envelope

location:Location

The requested, created, or updated location. The envelope is identical for UUID and external-ID lookup.

Object

Location

iduuid

Location identifier.

project_iduuid

Identifier of the containing project.

external_idstring | null

Case-sensitive identifier supplied by the partner.

namestring

Location display name.

folderstring | null

Optional organization folder.

tagsstring[]

Up to three organization tags.

descriptionstring | null

Location description.

websitestring | null

Normalized HTTP or HTTPS location website.

brand_aliasesstring[]

Normalized alternative names for the location brand.

languageISO 639-1 string | null

Location content language, or null when not overridden.

action_languageISO 639-1 string | null

Location action language, or null when not overridden.

effective_action_languageISO 639-1 string

Final action language after applying inheritance.

include_parent_brandboolean | null

Whether the parent project brand is included.

competitorsCompetitor[]

Active tracked competitors. Compatible tracked projection of the dedicated Competitors contract; suggested and dismissed records are excluded.

phonestring | null

Partner-supplied contact phone number.

emailstring | null

Normalized contact email address.

metadataobject

Partner-owned JSON metadata. Keys and values are returned without interpretation.

local_contextobject

Partner-supplied local facts used to contextualize processing.

focusglobal | country | region | city

Configured geographic targeting focus.

google_place_idstring | null

Google place identifier.

google_place_sourceprovided | discovered | null

Whether the Google place was supplied by the customer or matched during onboarding.

google_place_namestring | null

Business name associated with the Google place.

google_maps_urlstring | null

Google Maps URL for the location.

google_place_resolutionobject

Place resolution with state (resolved, ambiguous, unresolved, mismatch, or no_listing), source (customer or automatic), customer confirmation time, and ambiguous candidates containing only place_id, name, address, and google_maps_url.

formatted_addressstring | null

Formatted physical address.

address_line_2string | null

Optional second address line.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

postal_codestring | null

Normalized postal code.

countrystring | null

Normalized country name.

country_codestring | null

Explicit uppercase ISO 3166-1 alpha-2 country code, or null when not configured. Locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90.

longitudenumber | null

Longitude from -180 through 180.

statusactive | inactive | archived

Current location lifecycle status.

packagePackageReference

Assigned location package.

created_atdatetime

Location creation time in ISO 8601 format.

updated_atdatetime

Most recent location update time in ISO 8601 format.

Object

PackageReference

iduuid

Assigned package identifier.

namestring

Assigned package name.

Object

Competitor

iduuid

Competitor identifier.

kindcompetitor

Entity role. Always competitor in this projection.

namestring

Competitor display name.

domainstring

Normalized hostname without a scheme, path, query, leading www, or trailing dot. Required for tracked competitors.

aliasesstring[]

Additional names recognized for the competitor.

statusactive

Tracked competitors always participate in current processing.

competitor_statetracked

Management lifecycle state. This projection contains tracked competitors only.

created_atdatetime

Competitor creation time in ISO 8601 format.

updated_atdatetime

Most recent competitor update time in ISO 8601 format.

Object

Metadata and local context object

additional propertiesJSON value

Arbitrary partner-owned keys with string, number, boolean, null, object, or array values.

maximum size16 KB

Limit measured after JSON serialization.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/by-external-id/partner-location-amsterdam' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam",
    "folder": "Europe",
    "tags": [
      "Flagship",
      "Airport"
    ],
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "action_language": "en",
    "effective_action_language": "en",
    "include_parent_brand": true,
    "competitors": [
      {
        "id": "63ec8dad-c12f-43c8-89e4-06eb629d0977",
        "kind": "competitor",
        "name": "Example Rival",
        "domain": "example-rival.com",
        "aliases": [
          "rival"
        ],
        "status": "active",
        "competitor_state": "tracked",
        "created_at": "2026-07-02T11:20:00Z",
        "updated_at": "2026-07-30T09:10:00Z"
      }
    ],
    "phone": "+31 20 555 0100",
    "email": "amsterdam@acme.example",
    "metadata": {
      "partner_region_id": "nl-west"
    },
    "local_context": {
      "neighborhood": "Centrum",
      "service_area": "Amsterdam"
    },
    "focus": "city",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "google_place_source": "provided",
    "google_place_name": "Acme Amsterdam",
    "google_maps_url": "https://maps.google.com/?cid=123456789",
    "google_place_resolution": {
      "state": "resolved",
      "source": "customer",
      "confirmed_at": "2026-07-31T08:10:00Z",
      "candidates": []
    },
    "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
    "address_line_2": null,
    "city": "Amsterdam",
    "state": "North Holland",
    "postal_code": "1012 JS",
    "country": "Netherlands",
    "country_code": null,
    "latitude": 52.3728,
    "longitude": 4.8936,
    "status": "active",
    "package": {
      "id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "name": "Local Growth Weekly"
    },
    "created_at": "2026-07-31T08:10:00Z",
    "updated_at": "2026-07-31T08:10:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

429rate_limit_exceeded

Too many requests were made.

PATCH
/projects/{project_id}/locations/{location_id}

Updates only supplied location settings. Omitted fields remain unchanged.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
Request

Request body

namestring

New location name. Maximum: 200 characters.

external_idstring | null

partner identifier, unique among locations in this project.

descriptionstring | null

description. Maximum: 5,000 characters.

websitestring | null

Valid HTTP or HTTPS URL; maximum 2,048 characters.

brand_aliasesstring[]

Up to 10 alternative names, each at most 200 characters. Values are normalized and deduplicated.

languageISO 639-1 string | null

lowercase content-language override. If omitted, Signal infers it from a clear country_code; null uses the project location default, then en.

action_languageISO 639-1 string | null

lowercase action-language override. Null uses the project location default, then the effective content language.

include_parent_brandboolean | null

parent-brand override. Null uses the project location default.

phonestring | null

Contact phone number; maximum 50 characters.

emailstring | null

Valid contact email; maximum 320 characters.

metadataobject

Partner-owned JSON object, maximum serialized size 16 KB.

local_contextobject

Local context JSON object, maximum serialized size 16 KB.

focusglobal | country | region | city

Geographic targeting focus.

google_place_idstring | null

Google place identifier to select. Set to null to return the location to unresolved.

google_place_namestring | null

Google place business name. Maximum: 200 characters.

google_maps_urlstring | null

Google Maps URL. Maximum: 2,048 characters.

formatted_addressstring | null

Formatted physical address. Maximum: 500 characters.

address_line_2string | null

suite, unit, or floor. Preserved separately from the canonical address. Maximum: 200 characters.

citystring | null

City. Maximum: 200 characters.

statestring | null

Region or state. Maximum: 200 characters.

postal_codestring | null

Postal code. Maximum: 200 characters.

countrystring | null

Country name. Maximum: 200 characters.

country_codestring | null

ISO 3166-1 alpha-2 code. Null leaves the location country code unset; locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90. Latitude and longitude must be supplied together.

longitudenumber | null

Longitude from -180 through 180. Latitude and longitude must be supplied together.

folderstring | null

organization folder. Maximum: 30 characters.

tagsstring[]

Up to three organization tags. Each tag is 1–25 characters.

google_listing_absentboolean

Set to true to mark the location as having no Google listing.

address_line_2string | null

Replacement optional second address line.

Replacement and clearing behaviorProject membership and package assignment are immutable. Set nullable fields to null to clear them. metadata and local_context replace their complete objects; send {} to clear their keys. An empty brand_aliases array removes all aliases. Set google_place_id to null to return to unresolved, or send google_listing_absent: true to mark no listing.
Response

Response envelope

location:Location

The requested, created, or updated location. The envelope is identical for UUID and external-ID lookup.

Object

Location

iduuid

Location identifier.

project_iduuid

Identifier of the containing project.

external_idstring | null

Case-sensitive identifier supplied by the partner.

namestring

Location display name.

folderstring | null

Optional organization folder.

tagsstring[]

Up to three organization tags.

descriptionstring | null

Location description.

websitestring | null

Normalized HTTP or HTTPS location website.

brand_aliasesstring[]

Normalized alternative names for the location brand.

languageISO 639-1 string | null

Location content language, or null when not overridden.

action_languageISO 639-1 string | null

Location action language, or null when not overridden.

effective_action_languageISO 639-1 string

Final action language after applying inheritance.

include_parent_brandboolean | null

Whether the parent project brand is included.

competitorsCompetitor[]

Active tracked competitors. Compatible tracked projection of the dedicated Competitors contract; suggested and dismissed records are excluded.

phonestring | null

Partner-supplied contact phone number.

emailstring | null

Normalized contact email address.

metadataobject

Partner-owned JSON metadata. Keys and values are returned without interpretation.

local_contextobject

Partner-supplied local facts used to contextualize processing.

focusglobal | country | region | city

Configured geographic targeting focus.

google_place_idstring | null

Google place identifier.

google_place_sourceprovided | discovered | null

Whether the Google place was supplied by the customer or matched during onboarding.

google_place_namestring | null

Business name associated with the Google place.

google_maps_urlstring | null

Google Maps URL for the location.

google_place_resolutionobject

Place resolution with state (resolved, ambiguous, unresolved, mismatch, or no_listing), source (customer or automatic), customer confirmation time, and ambiguous candidates containing only place_id, name, address, and google_maps_url.

formatted_addressstring | null

Formatted physical address.

address_line_2string | null

Optional second address line.

citystring | null

Normalized city.

statestring | null

Normalized region or state.

postal_codestring | null

Normalized postal code.

countrystring | null

Normalized country name.

country_codestring | null

Explicit uppercase ISO 3166-1 alpha-2 country code, or null when not configured. Locations do not inherit the project country.

latitudenumber | null

Latitude from -90 through 90.

longitudenumber | null

Longitude from -180 through 180.

statusactive | inactive | archived

Current location lifecycle status.

packagePackageReference

Assigned location package.

created_atdatetime

Location creation time in ISO 8601 format.

updated_atdatetime

Most recent location update time in ISO 8601 format.

Object

PackageReference

iduuid

Assigned package identifier.

namestring

Assigned package name.

Object

Competitor

iduuid

Competitor identifier.

kindcompetitor

Entity role. Always competitor in this projection.

namestring

Competitor display name.

domainstring

Normalized hostname without a scheme, path, query, leading www, or trailing dot. Required for tracked competitors.

aliasesstring[]

Additional names recognized for the competitor.

statusactive

Tracked competitors always participate in current processing.

competitor_statetracked

Management lifecycle state. This projection contains tracked competitors only.

created_atdatetime

Competitor creation time in ISO 8601 format.

updated_atdatetime

Most recent competitor update time in ISO 8601 format.

Object

Metadata and local context object

additional propertiesJSON value

Arbitrary partner-owned keys with string, number, boolean, null, object, or array values.

maximum size16 KB

Limit measured after JSON serialization.

Request and response

Example requestcURL
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Acme Amsterdam Centrum",
  "description": "Acme flagship store in central Amsterdam.",
  "brand_aliases": [
    "acme amsterdam",
    "acme centrum"
  ],
  "phone": "+31 20 555 0199",
  "email": "centrum@acme.example",
  "metadata": {
    "partner_region_id": "nl-central"
  },
  "local_context": {
    "neighborhood": "Centrum",
    "service_area": "Amsterdam city center"
  },
  "focus": "city"
}'
Example responseJSON
{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam Centrum",
    "folder": "Europe",
    "tags": [
      "Flagship",
      "Airport"
    ],
    "description": "Acme flagship store in central Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam",
      "acme centrum"
    ],
    "language": "en",
    "action_language": "en",
    "effective_action_language": "en",
    "include_parent_brand": true,
    "competitors": [
      {
        "id": "63ec8dad-c12f-43c8-89e4-06eb629d0977",
        "kind": "competitor",
        "name": "Example Rival",
        "domain": "example-rival.com",
        "aliases": [
          "rival"
        ],
        "status": "active",
        "competitor_state": "tracked",
        "created_at": "2026-07-02T11:20:00Z",
        "updated_at": "2026-07-30T09:10:00Z"
      }
    ],
    "phone": "+31 20 555 0199",
    "email": "centrum@acme.example",
    "metadata": {
      "partner_region_id": "nl-central"
    },
    "local_context": {
      "neighborhood": "Centrum",
      "service_area": "Amsterdam city center"
    },
    "focus": "city",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "google_place_source": "provided",
    "google_place_name": "Acme Amsterdam",
    "google_maps_url": "https://maps.google.com/?cid=123456789",
    "google_place_resolution": {
      "state": "resolved",
      "source": "customer",
      "confirmed_at": "2026-07-31T08:10:00Z",
      "candidates": []
    },
    "formatted_address": "1 Market Street, 1012 JS Amsterdam, Netherlands",
    "address_line_2": null,
    "city": "Amsterdam",
    "state": "North Holland",
    "postal_code": "1012 JS",
    "country": "Netherlands",
    "country_code": null,
    "latitude": 52.3728,
    "longitude": 4.8936,
    "status": "active",
    "package": {
      "id": "8ae92d3f-18fb-4899-aef0-11f50b8bd0a7",
      "name": "Local Growth Weekly"
    },
    "created_at": "2026-07-31T08:10:00Z",
    "updated_at": "2026-07-31T12:10:00Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

409conflict

The external ID is already in use or the resource cannot accept this operation in its current state.

422validation_failed

One or more fields are invalid, or package_id does not identify an active package of the required type.

429rate_limit_exceeded

Too many requests were made.

DELETE
/projects/{project_id}/locations/{location_id}

Schedules asynchronous deletion of a location and its location-scoped resources.

Parameters

Path parameters

project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the project.

Required
202 AcceptedDeletion runs asynchronously and the response has no body.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
HTTP/1.1 202 Accepted
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": {
      "name": [
        "must be present"
      ]
    },
    "request_id": "req_01K1JQY1RQQ7N3C5H1K6J0P8AT"
  }
}
Errors

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404not_found

The requested project or location was not found.

429rate_limit_exceeded

Too many requests were made.