Create a location template
Creates a template from a configuration document rather than by capturing one off a live location, and answers it linked to nothing.
Behavior and permissions
name and configuration are both required. configuration is required because the captured schedule is: the field rules ask for one operatingHours entry per day of the week, so a body omitting configuration altogether is answered 400 with an errors entry naming configuration.operatingHours and code required. Send the full seven-day schedule on a create.
A field fault inside the document is named with its whole path from the body's root — configuration.services[0].id, configuration.operatingHours.sat.closesAt — so the member named in errors is always the member the caller sent.
name must not be held by another template of the tenant.
Requires a credential issued by a tenant administrator.
Authorization · Example request · Parameters · Request body · Responses
POST/api/integration/v1/location-templates
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/location-templates" \
--header "Authorization: Api-Key $QMS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Branch standard",
"description": "The layout every high-street branch starts from.",
"configuration": {
"services": [
{
"id": "77777777-7777-4777-8777-777777777777",
"defaultDurationMinutes": 30
}
],
"windows": [
{
"id": "A1",
"floor": "Ground"
}
],
"operatingHours": [
{
"day": "MON",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "TUE",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "WED",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "THU",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "FRI",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "SAT",
"opensAt": null,
"closesAt": null,
"closed": true
},
{
"day": "SUN",
"opensAt": null,
"closesAt": null,
"closed": true
}
]
}
}'Parameters
None.
Request body
{
"name": "Branch standard",
"description": "The layout every high-street branch starts from.",
"configuration": {
"services": [
{
"id": "77777777-7777-4777-8777-777777777777",
"defaultDurationMinutes": 30
}
],
"windows": [
{
"id": "A1",
"floor": "Ground"
}
],
"operatingHours": [
{
"day": "MON",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "TUE",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "WED",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "THU",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "FRI",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "SAT",
"opensAt": null,
"closesAt": null,
"closed": true
},
{
"day": "SUN",
"opensAt": null,
"closesAt": null,
"closed": true
}
]
}
}Request schema
The template create body. `name` and `configuration` are both required: a template is born capturing a complete configuration, and the field rules ask for a full seven-day `operatingHours`, so a body without `configuration` is refused as a missing schedule rather than accepted as an empty template.
name · string · required
Must not be held by another template of the tenant.
description · string · optional
configuration · object · required
The `configuration` member of a template create or edit body: the location configuration write's own members minus `detach`, which is a location's link state and has no template counterpart. A body is accepted here exactly as it is accepted there — the same entry shapes, the same field rules, the same `errors` slugs. The EFFECT differs on one group. A `windows` array carried here REPLACES what the template captured, so a window it does not name is dropped from the template; the same array on a location upserts and drops nothing. `services` and `operatingHours` replace on both.
Show nested fields
The `configuration` member of a template create or edit body: the location configuration write's own members minus `detach`, which is a location's link state and has no template counterpart. A body is accepted here exactly as it is accepted there — the same entry shapes, the same field rules, the same `errors` slugs. The EFFECT differs on one group. A `windows` array carried here REPLACES what the template captured, so a window it does not name is dropped from the template; the same array on a location upserts and drops nothing. `services` and `operatingHours` replace on both.
services · array · optional
The services to capture. An entry omitting `defaultDurationMinutes` captures no override, which is what leaves a location taking the catalogue default.
Show nested fields
One entry of the `services` array.
id · string · required
The catalogue service to offer. It must name an ACTIVE service of this tenant's catalogue — one that does not is answered `not_in_catalogue`, an archived one `archived`, and the same id twice in the array `duplicate`.
defaultDurationMinutes · integer · optional
A per-location duration override for the service, 1 to 480 minutes. On the location configuration write it is this location's own duration; omitted, a service the location already offers keeps the duration it has, and a service being added takes the catalogue default. On a template's `configuration` the same member captures an override for every location the template is applied to; omitted, the template captures none, and each such location takes the catalogue default. This entry shape is shared by both bodies, which is why the two readings sit together here.
windows · array · optional
The windows to capture, replacing those captured before.
Show nested fields
One entry of the `windows` array, merged onto the window carrying the same `id`.
id · string · required
The window's short code, 1 to 20 alphanumeric characters, and the key the entry is merged by. A value of another shape is answered `invalid_format`; the same code twice in the array, `duplicate`.
floor · string · optional
A floor label of at most 20 characters. Omitted, an existing window's label is left as it is.
status · string · optional
Whether the window is in service. A window is retired by moving it to `INACTIVE`, never by deleting it, so the code it published stays recognisable.
Allowed values: "ACTIVE", "INACTIVE"
operatingHours · array · optional
The whole weekly schedule, all seven days, replacing the one captured before.
Show nested fields
One entry of the `operatingHours` array. On a closed day `opensAt` and `closesAt` are not read and may be omitted.
day · string · required
A day of the week, as the three-letter code the schedule is keyed by.
Allowed values: "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"
opensAt · string | null · optional
24-hour `HH:MM`. Required on a day whose `closed` is false, and null or omitted on a day whose `closed` is true.
closesAt · string | null · optional
24-hour `HH:MM`, strictly after `opensAt`. Required on a day whose `closed` is false, and null or omitted on a day whose `closed` is true.
closed · boolean · optional
Whether the location is shut that day. Omitted, the day is treated as open.
qrEntryMode · string · optional
How the location hands out its QR entry points: `SINGLE` is one code for the whole branch and the customer picks a service after scanning, `PER_SERVICE` is one code per service the location offers. This surface stores and applies the mode; it serves no QR artefact.
Allowed values: "SINGLE", "PER_SERVICE"
walkInNoShowGraceSeconds · integer · optional
Between 30 and 600 seconds.
appointmentNoShowGraceSeconds · integer · optional
Between 60 and 3600 seconds.
operatorNameVisible · boolean · optional
Raw JSON Schema
application/json
{
"type": "object",
"description": "The template create body. `name` and `configuration` are both required: a template is born capturing a complete configuration, and the field rules ask for a full seven-day `operatingHours`, so a body without `configuration` is refused as a missing schedule rather than accepted as an empty template.",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Must not be held by another template of the tenant.",
"example": "Branch standard"
},
"description": {
"type": "string",
"maxLength": 500,
"example": "The layout every high-street branch starts from."
},
"configuration": {
"type": "object",
"description": "The `configuration` member of a template create or edit body: the location configuration write's own members minus `detach`, which is a location's link state and has no template counterpart. A body is accepted here exactly as it is accepted there — the same entry shapes, the same field rules, the same `errors` slugs.\n\nThe EFFECT differs on one group. A `windows` array carried here REPLACES what the template captured, so a window it does not name is dropped from the template; the same array on a location upserts and drops nothing. `services` and `operatingHours` replace on both.",
"properties": {
"services": {
"type": "array",
"description": "The services to capture. An entry omitting `defaultDurationMinutes` captures no override, which is what leaves a location taking the catalogue default.",
"items": {
"type": "object",
"description": "One entry of the `services` array.",
"properties": {
"id": {
"type": "string",
"description": "The catalogue service to offer. It must name an ACTIVE service of this tenant's catalogue — one that does not is answered `not_in_catalogue`, an archived one `archived`, and the same id twice in the array `duplicate`.",
"example": "77777777-7777-4777-8777-777777777777"
},
"defaultDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 480,
"description": "A per-location duration override for the service, 1 to 480 minutes.\n\nOn the location configuration write it is this location's own duration; omitted, a service the location already offers keeps the duration it has, and a service being added takes the catalogue default. On a template's `configuration` the same member captures an override for every location the template is applied to; omitted, the template captures none, and each such location takes the catalogue default. This entry shape is shared by both bodies, which is why the two readings sit together here.",
"example": 20
}
},
"required": [
"id"
]
}
},
"windows": {
"type": "array",
"description": "The windows to capture, replacing those captured before.",
"items": {
"type": "object",
"description": "One entry of the `windows` array, merged onto the window carrying the same `id`.",
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9]{1,20}$",
"description": "The window's short code, 1 to 20 alphanumeric characters, and the key the entry is merged by. A value of another shape is answered `invalid_format`; the same code twice in the array, `duplicate`.",
"example": "A1"
},
"floor": {
"type": "string",
"maxLength": 20,
"description": "A floor label of at most 20 characters. Omitted, an existing window's label is left as it is.",
"example": "Ground"
},
"status": {
"type": "string",
"description": "Whether the window is in service. A window is retired by moving it to `INACTIVE`, never by deleting it, so the code it published stays recognisable.",
"enum": [
"ACTIVE",
"INACTIVE"
],
"example": "ACTIVE"
}
},
"required": [
"id"
]
}
},
"operatingHours": {
"type": "array",
"description": "The whole weekly schedule, all seven days, replacing the one captured before.",
"items": {
"type": "object",
"description": "One entry of the `operatingHours` array. On a closed day `opensAt` and `closesAt` are not read and may be omitted.",
"properties": {
"day": {
"type": "string",
"description": "A day of the week, as the three-letter code the schedule is keyed by.",
"enum": [
"MON",
"TUE",
"WED",
"THU",
"FRI",
"SAT",
"SUN"
],
"example": "MON"
},
"opensAt": {
"type": [
"string",
"null"
],
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
"description": "24-hour `HH:MM`. Required on a day whose `closed` is false, and null or omitted on a day whose `closed` is true.",
"example": "09:00"
},
"closesAt": {
"type": [
"string",
"null"
],
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
"description": "24-hour `HH:MM`, strictly after `opensAt`. Required on a day whose `closed` is false, and null or omitted on a day whose `closed` is true.",
"example": "18:00"
},
"closed": {
"type": "boolean",
"description": "Whether the location is shut that day. Omitted, the day is treated as open.",
"example": false
}
},
"required": [
"day"
]
}
},
"qrEntryMode": {
"type": "string",
"description": "How the location hands out its QR entry points: `SINGLE` is one code for the whole branch and the customer picks a service after scanning, `PER_SERVICE` is one code per service the location offers. This surface stores and applies the mode; it serves no QR artefact.",
"enum": [
"SINGLE",
"PER_SERVICE"
],
"example": "SINGLE"
},
"walkInNoShowGraceSeconds": {
"type": "integer",
"minimum": 30,
"maximum": 600,
"description": "Between 30 and 600 seconds.",
"example": 120
},
"appointmentNoShowGraceSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 3600,
"description": "Between 60 and 3600 seconds.",
"example": 900
},
"operatorNameVisible": {
"type": "boolean",
"example": true
}
}
}
},
"required": [
"name",
"configuration"
]
}Responses
201 — The template as created.
{
"id": "99999999-9999-4999-8999-999999999999",
"name": "Branch standard",
"description": "The layout every high-street branch starts from.",
"linkedLocationIds": [],
"configuration": {
"services": [
{
"id": "77777777-7777-4777-8777-777777777777",
"defaultDurationMinutes": 30
}
],
"windows": [
{
"id": "A1",
"floor": "Ground",
"status": "ACTIVE"
}
],
"operatingHours": [
{
"day": "MON",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "TUE",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "WED",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "THU",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "FRI",
"opensAt": "08:30",
"closesAt": "17:30",
"closed": false
},
{
"day": "SAT",
"opensAt": null,
"closesAt": null,
"closed": true
},
{
"day": "SUN",
"opensAt": null,
"closesAt": null,
"closed": true
}
],
"qrEntryMode": "SINGLE",
"walkInNoShowGraceSeconds": 120,
"appointmentNoShowGraceSeconds": 900,
"operatorNameVisible": true
}
}201 response schema
One location template: a named, reusable queue configuration that locations are provisioned from. Every member is always present.
id · string · required
name · string · required
Unique among the tenant's templates.
description · string | null · required
Free text, or null when none was given.
linkedLocationIds · array · required
The locations provisioned from this template, sorted, so that two reads of an unchanged set are byte-identical. May be empty.
Show nested fields
configuration · object · required
What a template captures: the location configuration document's members minus `template`, which a template has no counterpart for because a template is not provisioned from another template. The shapes are the location document's own. Service durations are effective values: the captured override when present, otherwise the catalogue default, resolved exactly as for a location configuration.
Show nested fields
What a template captures: the location configuration document's members minus `template`, which a template has no counterpart for because a template is not provisioned from another template. The shapes are the location document's own. Service durations are effective values: the captured override when present, otherwise the catalogue default, resolved exactly as for a location configuration.
services · array · required
Show nested fields
One service this location offers.
id · string · required
The catalogue service's own identifier, as the service read publishes it.
defaultDurationMinutes · integer · required
How long one appointment for this service takes AT THIS LOCATION — the resolved value, which is the location's own override where it has one and the catalogue's default otherwise. Never null here.
windows · array · required
Show nested fields
One service window of the location.
id · string · required
The window's own short code, the one printed above the desk — 1 to 20 alphanumeric characters, unique within the location. It is the key this surface merges a window by, not a server-generated identifier.
floor · string | null · required
A free-text floor label of at most 20 characters, or null when none is set.
status · string · required
Whether the window is in service. A window is retired by moving it to `INACTIVE`, never by deleting it, so the code it published stays recognisable.
Allowed values: "ACTIVE", "INACTIVE"
operatingHours · array · required
Seven entries, one per day of the week.
Show nested fields
One day of the weekly schedule.
day · string · required
A day of the week, as the three-letter code the schedule is keyed by.
Allowed values: "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"
opensAt · string | null · required
When the location opens that day, as 24-hour `HH:MM`. Null on a day whose `closed` is true.
closesAt · string | null · required
When it closes, as 24-hour `HH:MM`, and strictly after `opensAt`. Null on a day whose `closed` is true.
closed · boolean · required
Whether the location is shut that day.
qrEntryMode · string · required
How the location hands out its QR entry points: `SINGLE` is one code for the whole branch and the customer picks a service after scanning, `PER_SERVICE` is one code per service the location offers. This surface stores and applies the mode; it serves no QR artefact.
Allowed values: "SINGLE", "PER_SERVICE"
walkInNoShowGraceSeconds · integer · required
The EFFECTIVE value, resolved the same way the location document resolves its own, so the two can be compared as numbers. A template that captured no override therefore publishes the platform default, and writing this document back as a template body would pin that default as an override the template never held.
appointmentNoShowGraceSeconds · integer · required
The same, for an appointment-issued ticket.
operatorNameVisible · boolean · required
Raw JSON Schema
application/json
{
"type": "object",
"description": "One location template: a named, reusable queue configuration that locations are provisioned from. Every member is always present.",
"properties": {
"id": {
"type": "string",
"example": "99999999-9999-4999-8999-999999999999"
},
"name": {
"type": "string",
"description": "Unique among the tenant's templates.",
"example": "Branch standard"
},
"description": {
"type": [
"string",
"null"
],
"description": "Free text, or null when none was given.",
"example": "The layout every high-street branch starts from."
},
"linkedLocationIds": {
"type": "array",
"description": "The locations provisioned from this template, sorted, so that two reads of an unchanged set are byte-identical. May be empty.",
"items": {
"type": "string"
},
"example": [
"22222222-2222-4222-8222-222222222222"
]
},
"configuration": {
"type": "object",
"description": "What a template captures: the location configuration document's members minus `template`, which a template has no counterpart for because a template is not provisioned from another template.\n\nThe shapes are the location document's own. Service durations are effective values: the captured override when present, otherwise the catalogue default, resolved exactly as for a location configuration.",
"properties": {
"services": {
"type": "array",
"items": {
"type": "object",
"description": "One service this location offers.",
"properties": {
"id": {
"type": "string",
"description": "The catalogue service's own identifier, as the service read publishes it.",
"example": "77777777-7777-4777-8777-777777777777"
},
"defaultDurationMinutes": {
"type": "integer",
"description": "How long one appointment for this service takes AT THIS LOCATION — the resolved value, which is the location's own override where it has one and the catalogue's default otherwise. Never null here.",
"example": 15
}
},
"required": [
"id",
"defaultDurationMinutes"
]
}
},
"windows": {
"type": "array",
"items": {
"type": "object",
"description": "One service window of the location.",
"properties": {
"id": {
"type": "string",
"description": "The window's own short code, the one printed above the desk — 1 to 20 alphanumeric characters, unique within the location. It is the key this surface merges a window by, not a server-generated identifier.",
"example": "A1"
},
"floor": {
"type": [
"string",
"null"
],
"description": "A free-text floor label of at most 20 characters, or null when none is set.",
"example": "Ground"
},
"status": {
"type": "string",
"description": "Whether the window is in service. A window is retired by moving it to `INACTIVE`, never by deleting it, so the code it published stays recognisable.",
"enum": [
"ACTIVE",
"INACTIVE"
],
"example": "ACTIVE"
}
},
"required": [
"id",
"floor",
"status"
]
}
},
"operatingHours": {
"type": "array",
"description": "Seven entries, one per day of the week.",
"items": {
"type": "object",
"description": "One day of the weekly schedule.",
"properties": {
"day": {
"type": "string",
"description": "A day of the week, as the three-letter code the schedule is keyed by.",
"enum": [
"MON",
"TUE",
"WED",
"THU",
"FRI",
"SAT",
"SUN"
],
"example": "MON"
},
"opensAt": {
"type": [
"string",
"null"
],
"description": "When the location opens that day, as 24-hour `HH:MM`. Null on a day whose `closed` is true.",
"example": "09:00"
},
"closesAt": {
"type": [
"string",
"null"
],
"description": "When it closes, as 24-hour `HH:MM`, and strictly after `opensAt`. Null on a day whose `closed` is true.",
"example": "18:00"
},
"closed": {
"type": "boolean",
"description": "Whether the location is shut that day.",
"example": false
}
},
"required": [
"day",
"opensAt",
"closesAt",
"closed"
]
}
},
"qrEntryMode": {
"type": "string",
"description": "How the location hands out its QR entry points: `SINGLE` is one code for the whole branch and the customer picks a service after scanning, `PER_SERVICE` is one code per service the location offers. This surface stores and applies the mode; it serves no QR artefact.",
"enum": [
"SINGLE",
"PER_SERVICE"
],
"example": "SINGLE"
},
"walkInNoShowGraceSeconds": {
"type": "integer",
"description": "The EFFECTIVE value, resolved the same way the location document resolves its own, so the two can be compared as numbers. A template that captured no override therefore publishes the platform default, and writing this document back as a template body would pin that default as an override the template never held.",
"example": 120
},
"appointmentNoShowGraceSeconds": {
"type": "integer",
"description": "The same, for an appointment-issued ticket.",
"example": 900
},
"operatorNameVisible": {
"type": "boolean",
"example": true
}
},
"required": [
"services",
"windows",
"operatingHours",
"qrEntryMode",
"walkInNoShowGraceSeconds",
"appointmentNoShowGraceSeconds",
"operatorNameVisible"
]
}
},
"required": [
"id",
"name",
"description",
"linkedLocationIds",
"configuration"
]
}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
}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
}