Skip to content
/
Create a location

Create a location

Request

Creates a standalone Location for the current authenticated user.

Authorization is user-delegated only (Authorization Code + PKCE); installation (client credentials) tokens and restricted keys are rejected. country_code, timezone, and currency are derived from city_id and are not writable.

The 201 response carries provisioning_status: ready means base accounts and payment methods already exist, pending means defaults are still being provisioned. Requires Idempotency-Key.

Errors: 403 user_not_verified / location_creation_forbidden / unsupported_token_subject; 409 duplicate_location; 422 invalid_city / unsupported_country / invalid_business_type / location_quota_exceeded; 429 location_creation_rate_limited.

Security
OAuth2(Required scopes: locations:create)
Headers
Idempotency-Keystring, <= 255 charactersrequired

Client-generated unique key for this logical request (UUID recommended). A retry with the same key and body returns the original result; the same key with a different body fails with 409 idempotency_key_reused. Keys are retained at least 24 hours and are scoped to credential, Location, and operation; after expiry the value may be reused for a new logical request.

Bodyapplication/jsonrequired
namestringrequired
city_idintegerrequired
business_type_idintegerrequired
languagestringrequired

BCP 47 language tag.

datetime_formatstringrequired
curl -i -X POST \
  https://developer.alteg.io/_mock/en/b2b-v3/openapi/locations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "name": "Lisbon Center",
    "city_id": 6201,
    "business_type_id": 1,
    "language": "en-PT",
    "datetime_format": "DD.MM.YYYY HH:mm"
  }'

Responses

Created

Headers
RateLimit-Remaininginteger, (int32), >= 0

Requests left in the most constrained policy window that applies to this request.

RateLimit-Resetinteger, (int32), >= 0

On 429, seconds until the most constrained policy frees up; it equals Retry-After there. On a successful response it reports the length of that policy's window rather than the time left in the current one, so treat it as the window size, not as a countdown — the counter to pace against is RateLimit-Remaining.

RateLimit-Policystring

Most constrained policy applied to the request, as <limit>;w=<window in seconds>.

Example:"10;w=60"
Locationstring

URL of the created resource.

X-Request-Idstring

Request identifier for support and log correlation.

Bodyapplication/json
city_idintegerrequired

City dictionary id.

country_codestringread-onlyrequired

ISO 3166-1 alpha-2 country code. Derived from city.

currencystringread-onlyrequired

ISO 4217 currency of the Location. Server-controlled.

datetime_formatstringrequired
idintegerread-onlyrequired
languagestringrequired

BCP 47 language tag.

namestringrequired
objectstringread-onlyrequired
Value:"location"
provisioning_statusstringread-onlyrequired

ready = base accounts and payment methods exist; pending = defaults are still being provisioned.

Enum:"ready""pending"
timezonestringread-onlyrequired

Canonical IANA timezone of the Location (e.g. Europe/Lisbon).

unique_visit_time_intervalintegerrequired

Visit grouping interval in seconds: -1 groups all appointments of the day, 0 keeps each appointment separate, positive values group by interval.

descriptionstring or null
business_type_idinteger or null

Business category of the Location.

addressstring or null
coordinatesobject or null
phonesArray of strings

Business contact phone numbers in international format.

sitestring or null
created_atstring, (date-time)read-only

UTC.

updated_atstring, (date-time)read-only

UTC.

Response
{
  "id": 0,
  "object": "location",
  "name": "string",
  "description": "string",
  "business_type_id": 0,
  "address": "string",
  "coordinates": {
    "latitude": 0,
    "longitude": 0
  },
  "phones": [
    "string"
  ],
  "site": "string",
  "timezone": "string",
  "currency": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "city_id": 0,
  "language": "string",
  "datetime_format": "string",
  "unique_visit_time_interval": 0,
  "country_code": "string",
  "provisioning_status": "ready"
}