Create location

Overview

Create a new location under an account in one transaction. If the account has a most-recent plan, the location is auto-attached to that plan and blank review_sites rows are seeded. Rejects duplicates (same name + address + postal code + city). Logs an audit event and emails a location-added notification.

Prerequisites

A partner bearer token. The API authenticates with OAuth 2.0 Bearer tokens (RS256-signed JWTs). Obtain one via POST /login or the SSO flow, then send it as Authorization: Bearer <bearer-token> — see Authentication for the token lifecycle.
Partner-admin scope. Only a partner-admin token can call this endpoint, and the target account_id must sit inside the caller's own partner tree (see Authentication below).

Base URL

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

Endpoint

POST /api/v1/partner/store/create

Authentication

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Who can call it: partner-admin tokens only.
This endpoint sits under the partner/ authentication group, so the token must belong to a partner-admin user.
The target account is identified by the account_id field in the request body.
That account must exist, must not be deleted, and must pass an ownership check — it has to sit inside the caller's own partner tree.
A request that references an account outside that tree is rejected.

Rate limit

No rate limit.

Request body

Body:

Field	Type	Required	Description
`name`	string	required	max 255; no angle brackets (`<`/`>`)
`storeid`	string	optional	max 100; no angle brackets
`client_location_id`	string	optional	max 100; no angle brackets
`address`	string	required	max 255; no angle brackets
`city_id`	int	required	must reference an existing `city.id`
`postal_code`	string	required	min 3, max 12; no angle brackets
`site_url`	string	optional	must be a valid URL
`company_phone`	string	optional	min 9, max 15 digits — primary business phone
`phone`	string	optional	min 9, max 15 digits — secondary line
`account_id`	int	required	parent account company id (`bundle_id = 3`); must exist, not deleted, and pass an ownership check

{
  "name": "Downtown Location",
  "storeid": "LOC-001",
  "client_location_id": "CLIENT-LOC-001",
  "address": "123 Main Street",
  "city_id": 123,
  "postal_code": "10001",
  "site_url": "https://downtown.acmebrand.com",
  "company_phone": "1234567890",
  "phone": "9876543210",
  "account_id": 123
}

Response

data.status (string) — success.
data.message (string) — Location has been created successfully!.

A duplicate location currently comes back as 500 with { status: "error", message: "This location is already registered!" }.

200 Success · `200`

{
  "data": {
    "status": "success",
    "message": "Location has been created successfully!"
  }
}

500 Duplicate · `500`

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

Errors

Status	Meaning
`401`	The bearer token is missing, expired or invalid
`422`	The request failed validation — the response names the fields
`500`	Duplicate

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": "Downtown Location", "storeid": "LOC-001", "client_location_id": "CLIENT-LOC-001", "address": "123 Main Street", "city_id": 123, "postal_code": "10001", "site_url": "https://downtown.acmebrand.com", "company_phone": "1234567890", "phone": "9876543210", "account_id": 123}'

Updated 11 days ago

Did this page help you?