POST/api/v4/locations

Create a location

Creates a new business location in your account and queues it for listing submission.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

Name	Type	Required	Description
input.name	string	required	Name of the business.
input.description	string	required	Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeId	string	optional	Unique store code. Must be unique across the account.
input.street	string	optional	Street address.
input.city	string	required	City. Mandatory for countries with city-level addressing (`SY10126`); omit only for service-area businesses with `hideAddress: true`.
input.stateIso	string	optional	State ISO code. See the countries and states endpoint for valid values.
input.postalCode	string	optional	Postal code (validated against the country).
input.countryIso	string	required	Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phone	string	optional	Primary phone number, validated for the country.
input.website	string	optional	Business website URL.
input.subCategoryId	integer	required	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.folderIds	array of strings	optional	Folder IDs to place the location in. Defaults to the account root folder.
input.businessHours	array of objects	optional	Opening hours: `[{ day, slots: [{ openTime, closeTime }], closed }]`. `day` is an uppercase weekday enum; set `closed: true` for a closed day.
input.serviceArea	object	optional	Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinks	array of objects	optional	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean). On create every link is new, so no `action` is needed. See the Place Action Links guide.
input.enabledSiteIds	array of integers	optional	Site IDs to publish this location to, when you want a subset of your plan's sites. See the plan-sites endpoint for valid IDs. Omit to publish to every site in your plan.
input.clientMutationId	string	optional	Optional idempotency/echo token returned unchanged in the response.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

{
  "input": {
    "name": "Acme Dental",
    "description": "Acme Dental is a family-owned dental practice in downtown New York offering preventive care, cosmetic dentistry, orthodontics, and emergency appointments. Our board-certified team combines modern equipment with a gentle, patient-first approach, and same-week appointments are available for new patients.",
    "storeId": "ACME01",
    "street": "123 Jump Street",
    "city": "New York",
    "stateIso": "NY",
    "postalCode": "10013",
    "countryIso": "US",
    "phone": "6443859313",
    "website": "https://acmedental.example.com",
    "subCategoryId": 1432,
    "folderIds": ["d90630a7-7af0-450f-bdfe-6457eb438b1f"],
    "businessHours": [
      { "day": "MONDAY", "slots": [{ "openTime": "09:00am", "closeTime": "05:00pm" }], "closed": false },
      { "day": "SUNDAY", "closed": true }
    ],
    "placeActionLinks": [
      { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },
      { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }
    ]
  }
}

Responses

200Location created successfully. Returns the new location as a summary object.

{
  "data": {
    "createLocation": {
      "clientMutationId": null,
      "success": true,
      "errors": null,
      "location": {
        "id": "TG9jYXRpb246MTgwMDI5MA==",
        "databaseId": 1800290,
        "storeId": "ACME01",
        "name": "Acme Dental",
        "street": "123 Jump Street",
        "city": "New York",
        "stateIso": "NY",
        "postalCode": "10013",
        "countryIso": "US",
        "phone": "6443859313",
        "website": "https://acmedental.example.com",
        "status": "PENDING",
        "primaryGbpSiteCategoryId": null,
        "tags": [],
        "folders": [
          { "id": "d90630a7-7af0-450f-bdfe-6457eb438b1f", "name": "root", "root": true }
        ],
        "placeActionLinks": [
          { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true, "name": null, "submissionStatus": null },
          { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com", "isPreferred": false, "name": null, "submissionStatus": null }
        ],
        "discoveredPlaceActionLinks": []
      }
    }
  }
}

400Bad request — validation failure (see `errors[]`).

401Unauthenticated — missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

Creates a new business location. On success the location is queued for submission to every publisher in its plan (or, when enabledSiteIds is supplied, just those sites). Required fields: name, a description of at least 200 characters, subCategoryId, countryIso, and — for countries with city-level addressing — city. A location also needs a valid street address and phone before it can actually publish — supply them at create time to avoid a follow-up update.

The returned id is base64-encoded (e.g. TG9jYXRpb246MTgwMDI5MA==); decode it to reveal the internal Location:<databaseId> form. Every subsequent call references this base64 id.

Use case — onboard a single storefront with hours. Send the address, phone, subCategoryId, and a businessHours array (uppercase weekday enums with openTime/closeTime slots, or closed: true). Store your own key in storeId so you can later resolve the location via get by store codes without tracking listingsAPI's ID.

Use case — publishing to a site subset. Pass enabledSiteIds (site IDs from the plan-sites endpoint) to publish the location to a curated subset of directories rather than the full plan — the pattern agencies use to sell tiered site coverage.

Seed Google action buttons at create time. Pass placeActionLinks to set the location's Google action buttons (book an appointment, order online, and so on) in the same call. Valid placeActionType values are APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, and SHOP_ONLINE, with at most one preferred link per type. Right after create, each link's name and submissionStatus are null until it syncs to Google. To add, edit, or remove links later, use update a location; see the Place Action Links guide for the full model.

Common errors (surface as 400 with detail in errors[]): description must be at least 200 characters (SY10005), countryIso must be a supported country (SY10036), city is mandatory for countries with city-level addressing (SY10126), state must be a valid ISO code, postal code and phone must be valid for the country, subCategoryId must exist, and storeId must be unique across the account. Because location creation is the heaviest-weighted call, high-volume onboarding can trip a 429 — honor the Retry-After header and create sequentially rather than in a burst.

curl -X POST 'https://listingsapi.com/api/v4/locations' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input.name": "<input.name>",
    "input.description": "<input.description>",
    "input.storeId": "<input.storeId>",
    "input.street": "<input.street>",
    "input.city": "<input.city>",
    "input.stateIso": "<input.stateIso>",
    "input.postalCode": "<input.postalCode>",
    "input.countryIso": "<input.countryIso>",
    "input.phone": "<input.phone>",
    "input.website": "<input.website>",
    "input.subCategoryId": "<input.subCategoryId>",
    "input.folderIds": "<input.folderIds>",
    "input.businessHours": "<input.businessHours>",
    "input.serviceArea": "<input.serviceArea>",
    "input.placeActionLinks": "<input.placeActionLinks>",
    "input.enabledSiteIds": "<input.enabledSiteIds>",
    "input.clientMutationId": "<input.clientMutationId>"
  }'

Run in playground