Add a location

Overview

Add a new location under an account. It's attached to the account's current plan automatically, and a connection slot is created for each review site on that plan.

Use this when a business opens a new location, or when you're setting up an account that didn't use with_location=1.

You'll need the account_id, the location's name, address, city_id, and postal_code. Optional: your own client_location_id, a display label (storeid), website, phones.

Returns the new location, including its id (data.data.id), which you need to connect its review sites. The account owner gets a location-added email. Duplicate locations (same name, address, postal code, and city) are rejected. Next step: connect its review sites.

Prerequisites

A Partner token. See Authentication.
The account's id (account_id), e.g. from List your accounts.
A city_id.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/partner/store/create

Authentication

Partner token

account_id must be an existing, not deleted account inside your own account tree; otherwise 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`name`	string	Yes	The location's name. Max 255 characters, no `<` or `>`.
`storeid`	string	No	A display label for the location. Max 100 characters, no `<` or `>`. Defaults to the city name.
`client_location_id`	string	No	Your own id for the location. Max 100 characters, no `<` or `>`. Defaults to `""`.
`address`	string	Yes	Street address. Max 255 characters, no `<` or `>`.
`city_id`	integer	Yes	The city. Must be an existing city id.
`postal_code`	string	Yes	Postal code. 3 to 12 characters, no `<` or `>`.
`site_url`	string	No	The location's website. Must be a valid URL.
`company_phone`	string	No	The primary business phone. 9 to 15 characters.
`phone`	string	No	A secondary phone line. 9 to 15 characters.
`account_id`	integer	Yes	The account to add the location to.

Request payload

{
  "name": "Acme Plumbing - North",
  "storeid": "NORTH-01",
  "client_location_id": "loc-001",
  "address": "12 King Street",
  "city_id": 3243,
  "postal_code": "2000",
  "site_url": "https://acmebrand.com",
  "company_phone": "0291234567",
  "account_id": 5994
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`Location has been created successfully!`
`data`	object	The new location.
`data.id`	integer	The location's id. Use it as the location id (`store_id`) in other calls.
`data.account_id`	integer	The account's id.
`data.store_name`	string	The location's name.
`data.storeid`	string	The display label. The city name when you didn't send one.
`data.client_location_id`	string	Your own id for the location, or `""` when you didn't send one.
`data.code`	string	The location's code.
`data.slug`	string	The location's slug.
`data.status`	string	The location's status, e.g. `active`.
`data.address`	string	Street address.
`data.city_id`	integer	The city's id.
`data.city_name`	string	The city's name.
`data.postal_code`	string	Postal code.
`data.site_url`	string or null	The location's website, or `null`.
`data.company_phone`	string or null	The primary business phone, or `null`.
`data.phone`	string or null	The secondary phone line, or `null`.

Response payload

{
  "data": {
    "status": "success",
    "message": "Location has been created successfully!",
    "data": {
      "id": 3076,
      "account_id": 5994,
      "store_name": "Acme Plumbing - North",
      "storeid": "NORTH-01",
      "client_location_id": "loc-001",
      "code": "SAU178040716910",
      "slug": "acme-plumbing-north",
      "status": "active",
      "address": "12 King Street",
      "city_id": 3243,
      "city_name": "Sydney",
      "postal_code": "2000",
      "site_url": "https://acmebrand.com",
      "company_phone": "0291234567",
      "phone": null
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Required fields missing

{
  "message": "The name field is required. (and 4 more errors)",
  "errors": {
    "name": ["The name field is required."],
    "address": ["The address field is required."],
    "city_id": ["The city id field is required."],
    "postal_code": ["The postal code field is required."],
    "account_id": ["The account id field is required."]
  }
}

422 Account not found or outside your tree

{
  "message": "The selected account is invalid or deleted. (and 1 more error)",
  "errors": {
    "account_id": [
      "The selected account is invalid or deleted.",
      "The selected account id does not belong to your company hierarchy."
    ]
  }
}

500 Duplicate location

A location with the same name, address, postal code and city already exists.

{
  "message": "This location is already registered!",
  "status": "error",
  "errors": []
}

Status	Meaning
`200`	The location is created.
`401`	The token is missing, expired or invalid.
`422`	A required field is missing or invalid, or `account_id` doesn't exist, is deleted or is outside your tree. The response names the fields.
`500`	Duplicate location (same name, address, postal code and city), or the location couldn't be created.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/store/create" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Acme Plumbing - North", "storeid": "NORTH-01", "client_location_id": "loc-001", "address": "12 King Street", "city_id": 3243, "postal_code": "2000", "site_url": "https://acmebrand.com", "company_phone": "0291234567", "account_id": 5994}'