Locations

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

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.

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.

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

List locations

/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, and email. Maximum: 200 characters.

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.

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.

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.

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

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_...'

{
  "locations": [
    {
      "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
      "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
      "external_id": "partner-location-amsterdam",
      "name": "Acme Amsterdam",
      "description": "Acme flagship store in Amsterdam.",
      "website": "https://acme.example/amsterdam",
      "brand_aliases": [
        "acme amsterdam"
      ],
      "language": "en",
      "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",
      "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.

{
  "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

Create location

/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. 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.

startboolean

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

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.

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.

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.

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.

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

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
}'

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",
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "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",
    "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.

{
  "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

Bulk create locations

/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.

Response

Response envelope

bulk_operation:BulkOperation

Accepted operation summary with an ID and status_url for polling.

Request and response

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
    },
    {
      "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,
      "city": "Rotterdam"
    }
  ]
}'

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.

{
  "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

Get location

/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.

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.

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.

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

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_...'

{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam",
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "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",
    "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.

{
  "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

Get locations overview

/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

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_...'

{
  "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.

{
  "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

Find location by external ID

/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.

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.

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.

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

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_...'

{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam",
    "description": "Acme flagship store in Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam"
    ],
    "language": "en",
    "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",
    "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.

{
  "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

Update location

/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. 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, 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

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.

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.

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.

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.

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.

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

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"
}'

{
  "location": {
    "id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "external_id": "partner-location-amsterdam",
    "name": "Acme Amsterdam Centrum",
    "description": "Acme flagship store in central Amsterdam.",
    "website": "https://acme.example/amsterdam",
    "brand_aliases": [
      "acme amsterdam",
      "acme centrum"
    ],
    "language": "en",
    "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",
    "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.

{
  "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

Delete location

/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

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_...'

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.

{
  "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.