Create a location
Creates a location in the credential's own tenant and answers it with status ACTIVE. Every member of the body but templateId is required; an omitted one is reported in errors under its own name with code required, the same way an invalid one is. A body member this document does not declare is ignored.
Behavior and permissions
templateId is optional and provisions the new location: the named template's captured configuration — its services, windows, operating hours and scalars — is written onto the location as it is created, and the location is created linked to that template. It is one act: a templateId naming no template of this tenant creates nothing at all and is answered 400 with a single errors entry naming templateId with code not_found. That not_found is an errors[].code, not the document-level not_found that answers an unserved path — the same spelling at two levels, and this one never carries a 404.
The location's configuration is not part of this answer; read it back from the configuration read.
A tenant whose plan's location maximum is reached is answered 409 plan_location_limit_reached, naming the plan that fits, or the Enterprise offer when no plan does. The required and format checks on the body run before that limit. Whether the name is already taken is checked after the limit, so a tenant at its maximum is answered 409 whatever the name holds.
Requires a credential issued by a tenant administrator.
Authorization · Example request · Parameters · Request body · Responses
POST/api/integration/v1/locations
Authorization
- apiKeyAuth — apiKey sent in the Authorization header
Use Authorization: Api-Key <secret>. Get a credential and check the scopes and issuer authority required for this operation.
Example request
Set QMS_BASE_URL to your workspace URL and QMS_API_KEY to your secret. Replace example identifiers with your own.
curl --request POST "$QMS_BASE_URL/api/integration/v1/locations" \
--header "Authorization: Api-Key $QMS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Riverside Branch",
"street": "Gedimino pr. 1",
"city": "Vilnius",
"postalCode": "01103",
"country": "LT",
"timezone": "Europe/Vilnius",
"defaultLocale": "EN"
}'Parameters
None.
Request body
{
"name": "Riverside Branch",
"street": "Gedimino pr. 1",
"city": "Vilnius",
"postalCode": "01103",
"country": "LT",
"timezone": "Europe/Vilnius",
"defaultLocale": "EN"
}Request schema
The location create body: the same members the entry publishes, minus the server-owned `id` and `status`. All seven are required; an omitted one is answered the same way an invalid one is, as an `errors` entry with code `required`.
name · string · required
street · string · required
city · string · required
postalCode · string · required
country · string · required
An ISO 3166-1 alpha-2 country code.
timezone · string · required
A region identifier of the IANA tz database that the platform supports, such as Europe/Vilnius. Offset forms such as +02:00 or UTC+2 and non-region identifiers such as UTC, Etc/* or legacy aliases are refused with `invalid_timezone`.
defaultLocale · string · required
The location's default language, spelled as on the entry.
templateId · string · optional
A location template to provision the new location from. Optional and the only optional member: absent, the location is created unconfigured and independent. Present, its captured configuration is written onto the location and the location is created linked to it, inside the same act — a value naming no template of this tenant creates nothing and is answered as an `errors` entry with code `not_found`.
Raw JSON Schema
application/json
{
"type": "object",
"description": "The location create body: the same members the entry publishes, minus the server-owned `id` and `status`. All seven are required; an omitted one is answered the same way an invalid one is, as an `errors` entry with code `required`.",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"example": "Riverside Branch"
},
"street": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"example": "Gedimino pr. 1"
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 85,
"example": "Vilnius"
},
"postalCode": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"example": "01103"
},
"country": {
"type": "string",
"description": "An ISO 3166-1 alpha-2 country code.",
"example": "LT"
},
"timezone": {
"type": "string",
"description": "A region identifier of the IANA tz database that the platform supports, such as Europe/Vilnius. Offset forms such as +02:00 or UTC+2 and non-region identifiers such as UTC, Etc/* or legacy aliases are refused with `invalid_timezone`.",
"example": "Europe/Vilnius"
},
"defaultLocale": {
"type": "string",
"description": "The location's default language, spelled as on the entry.",
"example": "EN"
},
"templateId": {
"type": "string",
"description": "A location template to provision the new location from. Optional and the only optional member: absent, the location is created unconfigured and independent. Present, its captured configuration is written onto the location and the location is created linked to it, inside the same act — a value naming no template of this tenant creates nothing and is answered as an `errors` entry with code `not_found`.",
"example": "99999999-9999-4999-8999-999999999999"
}
},
"required": [
"name",
"street",
"city",
"postalCode",
"country",
"timezone",
"defaultLocale"
]
}Responses
201 — The location as created.
{
"id": "22222222-2222-4222-8222-222222222222",
"name": "Riverside Branch",
"street": "Gedimino pr. 1",
"city": "Vilnius",
"postalCode": "01103",
"country": "LT",
"timezone": "Europe/Vilnius",
"defaultLocale": "EN",
"status": "ACTIVE"
}201 response schema
One location. Every member is always present; a member the tenant has left empty is null rather than absent. The address is four structured members and there is deliberately no formatted address line: a caller composes its own display line from them. This surface is unlocalised, so a line composed here could not be in the reader's language anyway. No queue-configuration member is published — operating hours, service windows, counters and the rest belong to operations this document does not describe.
id · string · required
name · string · required
street · string | null · required
city · string | null · required
postalCode · string | null · required
country · string | null · required
An ISO 3166-1 alpha-2 country code.
timezone · string · required
An IANA timezone identifier. A location created before the strict check may still carry a legacy value until its zone is changed.
defaultLocale · string · required
The location's default language: a two-letter upper-case code of a language the platform translates for customer pages. Which languages that covers is configuration; a language added to it is not a change to this schema.
status · string · required
Whether the location is in service. A permanently deleted location appears in no response at all, so no third value reaches a client.
Allowed values: "ACTIVE", "ARCHIVED"
Raw JSON Schema
application/json
{
"type": "object",
"description": "One location. Every member is always present; a member the tenant has left empty is null rather than absent.\n\nThe address is four structured members and there is deliberately no formatted address line: a caller composes its own display line from them. This surface is unlocalised, so a line composed here could not be in the reader's language anyway.\n\nNo queue-configuration member is published — operating hours, service windows, counters and the rest belong to operations this document does not describe.",
"properties": {
"id": {
"type": "string",
"example": "22222222-2222-4222-8222-222222222222"
},
"name": {
"type": "string",
"example": "City Centre"
},
"street": {
"type": [
"string",
"null"
],
"example": "Gedimino pr. 1"
},
"city": {
"type": [
"string",
"null"
],
"example": "Vilnius"
},
"postalCode": {
"type": [
"string",
"null"
],
"example": "01103"
},
"country": {
"type": [
"string",
"null"
],
"description": "An ISO 3166-1 alpha-2 country code.",
"example": "LT"
},
"timezone": {
"type": "string",
"description": "An IANA timezone identifier. A location created before the strict check may still carry a legacy value until its zone is changed.",
"example": "Europe/Vilnius"
},
"defaultLocale": {
"type": "string",
"description": "The location's default language: a two-letter upper-case code of a language the platform translates for customer pages. Which languages that covers is configuration; a language added to it is not a change to this schema.",
"example": "EN"
},
"status": {
"type": "string",
"description": "Whether the location is in service. A permanently deleted location appears in no response at all, so no third value reaches a client.",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"example": "ACTIVE"
}
},
"required": [
"id",
"name",
"street",
"city",
"postalCode",
"country",
"timezone",
"defaultLocale",
"status"
]
}400 — The request body or query parameters failed field validation. `errors` carries one entry per offending field, naming the member as this document spells it and the reason as a published slug. The member is absent when no single field can be named. On the service edit this status is shared with `service_code_immutable` — see that response. Branch on `code`.
{
"type": "urn:qms:problem:validation_failed",
"title": "Validation Failed",
"status": 400,
"code": "validation_failed",
"detail": "The request body failed field validation.",
"errors": [
{
"field": "country",
"code": "invalid_country"
},
{
"field": "name",
"code": "required"
}
]
}400 response schema
An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.
type · string · required
A URN identifying the problem kind, one per `code`.
title · string · required
A fixed English summary of the problem kind.
status · integer · required
The HTTP status code, repeated in the body.
code · string · required
The published slug this surface's error vocabulary uses.
detail · string · required
An English explanation of this occurrence.
errors · array · optional
One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.
Show nested fields
One offending field of a 400 field-validation refusal.
field · string · required
The member as THIS document spells it, which is not always what the same field is called inside the system.
code · string · required
The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`. Three of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.
blockers · array · optional
One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.
Show nested fields
One non-zero blocking category of a 409 refusal, and how many things it counted.
kind · string · required
What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.
Allowed values: "LOCATION", "TICKET", "APPOINTMENT", "TEMPLATE", "OPERATOR"
count · integer · required
How many of them there are. Always greater than zero.
checkCode · string · optional
The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.
planLimit · object · optional
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
Show nested fields
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
currentPlan · object · required
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
activeLocations · integer · required
The number of ACTIVE locations the tenant holds.
nextPlan · object · optional
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
enterpriseOffer · object · optional
The published Enterprise offer, named when no active plan covers the tenant's active location count.
Show nested fields
The published Enterprise offer, named when no active plan covers the tenant's active location count.
minLocations · integer · required
The smallest number of locations the offer covers.
fromMonthlyPriceCents · integer · int64 · required
The monthly price from which the offer starts, in euro cents.
extraLocationPriceCents · integer · int64 · required
The monthly price of each location beyond `minLocations`, in euro cents.
contactEmail · string · optional
The address to write to about a larger plan or an individual contract.
Raw JSON Schema
application/problem+json
{
"type": "object",
"description": "An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.",
"properties": {
"type": {
"type": "string",
"description": "A URN identifying the problem kind, one per `code`.",
"example": "urn:qms:problem:location_not_found"
},
"title": {
"type": "string",
"description": "A fixed English summary of the problem kind.",
"example": "Location Not Found"
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"example": 404
},
"code": {
"type": "string",
"description": "The published slug this surface's error vocabulary uses.",
"example": "location_not_found"
},
"detail": {
"type": "string",
"description": "An English explanation of this occurrence.",
"example": "No location was found for this identifier."
},
"errors": {
"type": "array",
"description": "One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.",
"items": {
"type": "object",
"description": "One offending field of a 400 field-validation refusal.",
"properties": {
"field": {
"type": "string",
"description": "The member as THIS document spells it, which is not always what the same field is called inside the system.",
"example": "defaultLocale"
},
"code": {
"type": "string",
"description": "The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`.\n\nThree of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.",
"example": "invalid_locale"
}
},
"required": [
"field",
"code"
]
}
},
"blockers": {
"type": "array",
"description": "One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.",
"items": {
"type": "object",
"description": "One non-zero blocking category of a 409 refusal, and how many things it counted.",
"properties": {
"kind": {
"type": "string",
"description": "What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.",
"enum": [
"LOCATION",
"TICKET",
"APPOINTMENT",
"TEMPLATE",
"OPERATOR"
],
"example": "TICKET"
},
"count": {
"type": "integer",
"description": "How many of them there are. Always greater than zero.",
"example": 3
}
},
"required": [
"kind",
"count"
]
}
},
"checkCode": {
"type": "string",
"description": "The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.",
"example": "unreachable"
},
"planLimit": {
"type": "object",
"description": "What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.",
"properties": {
"currentPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"activeLocations": {
"type": "integer",
"description": "The number of ACTIVE locations the tenant holds.",
"example": 3
},
"nextPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"enterpriseOffer": {
"type": "object",
"description": "The published Enterprise offer, named when no active plan covers the tenant's active location count.",
"properties": {
"minLocations": {
"type": "integer",
"description": "The smallest number of locations the offer covers.",
"example": 8
},
"fromMonthlyPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price from which the offer starts, in euro cents.",
"example": 27900
},
"extraLocationPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price of each location beyond `minLocations`, in euro cents.",
"example": 2900
}
},
"required": [
"minLocations",
"fromMonthlyPriceCents",
"extraLocationPriceCents"
]
},
"contactEmail": {
"type": "string",
"description": "The address to write to about a larger plan or an individual contract.",
"example": "sales@example.com"
}
},
"required": [
"currentPlan",
"activeLocations"
]
}
},
"required": [
"type",
"title",
"status",
"code",
"detail"
],
"additionalProperties": false
}401 — No valid API credential was presented. Every refusal cause — absent, malformed, unknown, expired, revoked, or belonging to another tenant — answers with this one document, and no `WWW-Authenticate` header is returned.
{
"type": "urn:qms:problem:unauthenticated",
"title": "Unauthenticated",
"status": 401,
"code": "unauthenticated",
"detail": "The request presented no valid API credential."
}401 response schema
An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.
type · string · required
A URN identifying the problem kind, one per `code`.
title · string · required
A fixed English summary of the problem kind.
status · integer · required
The HTTP status code, repeated in the body.
code · string · required
The published slug this surface's error vocabulary uses.
detail · string · required
An English explanation of this occurrence.
errors · array · optional
One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.
Show nested fields
One offending field of a 400 field-validation refusal.
field · string · required
The member as THIS document spells it, which is not always what the same field is called inside the system.
code · string · required
The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`. Three of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.
blockers · array · optional
One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.
Show nested fields
One non-zero blocking category of a 409 refusal, and how many things it counted.
kind · string · required
What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.
Allowed values: "LOCATION", "TICKET", "APPOINTMENT", "TEMPLATE", "OPERATOR"
count · integer · required
How many of them there are. Always greater than zero.
checkCode · string · optional
The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.
planLimit · object · optional
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
Show nested fields
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
currentPlan · object · required
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
activeLocations · integer · required
The number of ACTIVE locations the tenant holds.
nextPlan · object · optional
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
enterpriseOffer · object · optional
The published Enterprise offer, named when no active plan covers the tenant's active location count.
Show nested fields
The published Enterprise offer, named when no active plan covers the tenant's active location count.
minLocations · integer · required
The smallest number of locations the offer covers.
fromMonthlyPriceCents · integer · int64 · required
The monthly price from which the offer starts, in euro cents.
extraLocationPriceCents · integer · int64 · required
The monthly price of each location beyond `minLocations`, in euro cents.
contactEmail · string · optional
The address to write to about a larger plan or an individual contract.
Raw JSON Schema
application/problem+json
{
"type": "object",
"description": "An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.",
"properties": {
"type": {
"type": "string",
"description": "A URN identifying the problem kind, one per `code`.",
"example": "urn:qms:problem:location_not_found"
},
"title": {
"type": "string",
"description": "A fixed English summary of the problem kind.",
"example": "Location Not Found"
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"example": 404
},
"code": {
"type": "string",
"description": "The published slug this surface's error vocabulary uses.",
"example": "location_not_found"
},
"detail": {
"type": "string",
"description": "An English explanation of this occurrence.",
"example": "No location was found for this identifier."
},
"errors": {
"type": "array",
"description": "One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.",
"items": {
"type": "object",
"description": "One offending field of a 400 field-validation refusal.",
"properties": {
"field": {
"type": "string",
"description": "The member as THIS document spells it, which is not always what the same field is called inside the system.",
"example": "defaultLocale"
},
"code": {
"type": "string",
"description": "The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`.\n\nThree of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.",
"example": "invalid_locale"
}
},
"required": [
"field",
"code"
]
}
},
"blockers": {
"type": "array",
"description": "One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.",
"items": {
"type": "object",
"description": "One non-zero blocking category of a 409 refusal, and how many things it counted.",
"properties": {
"kind": {
"type": "string",
"description": "What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.",
"enum": [
"LOCATION",
"TICKET",
"APPOINTMENT",
"TEMPLATE",
"OPERATOR"
],
"example": "TICKET"
},
"count": {
"type": "integer",
"description": "How many of them there are. Always greater than zero.",
"example": 3
}
},
"required": [
"kind",
"count"
]
}
},
"checkCode": {
"type": "string",
"description": "The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.",
"example": "unreachable"
},
"planLimit": {
"type": "object",
"description": "What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.",
"properties": {
"currentPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"activeLocations": {
"type": "integer",
"description": "The number of ACTIVE locations the tenant holds.",
"example": 3
},
"nextPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"enterpriseOffer": {
"type": "object",
"description": "The published Enterprise offer, named when no active plan covers the tenant's active location count.",
"properties": {
"minLocations": {
"type": "integer",
"description": "The smallest number of locations the offer covers.",
"example": 8
},
"fromMonthlyPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price from which the offer starts, in euro cents.",
"example": 27900
},
"extraLocationPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price of each location beyond `minLocations`, in euro cents.",
"example": 2900
}
},
"required": [
"minLocations",
"fromMonthlyPriceCents",
"extraLocationPriceCents"
]
},
"contactEmail": {
"type": "string",
"description": "The address to write to about a larger plan or an individual contract.",
"example": "sales@example.com"
}
},
"required": [
"currentPlan",
"activeLocations"
]
}
},
"required": [
"type",
"title",
"status",
"code",
"detail"
],
"additionalProperties": false
}403 — The operation was refused before anything was read or written. Two codes share this status: `insufficient_scope` when the credential's scope set does not admit the operation at all, and `insufficient_authority` when the scope set admits it but the user who issued the credential is a location manager and the operation requires a tenant administrator. The scope check runs first, so it displaces the authority refusal whenever both apply, and widening the scopes never lifts the authority refusal. Branch on `code`, never on the status alone.
{
"type": "urn:qms:problem:insufficient_scope",
"title": "Insufficient Scope",
"status": 403,
"code": "insufficient_scope",
"detail": "The API credential does not reach this operation."
}{
"type": "urn:qms:problem:insufficient_authority",
"title": "Insufficient Authority",
"status": 403,
"code": "insufficient_authority",
"detail": "The API credential's role does not reach this operation."
}403 response schema
An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.
type · string · required
A URN identifying the problem kind, one per `code`.
title · string · required
A fixed English summary of the problem kind.
status · integer · required
The HTTP status code, repeated in the body.
code · string · required
The published slug this surface's error vocabulary uses.
detail · string · required
An English explanation of this occurrence.
errors · array · optional
One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.
Show nested fields
One offending field of a 400 field-validation refusal.
field · string · required
The member as THIS document spells it, which is not always what the same field is called inside the system.
code · string · required
The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`. Three of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.
blockers · array · optional
One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.
Show nested fields
One non-zero blocking category of a 409 refusal, and how many things it counted.
kind · string · required
What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.
Allowed values: "LOCATION", "TICKET", "APPOINTMENT", "TEMPLATE", "OPERATOR"
count · integer · required
How many of them there are. Always greater than zero.
checkCode · string · optional
The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.
planLimit · object · optional
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
Show nested fields
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
currentPlan · object · required
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
activeLocations · integer · required
The number of ACTIVE locations the tenant holds.
nextPlan · object · optional
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
enterpriseOffer · object · optional
The published Enterprise offer, named when no active plan covers the tenant's active location count.
Show nested fields
The published Enterprise offer, named when no active plan covers the tenant's active location count.
minLocations · integer · required
The smallest number of locations the offer covers.
fromMonthlyPriceCents · integer · int64 · required
The monthly price from which the offer starts, in euro cents.
extraLocationPriceCents · integer · int64 · required
The monthly price of each location beyond `minLocations`, in euro cents.
contactEmail · string · optional
The address to write to about a larger plan or an individual contract.
Raw JSON Schema
application/problem+json
{
"type": "object",
"description": "An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.",
"properties": {
"type": {
"type": "string",
"description": "A URN identifying the problem kind, one per `code`.",
"example": "urn:qms:problem:location_not_found"
},
"title": {
"type": "string",
"description": "A fixed English summary of the problem kind.",
"example": "Location Not Found"
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"example": 404
},
"code": {
"type": "string",
"description": "The published slug this surface's error vocabulary uses.",
"example": "location_not_found"
},
"detail": {
"type": "string",
"description": "An English explanation of this occurrence.",
"example": "No location was found for this identifier."
},
"errors": {
"type": "array",
"description": "One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.",
"items": {
"type": "object",
"description": "One offending field of a 400 field-validation refusal.",
"properties": {
"field": {
"type": "string",
"description": "The member as THIS document spells it, which is not always what the same field is called inside the system.",
"example": "defaultLocale"
},
"code": {
"type": "string",
"description": "The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`.\n\nThree of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.",
"example": "invalid_locale"
}
},
"required": [
"field",
"code"
]
}
},
"blockers": {
"type": "array",
"description": "One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.",
"items": {
"type": "object",
"description": "One non-zero blocking category of a 409 refusal, and how many things it counted.",
"properties": {
"kind": {
"type": "string",
"description": "What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.",
"enum": [
"LOCATION",
"TICKET",
"APPOINTMENT",
"TEMPLATE",
"OPERATOR"
],
"example": "TICKET"
},
"count": {
"type": "integer",
"description": "How many of them there are. Always greater than zero.",
"example": 3
}
},
"required": [
"kind",
"count"
]
}
},
"checkCode": {
"type": "string",
"description": "The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.",
"example": "unreachable"
},
"planLimit": {
"type": "object",
"description": "What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.",
"properties": {
"currentPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"activeLocations": {
"type": "integer",
"description": "The number of ACTIVE locations the tenant holds.",
"example": 3
},
"nextPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"enterpriseOffer": {
"type": "object",
"description": "The published Enterprise offer, named when no active plan covers the tenant's active location count.",
"properties": {
"minLocations": {
"type": "integer",
"description": "The smallest number of locations the offer covers.",
"example": 8
},
"fromMonthlyPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price from which the offer starts, in euro cents.",
"example": 27900
},
"extraLocationPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price of each location beyond `minLocations`, in euro cents.",
"example": 2900
}
},
"required": [
"minLocations",
"fromMonthlyPriceCents",
"extraLocationPriceCents"
]
},
"contactEmail": {
"type": "string",
"description": "The address to write to about a larger plan or an individual contract.",
"example": "sales@example.com"
}
},
"required": [
"currentPlan",
"activeLocations"
]
}
},
"required": [
"type",
"title",
"status",
"code",
"detail"
],
"additionalProperties": false
}409 — The plan stored for the tenant covers no further active location. The `planLimit` member names the current plan with its maximum, the number of active locations, and either the smallest active plan above that number (`nextPlan`) or, when no plan is, the Enterprise offer (`enterpriseOffer`). This entry is the code's declaration; the location reactivate declares `LocationReactivateConflict`, which shares the status with `location_not_archived`.
{
"type": "urn:qms:problem:plan_location_limit_reached",
"title": "Plan Location Limit Reached",
"status": 409,
"code": "plan_location_limit_reached",
"detail": "The plan of the tenant covers no further active location.",
"planLimit": {
"currentPlan": {
"planId": "starter-plus",
"displayName": "Starter Plus",
"maxLocations": 3
},
"activeLocations": 3,
"nextPlan": {
"planId": "business",
"displayName": "Business",
"maxLocations": 5
},
"contactEmail": "sales@example.com"
}
}409 response schema
An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.
type · string · required
A URN identifying the problem kind, one per `code`.
title · string · required
A fixed English summary of the problem kind.
status · integer · required
The HTTP status code, repeated in the body.
code · string · required
The published slug this surface's error vocabulary uses.
detail · string · required
An English explanation of this occurrence.
errors · array · optional
One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.
Show nested fields
One offending field of a 400 field-validation refusal.
field · string · required
The member as THIS document spells it, which is not always what the same field is called inside the system.
code · string · required
The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`. Three of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.
blockers · array · optional
One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.
Show nested fields
One non-zero blocking category of a 409 refusal, and how many things it counted.
kind · string · required
What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.
Allowed values: "LOCATION", "TICKET", "APPOINTMENT", "TEMPLATE", "OPERATOR"
count · integer · required
How many of them there are. Always greater than zero.
checkCode · string · optional
The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.
planLimit · object · optional
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
Show nested fields
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
currentPlan · object · required
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
activeLocations · integer · required
The number of ACTIVE locations the tenant holds.
nextPlan · object · optional
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
enterpriseOffer · object · optional
The published Enterprise offer, named when no active plan covers the tenant's active location count.
Show nested fields
The published Enterprise offer, named when no active plan covers the tenant's active location count.
minLocations · integer · required
The smallest number of locations the offer covers.
fromMonthlyPriceCents · integer · int64 · required
The monthly price from which the offer starts, in euro cents.
extraLocationPriceCents · integer · int64 · required
The monthly price of each location beyond `minLocations`, in euro cents.
contactEmail · string · optional
The address to write to about a larger plan or an individual contract.
Raw JSON Schema
application/problem+json
{
"type": "object",
"description": "An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.",
"properties": {
"type": {
"type": "string",
"description": "A URN identifying the problem kind, one per `code`.",
"example": "urn:qms:problem:location_not_found"
},
"title": {
"type": "string",
"description": "A fixed English summary of the problem kind.",
"example": "Location Not Found"
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"example": 404
},
"code": {
"type": "string",
"description": "The published slug this surface's error vocabulary uses.",
"example": "location_not_found"
},
"detail": {
"type": "string",
"description": "An English explanation of this occurrence.",
"example": "No location was found for this identifier."
},
"errors": {
"type": "array",
"description": "One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.",
"items": {
"type": "object",
"description": "One offending field of a 400 field-validation refusal.",
"properties": {
"field": {
"type": "string",
"description": "The member as THIS document spells it, which is not always what the same field is called inside the system.",
"example": "defaultLocale"
},
"code": {
"type": "string",
"description": "The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`.\n\nThree of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.",
"example": "invalid_locale"
}
},
"required": [
"field",
"code"
]
}
},
"blockers": {
"type": "array",
"description": "One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.",
"items": {
"type": "object",
"description": "One non-zero blocking category of a 409 refusal, and how many things it counted.",
"properties": {
"kind": {
"type": "string",
"description": "What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.",
"enum": [
"LOCATION",
"TICKET",
"APPOINTMENT",
"TEMPLATE",
"OPERATOR"
],
"example": "TICKET"
},
"count": {
"type": "integer",
"description": "How many of them there are. Always greater than zero.",
"example": 3
}
},
"required": [
"kind",
"count"
]
}
},
"checkCode": {
"type": "string",
"description": "The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.",
"example": "unreachable"
},
"planLimit": {
"type": "object",
"description": "What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.",
"properties": {
"currentPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"activeLocations": {
"type": "integer",
"description": "The number of ACTIVE locations the tenant holds.",
"example": 3
},
"nextPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"enterpriseOffer": {
"type": "object",
"description": "The published Enterprise offer, named when no active plan covers the tenant's active location count.",
"properties": {
"minLocations": {
"type": "integer",
"description": "The smallest number of locations the offer covers.",
"example": 8
},
"fromMonthlyPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price from which the offer starts, in euro cents.",
"example": 27900
},
"extraLocationPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price of each location beyond `minLocations`, in euro cents.",
"example": 2900
}
},
"required": [
"minLocations",
"fromMonthlyPriceCents",
"extraLocationPriceCents"
]
},
"contactEmail": {
"type": "string",
"description": "The address to write to about a larger plan or an individual contract.",
"example": "sales@example.com"
}
},
"required": [
"currentPlan",
"activeLocations"
]
}
},
"required": [
"type",
"title",
"status",
"code",
"detail"
],
"additionalProperties": false
}500 — The request could not be processed. The body names no internal detail. A retry is safe on every read described here; on a create, an edit or a lifecycle transition a retry may or may not repeat a change that already committed, so read the resource back before retrying one of those.
{
"type": "urn:qms:problem:internal_error",
"title": "Internal Server Error",
"status": 500,
"code": "internal_error",
"detail": "The request could not be processed."
}500 response schema
An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.
type · string · required
A URN identifying the problem kind, one per `code`.
title · string · required
A fixed English summary of the problem kind.
status · integer · required
The HTTP status code, repeated in the body.
code · string · required
The published slug this surface's error vocabulary uses.
detail · string · required
An English explanation of this occurrence.
errors · array · optional
One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.
Show nested fields
One offending field of a 400 field-validation refusal.
field · string · required
The member as THIS document spells it, which is not always what the same field is called inside the system.
code · string · required
The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`. Three of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.
blockers · array · optional
One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.
Show nested fields
One non-zero blocking category of a 409 refusal, and how many things it counted.
kind · string · required
What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.
Allowed values: "LOCATION", "TICKET", "APPOINTMENT", "TEMPLATE", "OPERATOR"
count · integer · required
How many of them there are. Always greater than zero.
checkCode · string · optional
The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.
planLimit · object · optional
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
Show nested fields
What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.
currentPlan · object · required
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
activeLocations · integer · required
The number of ACTIVE locations the tenant holds.
nextPlan · object · optional
A plan named by a `plan_location_limit_reached` refusal.
Show nested fields
A plan named by a `plan_location_limit_reached` refusal.
planId · string · required
The plan's stable identifier.
displayName · string · required
The plan's name, not translated.
maxLocations · integer · required
The most ACTIVE locations the plan covers.
enterpriseOffer · object · optional
The published Enterprise offer, named when no active plan covers the tenant's active location count.
Show nested fields
The published Enterprise offer, named when no active plan covers the tenant's active location count.
minLocations · integer · required
The smallest number of locations the offer covers.
fromMonthlyPriceCents · integer · int64 · required
The monthly price from which the offer starts, in euro cents.
extraLocationPriceCents · integer · int64 · required
The monthly price of each location beyond `minLocations`, in euro cents.
contactEmail · string · optional
The address to write to about a larger plan or an individual contract.
Raw JSON Schema
application/problem+json
{
"type": "object",
"description": "An RFC 9457 problem document: `type`, `title`, `status`, `code` and `detail`, every one of those five always present. `errors`, `blockers`, `checkCode` and `planLimit` are the exceptions — each is scoped to one family of refusal and is ABSENT on every other document, which is why none is required below. `code` is the stable, machine-readable member; branch on it rather than on `title` or `detail`, which are English prose meant for a developer reading a log.",
"properties": {
"type": {
"type": "string",
"description": "A URN identifying the problem kind, one per `code`.",
"example": "urn:qms:problem:location_not_found"
},
"title": {
"type": "string",
"description": "A fixed English summary of the problem kind.",
"example": "Location Not Found"
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"example": 404
},
"code": {
"type": "string",
"description": "The published slug this surface's error vocabulary uses.",
"example": "location_not_found"
},
"detail": {
"type": "string",
"description": "An English explanation of this occurrence.",
"example": "No location was found for this identifier."
},
"errors": {
"type": "array",
"description": "One entry per offending field of a 400 field-validation refusal. Present on those alone, and ABSENT — not null, not an empty array — on every other problem document, including a field-validation refusal that can name no single field. Sorted by `field`, so two refusals over the same body produce the same document.",
"items": {
"type": "object",
"description": "One offending field of a 400 field-validation refusal.",
"properties": {
"field": {
"type": "string",
"description": "The member as THIS document spells it, which is not always what the same field is called inside the system.",
"example": "defaultLocale"
},
"code": {
"type": "string",
"description": "The published reason slug. Typed as a plain string rather than an enumeration, because the set is not closed — an integrity backstop can report a slug outside the published list. The values in use today are `required`, `too_long`, `invalid_format`, `invalid_timezone`, `invalid_locale`, `invalid_country`, `name_taken`, `code_taken`, `display_prefix_taken`, `out_of_range`, `not_in_catalogue`, `archived`, `duplicate`, `not_found`, `not_linked_to_location`, `inactive`, `language_not_in_catalogue`, `not_writable`, `password_too_short` and `password_breached`.\n\nThree of them are worth a sentence. `invalid_format` covers a value whose SHAPE is wrong — a window code that is not alphanumeric, a time that is not `HH:MM` — and, on the operating hours, the one fault that is a relation rather than a shape: a `closesAt` that is not after its `opensAt`, where both values are well formed and it is their ORDER that is refused. It also covers a member whose JSON type cannot be read — a string where a boolean belongs — reported under its path, e.g. `operatingHours[0].closed`. `not_found` means the member names something this tenant does not hold; it is the same word as the document-level `code` that answers an unserved path, at a different level and never with that status. `not_writable` is the operator invite, the operator profile edit and the visit-reason replace's own: a body member the request type declares no slot for, refused by NAME whether or not its value would have changed anything. `password_too_short` and `password_breached` are the operator create's own, under `initialPassword`.",
"example": "invalid_locale"
}
},
"required": [
"field",
"code"
]
}
},
"blockers": {
"type": "array",
"description": "One entry per non-zero blocking category of a 409 refusal that names what blocks it. Present on those alone, and ABSENT on every other problem document. A category with nothing to report is absent rather than present with a count of 0.",
"items": {
"type": "object",
"description": "One non-zero blocking category of a 409 refusal, and how many things it counted.",
"properties": {
"kind": {
"type": "string",
"description": "What kind of thing still depends on the entry — or, on a configuration refusal, on what the write would take away.",
"enum": [
"LOCATION",
"TICKET",
"APPOINTMENT",
"TEMPLATE",
"OPERATOR"
],
"example": "TICKET"
},
"count": {
"type": "integer",
"description": "How many of them there are. Always greater than zero.",
"example": 3
}
},
"required": [
"kind",
"count"
]
}
},
"checkCode": {
"type": "string",
"description": "The discovery-failure code of a `connection_check_failed` refusal: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Present on that refusal alone, and ABSENT on every other problem document.",
"example": "unreachable"
},
"planLimit": {
"type": "object",
"description": "What a `plan_location_limit_reached` refusal reports. Present on that refusal alone, and ABSENT on every other problem document. Exactly one of `nextPlan` and `enterpriseOffer` is present: `nextPlan` when an active plan above the active location count exists, `enterpriseOffer` when none does. `contactEmail` is absent when no contact address is configured.",
"properties": {
"currentPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"activeLocations": {
"type": "integer",
"description": "The number of ACTIVE locations the tenant holds.",
"example": 3
},
"nextPlan": {
"type": "object",
"description": "A plan named by a `plan_location_limit_reached` refusal.",
"properties": {
"planId": {
"type": "string",
"description": "The plan's stable identifier.",
"example": "business"
},
"displayName": {
"type": "string",
"description": "The plan's name, not translated.",
"example": "Business"
},
"maxLocations": {
"type": "integer",
"description": "The most ACTIVE locations the plan covers.",
"example": 5
}
},
"required": [
"planId",
"displayName",
"maxLocations"
]
},
"enterpriseOffer": {
"type": "object",
"description": "The published Enterprise offer, named when no active plan covers the tenant's active location count.",
"properties": {
"minLocations": {
"type": "integer",
"description": "The smallest number of locations the offer covers.",
"example": 8
},
"fromMonthlyPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price from which the offer starts, in euro cents.",
"example": 27900
},
"extraLocationPriceCents": {
"type": "integer",
"format": "int64",
"description": "The monthly price of each location beyond `minLocations`, in euro cents.",
"example": 2900
}
},
"required": [
"minLocations",
"fromMonthlyPriceCents",
"extraLocationPriceCents"
]
},
"contactEmail": {
"type": "string",
"description": "The address to write to about a larger plan or an individual contract.",
"example": "sales@example.com"
}
},
"required": [
"currentPlan",
"activeLocations"
]
}
},
"required": [
"type",
"title",
"status",
"code",
"detail"
],
"additionalProperties": false
}