API reference

Browse operations by resource. Expand an operation for a preview, or follow its link to a dedicated page with a request example, responses, and schemas. Integrations covers how to obtain a credential, how to present it, and what happens when a call is refused.

AuthenticationQueuesLocationsContractServicesBrandingTemplatesOtherSettings

Authentication

Open operation →

GETDescribe the credential presented on this request/api/integration/v1/whoami

Describe the credential presented on this request

Answers with the credential the request authenticated as, the tenant it belongs to and the locations it currently reaches. The reachable set is resolved on every call, so an assignment withdrawn in the console is reflected here immediately.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/whoami" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The credential, its tenant and the locations it reaches.

200 · Example

{
  "tenantId": "11111111-1111-4111-8111-111111111111",
  "tenantSubdomain": "your-tenant",
  "userId": "44444444-4444-4444-8444-444444444444",
  "credentialId": "55555555-5555-4555-8555-555555555555",
  "label": "Lobby display integration",
  "displayPrefix": "qms_EXAMPLEE",
  "expiresAt": "2027-01-31T09:00:00.000Z",
  "managementLevel": "LOCATION_MANAGER",
  "scopes": [
    "api",
    "queue:read"
  ],
  "locationIds": [
    "22222222-2222-4222-8222-222222222222"
  ]
}

200 response schema

What the caller learns about the credential it just presented.

tenantId · string · required

The tenant the credential belongs to.

tenantSubdomain · string | null · required

The tenant's subdomain, or null when the tenant record cannot be read on this request.

userId · string · required

The console user who issued the credential.

credentialId · string · required

The credential itself.

label · string · required

The label the credential was issued under.

displayPrefix · string · required

The leading characters of the secret, kept in clear so a credential can be recognised in the console without revealing it. The example is the leading characters of the example secret in `apiKeyAuth`, and is no more a working credential than that secret is.

expiresAt · string · required

When the credential stops authenticating.

managementLevel · string · required

The management level the credential acts with.

Allowed values: "TENANT_ADMIN", "LOCATION_MANAGER"

scopes · array · required

The credential scope set, sorted lexically.

Show nested fields

An open scope vocabulary. Values may be added within the current API major version. Clients must not reject values they do not know. Removing or renaming a value is a breaking change.

locationIds · array · required

The locations the credential reaches at this instant, sorted, so that two reads of an unchanged assignment set are byte-identical. May be empty.

Show nested fields

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "What the caller learns about the credential it just presented.",
  "properties": {
    "tenantId": {
      "type": "string",
      "description": "The tenant the credential belongs to.",
      "example": "11111111-1111-4111-8111-111111111111"
    },
    "tenantSubdomain": {
      "type": [
        "string",
        "null"
      ],
      "description": "The tenant's subdomain, or null when the tenant record cannot be read on this request.",
      "example": "your-tenant"
    },
    "userId": {
      "type": "string",
      "description": "The console user who issued the credential.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "credentialId": {
      "type": "string",
      "description": "The credential itself.",
      "example": "55555555-5555-4555-8555-555555555555"
    },
    "label": {
      "type": "string",
      "description": "The label the credential was issued under.",
      "example": "Lobby display integration"
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading characters of the secret, kept in clear so a credential can be recognised in the console without revealing it. The example is the leading characters of the example secret in `apiKeyAuth`, and is no more a working credential than that secret is.",
      "example": "qms_EXAMPLEE"
    },
    "expiresAt": {
      "type": "string",
      "description": "When the credential stops authenticating.",
      "example": "2027-01-31T09:00:00.000Z"
    },
    "managementLevel": {
      "type": "string",
      "description": "The management level the credential acts with.",
      "enum": [
        "TENANT_ADMIN",
        "LOCATION_MANAGER"
      ],
      "example": "LOCATION_MANAGER"
    },
    "scopes": {
      "type": "array",
      "description": "The credential scope set, sorted lexically.",
      "items": {
        "type": "string",
        "description": "An open scope vocabulary. Values may be added within the current API major version. Clients must not reject values they do not know. Removing or renaming a value is a breaking change."
      },
      "example": [
        "api",
        "queue:read"
      ]
    },
    "locationIds": {
      "type": "array",
      "description": "The locations the credential reaches at this instant, sorted, so that two reads of an unchanged assignment set are byte-identical. May be empty.",
      "items": {
        "type": "string"
      },
      "example": [
        "22222222-2222-4222-8222-222222222222"
      ]
    }
  },
  "required": [
    "tenantId",
    "tenantSubdomain",
    "userId",
    "credentialId",
    "label",
    "displayPrefix",
    "expiresAt",
    "managementLevel",
    "scopes",
    "locationIds"
  ]
}

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.

401 · Example

{
  "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
}

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.

500 · Example

{
  "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
}

Queues

Open operation →

GETRead a location's live queue/api/integration/v1/locations/{locationId}/queue

Read a location's live queue

The tickets a location is serving and the tickets waiting for it, as of the instant in `asOf`. A location the credential does not reach, a location belonging to another tenant and a location that does not exist are one and the same answer.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/queue" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's serving and waiting tickets.

200 · Example

{
  "location": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "City Centre"
  },
  "serving": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "number": "A014",
      "state": "SERVING",
      "channel": "WALK_IN",
      "service": {
        "id": "77777777-7777-4777-8777-777777777777",
        "name": "Account opening"
      },
      "client": {
        "displayName": "A. Client"
      },
      "queueEnteredAt": "2026-09-10T08:41:00.000Z",
      "estimatedWaitMinutes": null,
      "calledAt": "2026-09-10T08:52:00.000Z",
      "servingStartedAt": "2026-09-10T08:53:00.000Z",
      "window": {
        "id": "88888888-8888-4888-8888-888888888888",
        "label": "3"
      },
      "operator": {
        "id": "66666666-6666-4666-8666-666666666666",
        "name": "Operator One"
      },
      "closedAt": null
    }
  ],
  "waiting": [],
  "asOf": "2026-09-10T09:00:00.000Z"
}

200 response schema

A location's live queue at a single instant.

location · object · required

The location this queue belongs to.

Show nested fields

The location this queue belongs to.

id · string · required

name · string · required

serving · array · required

The tickets currently held by an operator, called or being served.

Show nested fields

One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.

id · string · required

number · string · required

The number shown to the customer.

state · string · required

The ticket's lifecycle state.

Allowed values: "WAITING", "CALLED", "SERVING", "COMPLETED", "CANCELLED", "NO_SHOW", "SKIPPED"

channel · string · required

How the ticket entered the queue.

Allowed values: "WALK_IN", "WEB_BOOKING", "MOBILE"

service · object · required

The service the ticket was issued for.

Show nested fields

The service the ticket was issued for.

id · string · required

name · string · required

client · object · required

The customer the ticket was issued to.

Show nested fields

The customer the ticket was issued to.

displayName · string | null · required

The name the customer gave, or null when they gave none.

queueEnteredAt · string · required

When the ticket joined the queue.

estimatedWaitMinutes · integer | null · required

The estimated wait in whole minutes. Non-null only while the ticket is waiting.

calledAt · string | null · required

When the ticket was called. Non-null only while an operator holds it.

servingStartedAt · string | null · required

When service began. Non-null only while the ticket is being served.

window · one of · required

The window the ticket was called to. Non-null only while an operator holds it.

Show nested fields

The window the ticket was called to. Non-null only while an operator holds it.

Option 1 · object

The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.

id · string | null · required

label · string · required

The window code shown to the customer.

Option 2 · null

operator · one of · required

The operator holding the ticket. Non-null only while an operator holds it.

Show nested fields

The operator holding the ticket. Non-null only while an operator holds it.

Option 1 · object

The operator holding the ticket. `id` is the operator profile, not a console user.

id · string · required

name · string | null · required

The operator's display name, or null when it is not published.

Option 2 · null

closedAt · string | null · required

When the ticket reached a terminal state. Non-null only once it has.

waiting · array · required

The tickets waiting, in the order the location will call them.

Show nested fields

One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.

id · string · required

number · string · required

The number shown to the customer.

state · string · required

The ticket's lifecycle state.

Allowed values: "WAITING", "CALLED", "SERVING", "COMPLETED", "CANCELLED", "NO_SHOW", "SKIPPED"

channel · string · required

How the ticket entered the queue.

Allowed values: "WALK_IN", "WEB_BOOKING", "MOBILE"

service · object · required

The service the ticket was issued for.

Show nested fields

The service the ticket was issued for.

id · string · required

name · string · required

client · object · required

The customer the ticket was issued to.

Show nested fields

The customer the ticket was issued to.

displayName · string | null · required

The name the customer gave, or null when they gave none.

queueEnteredAt · string · required

When the ticket joined the queue.

estimatedWaitMinutes · integer | null · required

The estimated wait in whole minutes. Non-null only while the ticket is waiting.

calledAt · string | null · required

When the ticket was called. Non-null only while an operator holds it.

servingStartedAt · string | null · required

When service began. Non-null only while the ticket is being served.

window · one of · required

The window the ticket was called to. Non-null only while an operator holds it.

Show nested fields

The window the ticket was called to. Non-null only while an operator holds it.

Option 1 · object

The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.

id · string | null · required

label · string · required

The window code shown to the customer.

Option 2 · null

operator · one of · required

The operator holding the ticket. Non-null only while an operator holds it.

Show nested fields

The operator holding the ticket. Non-null only while an operator holds it.

Option 1 · object

The operator holding the ticket. `id` is the operator profile, not a console user.

id · string · required

name · string | null · required

The operator's display name, or null when it is not published.

Option 2 · null

closedAt · string | null · required

When the ticket reached a terminal state. Non-null only once it has.

asOf · string · required

The instant this view was taken.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's live queue at a single instant.",
  "properties": {
    "location": {
      "type": "object",
      "description": "The location this queue belongs to.",
      "properties": {
        "id": {
          "type": "string",
          "example": "22222222-2222-4222-8222-222222222222"
        },
        "name": {
          "type": "string",
          "example": "City Centre"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "serving": {
      "type": "array",
      "description": "The tickets currently held by an operator, called or being served.",
      "items": {
        "type": "object",
        "description": "One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.",
        "properties": {
          "id": {
            "type": "string",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "number": {
            "type": "string",
            "description": "The number shown to the customer.",
            "example": "A014"
          },
          "state": {
            "type": "string",
            "description": "The ticket's lifecycle state.",
            "enum": [
              "WAITING",
              "CALLED",
              "SERVING",
              "COMPLETED",
              "CANCELLED",
              "NO_SHOW",
              "SKIPPED"
            ],
            "example": "SERVING"
          },
          "channel": {
            "type": "string",
            "description": "How the ticket entered the queue.",
            "enum": [
              "WALK_IN",
              "WEB_BOOKING",
              "MOBILE"
            ],
            "example": "WALK_IN"
          },
          "service": {
            "type": "object",
            "description": "The service the ticket was issued for.",
            "properties": {
              "id": {
                "type": "string",
                "example": "77777777-7777-4777-8777-777777777777"
              },
              "name": {
                "type": "string",
                "example": "Account opening"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "client": {
            "type": "object",
            "description": "The customer the ticket was issued to.",
            "properties": {
              "displayName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The name the customer gave, or null when they gave none.",
                "example": "A. Client"
              }
            },
            "required": [
              "displayName"
            ]
          },
          "queueEnteredAt": {
            "type": "string",
            "description": "When the ticket joined the queue.",
            "example": "2026-09-10T08:41:00.000Z"
          },
          "estimatedWaitMinutes": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The estimated wait in whole minutes. Non-null only while the ticket is waiting.",
            "example": 12
          },
          "calledAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the ticket was called. Non-null only while an operator holds it.",
            "example": "2026-09-10T08:52:00.000Z"
          },
          "servingStartedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When service began. Non-null only while the ticket is being served.",
            "example": "2026-09-10T08:53:00.000Z"
          },
          "window": {
            "description": "The window the ticket was called to. Non-null only while an operator holds it.",
            "oneOf": [
              {
                "type": "object",
                "description": "The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.",
                "properties": {
                  "id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "88888888-8888-4888-8888-888888888888"
                  },
                  "label": {
                    "type": "string",
                    "description": "The window code shown to the customer.",
                    "example": "3"
                  }
                },
                "required": [
                  "id",
                  "label"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "operator": {
            "description": "The operator holding the ticket. Non-null only while an operator holds it.",
            "oneOf": [
              {
                "type": "object",
                "description": "The operator holding the ticket. `id` is the operator profile, not a console user.",
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "66666666-6666-4666-8666-666666666666"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The operator's display name, or null when it is not published.",
                    "example": "Operator One"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "closedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the ticket reached a terminal state. Non-null only once it has.",
            "example": "2026-09-10T09:14:00.000Z"
          }
        },
        "required": [
          "id",
          "number",
          "state",
          "channel",
          "service",
          "client",
          "queueEnteredAt",
          "estimatedWaitMinutes",
          "calledAt",
          "servingStartedAt",
          "window",
          "operator",
          "closedAt"
        ]
      }
    },
    "waiting": {
      "type": "array",
      "description": "The tickets waiting, in the order the location will call them.",
      "items": {
        "type": "object",
        "description": "One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.",
        "properties": {
          "id": {
            "type": "string",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "number": {
            "type": "string",
            "description": "The number shown to the customer.",
            "example": "A014"
          },
          "state": {
            "type": "string",
            "description": "The ticket's lifecycle state.",
            "enum": [
              "WAITING",
              "CALLED",
              "SERVING",
              "COMPLETED",
              "CANCELLED",
              "NO_SHOW",
              "SKIPPED"
            ],
            "example": "SERVING"
          },
          "channel": {
            "type": "string",
            "description": "How the ticket entered the queue.",
            "enum": [
              "WALK_IN",
              "WEB_BOOKING",
              "MOBILE"
            ],
            "example": "WALK_IN"
          },
          "service": {
            "type": "object",
            "description": "The service the ticket was issued for.",
            "properties": {
              "id": {
                "type": "string",
                "example": "77777777-7777-4777-8777-777777777777"
              },
              "name": {
                "type": "string",
                "example": "Account opening"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "client": {
            "type": "object",
            "description": "The customer the ticket was issued to.",
            "properties": {
              "displayName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The name the customer gave, or null when they gave none.",
                "example": "A. Client"
              }
            },
            "required": [
              "displayName"
            ]
          },
          "queueEnteredAt": {
            "type": "string",
            "description": "When the ticket joined the queue.",
            "example": "2026-09-10T08:41:00.000Z"
          },
          "estimatedWaitMinutes": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The estimated wait in whole minutes. Non-null only while the ticket is waiting.",
            "example": 12
          },
          "calledAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the ticket was called. Non-null only while an operator holds it.",
            "example": "2026-09-10T08:52:00.000Z"
          },
          "servingStartedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When service began. Non-null only while the ticket is being served.",
            "example": "2026-09-10T08:53:00.000Z"
          },
          "window": {
            "description": "The window the ticket was called to. Non-null only while an operator holds it.",
            "oneOf": [
              {
                "type": "object",
                "description": "The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.",
                "properties": {
                  "id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "88888888-8888-4888-8888-888888888888"
                  },
                  "label": {
                    "type": "string",
                    "description": "The window code shown to the customer.",
                    "example": "3"
                  }
                },
                "required": [
                  "id",
                  "label"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "operator": {
            "description": "The operator holding the ticket. Non-null only while an operator holds it.",
            "oneOf": [
              {
                "type": "object",
                "description": "The operator holding the ticket. `id` is the operator profile, not a console user.",
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "66666666-6666-4666-8666-666666666666"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The operator's display name, or null when it is not published.",
                    "example": "Operator One"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "closedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the ticket reached a terminal state. Non-null only once it has.",
            "example": "2026-09-10T09:14:00.000Z"
          }
        },
        "required": [
          "id",
          "number",
          "state",
          "channel",
          "service",
          "client",
          "queueEnteredAt",
          "estimatedWaitMinutes",
          "calledAt",
          "servingStartedAt",
          "window",
          "operator",
          "closedAt"
        ]
      }
    },
    "asOf": {
      "type": "string",
      "description": "The instant this view was taken.",
      "example": "2026-09-10T09:00:00.000Z"
    }
  },
  "required": [
    "location",
    "serving",
    "waiting",
    "asOf"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETRead a single ticket/api/integration/v1/tickets/{ticketId}

Read a single ticket

A ticket in any state, terminal included, for as long as it is retained. A ticket at a location the credential does not reach, a ticket belonging to another tenant and a ticket that does not exist are one and the same answer.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/tickets/33333333-3333-4333-8333-333333333333" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
ticketId	path	yes	{"type":"string"}

ticketId: The ticket's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The ticket.

200 · Example

{
  "id": "33333333-3333-4333-8333-333333333333",
  "number": "A014",
  "state": "WAITING",
  "channel": "WEB_BOOKING",
  "service": {
    "id": "77777777-7777-4777-8777-777777777777",
    "name": "Account opening"
  },
  "client": {
    "displayName": null
  },
  "queueEnteredAt": "2026-09-10T08:41:00.000Z",
  "estimatedWaitMinutes": 12,
  "calledAt": null,
  "servingStartedAt": null,
  "window": null,
  "operator": null,
  "closedAt": null
}

200 response schema

One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.

id · string · required

number · string · required

The number shown to the customer.

state · string · required

The ticket's lifecycle state.

Allowed values: "WAITING", "CALLED", "SERVING", "COMPLETED", "CANCELLED", "NO_SHOW", "SKIPPED"

channel · string · required

How the ticket entered the queue.

Allowed values: "WALK_IN", "WEB_BOOKING", "MOBILE"

service · object · required

The service the ticket was issued for.

Show nested fields

The service the ticket was issued for.

id · string · required

name · string · required

client · object · required

The customer the ticket was issued to.

Show nested fields

The customer the ticket was issued to.

displayName · string | null · required

The name the customer gave, or null when they gave none.

queueEnteredAt · string · required

When the ticket joined the queue.

estimatedWaitMinutes · integer | null · required

The estimated wait in whole minutes. Non-null only while the ticket is waiting.

calledAt · string | null · required

When the ticket was called. Non-null only while an operator holds it.

servingStartedAt · string | null · required

When service began. Non-null only while the ticket is being served.

window · one of · required

The window the ticket was called to. Non-null only while an operator holds it.

Show nested fields

The window the ticket was called to. Non-null only while an operator holds it.

Option 1 · object

The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.

id · string | null · required

label · string · required

The window code shown to the customer.

Option 2 · null

operator · one of · required

The operator holding the ticket. Non-null only while an operator holds it.

Show nested fields

The operator holding the ticket. Non-null only while an operator holds it.

Option 1 · object

The operator holding the ticket. `id` is the operator profile, not a console user.

id · string · required

name · string | null · required

The operator's display name, or null when it is not published.

Option 2 · null

closedAt · string | null · required

When the ticket reached a terminal state. Non-null only once it has.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One ticket. Every member is always present; a member that does not apply to the ticket's current state is null rather than absent.",
  "properties": {
    "id": {
      "type": "string",
      "example": "33333333-3333-4333-8333-333333333333"
    },
    "number": {
      "type": "string",
      "description": "The number shown to the customer.",
      "example": "A014"
    },
    "state": {
      "type": "string",
      "description": "The ticket's lifecycle state.",
      "enum": [
        "WAITING",
        "CALLED",
        "SERVING",
        "COMPLETED",
        "CANCELLED",
        "NO_SHOW",
        "SKIPPED"
      ],
      "example": "SERVING"
    },
    "channel": {
      "type": "string",
      "description": "How the ticket entered the queue.",
      "enum": [
        "WALK_IN",
        "WEB_BOOKING",
        "MOBILE"
      ],
      "example": "WALK_IN"
    },
    "service": {
      "type": "object",
      "description": "The service the ticket was issued for.",
      "properties": {
        "id": {
          "type": "string",
          "example": "77777777-7777-4777-8777-777777777777"
        },
        "name": {
          "type": "string",
          "example": "Account opening"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "client": {
      "type": "object",
      "description": "The customer the ticket was issued to.",
      "properties": {
        "displayName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name the customer gave, or null when they gave none.",
          "example": "A. Client"
        }
      },
      "required": [
        "displayName"
      ]
    },
    "queueEnteredAt": {
      "type": "string",
      "description": "When the ticket joined the queue.",
      "example": "2026-09-10T08:41:00.000Z"
    },
    "estimatedWaitMinutes": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The estimated wait in whole minutes. Non-null only while the ticket is waiting.",
      "example": 12
    },
    "calledAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the ticket was called. Non-null only while an operator holds it.",
      "example": "2026-09-10T08:52:00.000Z"
    },
    "servingStartedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When service began. Non-null only while the ticket is being served.",
      "example": "2026-09-10T08:53:00.000Z"
    },
    "window": {
      "description": "The window the ticket was called to. Non-null only while an operator holds it.",
      "oneOf": [
        {
          "type": "object",
          "description": "The window the ticket was called to. The object exists whenever the ticket carries a window code, because that code is what the customer was told; `id` is null when the window record has since been renamed or removed.",
          "properties": {
            "id": {
              "type": [
                "string",
                "null"
              ],
              "example": "88888888-8888-4888-8888-888888888888"
            },
            "label": {
              "type": "string",
              "description": "The window code shown to the customer.",
              "example": "3"
            }
          },
          "required": [
            "id",
            "label"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "operator": {
      "description": "The operator holding the ticket. Non-null only while an operator holds it.",
      "oneOf": [
        {
          "type": "object",
          "description": "The operator holding the ticket. `id` is the operator profile, not a console user.",
          "properties": {
            "id": {
              "type": "string",
              "example": "66666666-6666-4666-8666-666666666666"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "The operator's display name, or null when it is not published.",
              "example": "Operator One"
            }
          },
          "required": [
            "id",
            "name"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "closedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the ticket reached a terminal state. Non-null only once it has.",
      "example": "2026-09-10T09:14:00.000Z"
    }
  },
  "required": [
    "id",
    "number",
    "state",
    "channel",
    "service",
    "client",
    "queueEnteredAt",
    "estimatedWaitMinutes",
    "calledAt",
    "servingStartedAt",
    "window",
    "operator",
    "closedAt"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No ticket was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:ticket_not_found",
  "title": "Ticket Not Found",
  "status": 404,
  "code": "ticket_not_found",
  "detail": "No ticket was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Locations

Open operation →

GETRead a service's bookable slots at a location/api/integration/v1/locations/{locationId}/services/{serviceId}/availability

Read a service's bookable slots at a location

The appointment slot grid of one service at one location over an inclusive date range, exactly as the customer booking flow derives it: one entry per slot, `available` false where the slot is already at capacity, no operator covers it, or its start is not after the current instant. A date the location does not open on, or that a closure matches, contributes no entry, and an archived location yields no entry for any date. Entries are sorted by `start` ascending. `from` and `to` are required calendar dates in `YYYY-MM-DD` form, `to` not before `from`, spanning at most 31 days inclusive; a range that breaks any of those is refused with 400 `validation_failed` and `errors` names the offending query member. A range that starts before today or ends after the last bookable date, both reckoned in the location's time zone, is refused whole with 422 `outside_booking_window` and is never truncated. The answer discloses availability and nothing else: no capacity, count, operator, customer or appointment. A location outside the credential's reach, in another tenant, deleted or nonexistent is one answer, 404 `location_not_found`; a service not offered at the location is 404 `service_not_found`.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/services/77777777-7777-4777-8777-777777777777/availability" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
serviceId	path	yes	{"type":"string"}
from	query	yes	{"type":"string","format":"date"}
to	query	yes	{"type":"string","format":"date"}

locationId: The location's opaque identifier.

serviceId: The service's opaque identifier.

from: The first date of the range, in the location's time zone.

to: The last date of the range, inclusive, in the location's time zone.

Request body

None. This operation carries no request body.

Responses

200 — The slot grid of the range, sorted by start.

200 · Example

{
  "items": [
    {
      "date": "2026-10-05",
      "start": "2026-10-05T06:00:00.000Z",
      "durationMinutes": 30,
      "available": true
    },
    {
      "date": "2026-10-05",
      "start": "2026-10-05T06:30:00.000Z",
      "durationMinutes": 30,
      "available": false
    }
  ]
}

200 response schema

The availability read's answer: an object carrying exactly one member, never a bare array. A range with no slot answers an empty list.

items · array · required

One entry per slot of the range, sorted by start ascending.

Show nested fields

One slot of the grid.

date · string · date · required

The slot's calendar date in the location's time zone.

start · string · date-time · required

The instant the slot starts.

durationMinutes · integer · required

The interval the slot grid is built from.

available · boolean · required

Whether a seat remains at the slot and it has not started.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The availability read's answer: an object carrying exactly one member, never a bare array. A range with no slot answers an empty list.",
  "additionalProperties": false,
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per slot of the range, sorted by start ascending.",
      "items": {
        "type": "object",
        "description": "One slot of the grid.",
        "additionalProperties": false,
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "The slot's calendar date in the location's time zone.",
            "example": "2026-10-05"
          },
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "The instant the slot starts.",
            "example": "2026-10-05T06:00:00.000Z"
          },
          "durationMinutes": {
            "type": "integer",
            "description": "The interval the slot grid is built from.",
            "example": 30
          },
          "available": {
            "type": "boolean",
            "description": "Whether a seat remains at the slot and it has not started.",
            "example": true
          }
        },
        "required": [
          "date",
          "start",
          "durationMinutes",
          "available"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — Either the location or the service was not found, told apart by `code`. `location_not_found`: the location is outside the credential's reach, in another tenant, deleted or nonexistent. `service_not_found`: the service is not offered at the location, is archived, belongs to another tenant or is nonexistent. Neither is ever a 403, so that the existence of another tenant's data cannot be probed.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · serviceNotFound

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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
}

422 — The requested range starts before today or ends after the last date the location's booking window allows, both reckoned in the location's time zone. The range is refused whole, never truncated.

422 · Example

{
  "type": "urn:qms:problem:outside_booking_window",
  "title": "Outside Booking Window",
  "status": 422,
  "code": "outside_booking_window",
  "detail": "The requested range reaches outside the location's booking window."
}

422 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's appointments for one day/api/integration/v1/locations/{locationId}/appointments

Read a location's appointments for one day

Every appointment at one location whose slot starts on one calendar day, reckoned in the location's time zone, in every status: `CONFIRMED`, `ACTIVATED`, `CANCELLED` and `NO_SHOW`. Entries are ordered by slot start ascending, then by booking creation time, then by identifier. A day with no appointment answers an empty list, not 404. Any valid date is accepted: the read is bounded by neither the booking window nor today. `date` is required and in `YYYY-MM-DD` form; a date that is missing or not in that form is refused with 400 `validation_failed` and `errors` names `date`. An entry carries the appointment's identifier, its slot start, its status, the service, the client and the ticket. `ticket` is present only once the appointment has been activated into a ticket and is otherwise null; `client.displayName` is null, because appointments currently carry no customer name. No contact detail, special request, preferred operator or deposit is ever returned. A location outside the credential's reach, in another tenant, deleted or nonexistent is one answer, 404 `location_not_found`.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/appointments" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
date	query	yes	{"type":"string","format":"date"}

locationId: The location's opaque identifier.

date: The day to read, in the location's time zone.

Request body

None. This operation carries no request body.

Responses

200 — The appointments of the day.

200 · Example

{
  "items": [
    {
      "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
      "slotStart": "2026-10-06T06:30:00.000Z",
      "status": "ACTIVATED",
      "service": {
        "id": "77777777-7777-4777-8777-777777777777",
        "name": "Account opening"
      },
      "client": {
        "displayName": null
      },
      "ticket": {
        "id": "33333333-3333-4333-8333-333333333333",
        "number": "A-007"
      }
    },
    {
      "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbc",
      "slotStart": "2026-10-06T07:00:00.000Z",
      "status": "CONFIRMED",
      "service": {
        "id": "77777777-7777-4777-8777-777777777777",
        "name": "Account opening"
      },
      "client": {
        "displayName": null
      },
      "ticket": null
    }
  ]
}

200 response schema

The appointments read's answer: an object carrying exactly one member, never a bare array. A day with no appointment answers an empty list.

items · array · required

One entry per appointment of the day, ordered by slot start, then booking creation time, then identifier.

Show nested fields

One appointment. Every member is always present; `ticket` and `client.displayName` are null rather than absent when they do not apply.

id · string · required

slotStart · string · date-time · required

The instant the slot starts.

status · string · required

Allowed values: "CONFIRMED", "ACTIVATED", "CANCELLED", "NO_SHOW"

service · object · required

The service the appointment was booked for.

Show nested fields

The service the appointment was booked for.

id · string · required

name · string · required

client · object · required

The customer the appointment belongs to.

Show nested fields

The customer the appointment belongs to.

displayName · string | null · required

The customer's full name for an appointment booked by an identified customer; null otherwise.

ticket · one of · required

The ticket the appointment was activated into. Null until then, and null when that ticket can no longer be read.

Show nested fields

The ticket the appointment was activated into. Null until then, and null when that ticket can no longer be read.

Option 1 · object

The ticket an activated appointment became.

id · string · required

number · string · required

The public ticket number.

Option 2 · null

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The appointments read's answer: an object carrying exactly one member, never a bare array. A day with no appointment answers an empty list.",
  "additionalProperties": false,
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per appointment of the day, ordered by slot start, then booking creation time, then identifier.",
      "items": {
        "type": "object",
        "description": "One appointment. Every member is always present; `ticket` and `client.displayName` are null rather than absent when they do not apply.",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "example": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
          },
          "slotStart": {
            "type": "string",
            "format": "date-time",
            "description": "The instant the slot starts.",
            "example": "2026-10-06T06:30:00.000Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "CONFIRMED",
              "ACTIVATED",
              "CANCELLED",
              "NO_SHOW"
            ],
            "example": "CONFIRMED"
          },
          "service": {
            "type": "object",
            "description": "The service the appointment was booked for.",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "example": "77777777-7777-4777-8777-777777777777"
              },
              "name": {
                "type": "string",
                "example": "Account opening"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "client": {
            "type": "object",
            "description": "The customer the appointment belongs to.",
            "additionalProperties": false,
            "properties": {
              "displayName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The customer's full name for an appointment booked by an identified customer; null otherwise.",
                "example": "Ona Jonaitiene"
              }
            },
            "required": [
              "displayName"
            ]
          },
          "ticket": {
            "description": "The ticket the appointment was activated into. Null until then, and null when that ticket can no longer be read.",
            "oneOf": [
              {
                "type": "object",
                "description": "The ticket an activated appointment became.",
                "additionalProperties": false,
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "33333333-3333-4333-8333-333333333333"
                  },
                  "number": {
                    "type": "string",
                    "description": "The public ticket number.",
                    "example": "A-007"
                  }
                },
                "required": [
                  "id",
                  "number"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "slotStart",
          "status",
          "service",
          "client",
          "ticket"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETList the locations this credential reaches/api/integration/v1/locations

List the locations this credential reaches

Every location the credential reaches, sorted by name ascending. Archived locations are returned alongside active ones and told apart by `status`; a location outside the credential's reach is absent rather than refused, so this read never answers 404. The answer is always the object `{"items": [...]}`, never a bare array, and it is never paginated — every element inside the credential's reach is returned. The operation declares no query parameter, and one supplied anyway changes neither the status nor the body.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The locations the credential reaches, sorted by name.

200 · Example

{
  "items": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "City Centre",
      "street": "Gedimino pr. 1",
      "city": "Vilnius",
      "postalCode": "01103",
      "country": "LT",
      "timezone": "Europe/Vilnius",
      "defaultLocale": "EN",
      "status": "ACTIVE"
    }
  ]
}

200 response schema

The location collection read's answer: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per location the credential reaches, sorted by name.

Show nested fields

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": "The location collection read's answer: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per location the credential reaches, sorted by name.",
      "items": {
        "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"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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.

500 · Example

{
  "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
}

Open operation →

POSTCreate a location/api/integration/v1/locations

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. `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

• 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

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

Example 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.

201 · Example

{
  "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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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`.

409 · Example

{
  "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.

500 · Example

{
  "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
}

Open operation →

GETRead a single location/api/integration/v1/locations/{locationId}

Read a single location

One location the credential reaches, active or archived. A location the credential does not reach, a location belonging to another tenant, a permanently deleted location, and a path segment that is not an identifier at all are one and the same answer.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location.

200 · Example

{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "City Centre",
  "street": "Gedimino pr. 1",
  "city": "Vilnius",
  "postalCode": "01103",
  "country": "LT",
  "timezone": "Europe/Vilnius",
  "defaultLocale": "EN",
  "status": "ACTIVE"
}

200 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"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHEdit a location/api/integration/v1/locations/{locationId}

Edit a location

A partial edit: a member absent from the body is left unchanged, and a member present replaces the stored value. Sending a location its own current name is accepted — the name uniqueness rule compares against the other active locations only. Requires a credential issued by a tenant administrator.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Riverside Branch North"
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "name": "Riverside Branch North"
}

Request schema

The location edit body. Every member is optional and one left out is left unchanged; a member sent replaces the stored value and is validated exactly as it is on the create. A member sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged — so no member can be cleared through this operation.

name · string · optional

street · string · optional

city · string · optional

postalCode · string · optional

country · string · optional

An ISO 3166-1 alpha-2 country code.

timezone · string · optional

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`. The location's current value sent back unchanged is accepted as it stands.

defaultLocale · string · optional

The location's default language, spelled as on the entry.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The location edit body. Every member is optional and one left out is left unchanged; a member sent replaces the stored value and is validated exactly as it is on the create. A member sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged — so no member can be cleared through this operation.",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "example": "Riverside Branch North"
    },
    "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`. The location's current value sent back unchanged is accepted as it stands.",
      "example": "Europe/Vilnius"
    },
    "defaultLocale": {
      "type": "string",
      "description": "The location's default language, spelled as on the entry.",
      "example": "EN"
    }
  }
}

Responses

200 — The location as it stands after the edit.

200 · Example

{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Riverside Branch North",
  "street": "Gedimino pr. 1",
  "city": "Vilnius",
  "postalCode": "01103",
  "country": "LT",
  "timezone": "Europe/Vilnius",
  "defaultLocale": "EN",
  "status": "ACTIVE"
}

200 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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

POSTArchive a location/api/integration/v1/locations/{locationId}/archive

Archive a location

Moves an active location to `status` `ARCHIVED` and answers the updated location. The request carries no body. Two refusals share the 409: a location that is already archived cannot transition at all and is answered `location_already_archived`, and that guard is evaluated before anything is counted; a location still holding open work is answered `archive_blocked` with one `blockers` entry per non-zero category. Archiving through this API cancels no appointment: an appointment still holding a future slot is counted as a blocker and refuses the archive, and is never cancelled by it. Cancelling it is what clears the block — a cancelled appointment stops counting, however far in the future its slot was.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/archive" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location, now archived.

200 · Example

{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "City Centre",
  "street": "Gedimino pr. 1",
  "city": "Vilnius",
  "postalCode": "01103",
  "country": "LT",
  "timezone": "Europe/Vilnius",
  "defaultLocale": "EN",
  "status": "ARCHIVED"
}

200 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"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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 location archive was refused. Two codes share this status: `location_already_archived` when the location cannot transition at all, and `archive_blocked` when it still holds open work, with one `blockers` entry per non-zero category. The transition guard is evaluated first, so an already-archived location is never answered `archive_blocked` about unrelated stale queue state. Branch on `code`.

409 · locationAlreadyArchived

{
  "type": "urn:qms:problem:location_already_archived",
  "title": "Location Already Archived",
  "status": 409,
  "code": "location_already_archived",
  "detail": "The location is already archived."
}

409 · archiveBlocked

{
  "type": "urn:qms:problem:archive_blocked",
  "title": "Archive Blocked",
  "status": 409,
  "code": "archive_blocked",
  "detail": "The entry cannot be archived while something still depends on it.",
  "blockers": [
    {
      "kind": "TICKET",
      "count": 3
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

POSTReactivate an archived location/api/integration/v1/locations/{locationId}/reactivate

Reactivate an archived location

Moves an archived location back to `status` `ACTIVE` and answers the updated location. The request carries no body. A location that is not archived is answered 409 `location_not_archived`; 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; a location whose name has since been taken by another active location is answered 400 with an `errors` entry naming `name`. The checks run in that order, so the first one that applies is the answer.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/reactivate" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location, now active.

200 · Example

{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "City Centre",
  "street": "Gedimino pr. 1",
  "city": "Vilnius",
  "postalCode": "01103",
  "country": "LT",
  "timezone": "Europe/Vilnius",
  "defaultLocale": "EN",
  "status": "ACTIVE"
}

200 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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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 location reactivate was refused. Two codes share this status: `location_not_archived` when the location cannot transition at all, and `plan_location_limit_reached` when the tenant's plan covers no further active location. The transition guard is evaluated first, so a location that is not archived is never answered about the plan. Branch on `code`.

409 · locationNotArchived

{
  "type": "urn:qms:problem:location_not_archived",
  "title": "Location Not Archived",
  "status": 409,
  "code": "location_not_archived",
  "detail": "The location is not archived."
}

409 · planLocationLimitReached

{
  "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.

500 · Example

{
  "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
}

Open operation →

PATCHSet a location's time zone/api/integration/v1/locations/{locationId}/timezone

Set a location's time zone

Sets the time zone every location-local date and time of the location is read in, and answers the location. The value is a region identifier of the IANA tz database that the platform supports, such as Europe/Vilnius; an offset form such as +02:00 or UTC+2, a non-region identifier such as UTC, Etc/GMT+2 or US/Eastern, or a value with surrounding spaces, is refused with `invalid_timezone` and nothing is written. An absent or blank value is answered with code `required`. Sending the location its current time zone changes nothing. A credential issued by a tenant administrator or by a location manager may call it; a location manager's credential reaches only the locations they are assigned to.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/timezone" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "timezone": "Asia/Kolkata"
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "timezone": "Asia/Kolkata"
}

Request schema

The time zone write body. Its one member is required; an absent, null or blank value is answered as an `errors` entry with code `required`.

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`.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The time zone write body. Its one member is required; an absent, null or blank value is answered as an `errors` entry with code `required`.",
  "properties": {
    "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": "Asia/Kolkata"
    }
  },
  "required": [
    "timezone"
  ]
}

Responses

200 — The location as it stands after the change.

200 · Example

{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "City Centre",
  "street": "Gedimino pr. 1",
  "city": "Vilnius",
  "postalCode": "01103",
  "country": "LT",
  "timezone": "Asia/Kolkata",
  "defaultLocale": "EN",
  "status": "ACTIVE"
}

200 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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's queue configuration/api/integration/v1/locations/{locationId}/configuration

Read a location's queue configuration

Every queue-configuration field of one location, as a single document: the template the location is provisioned from, the services it offers, its service windows, its weekly operating hours, its QR entry mode, the two no-show grace windows and whether operator names are shown. A location the credential does not reach, a location belonging to another tenant, a permanently deleted location, and a path segment that is not an identifier at all are one and the same answer. `operatingHours` always carries exactly seven entries, one per day, whether the location opens that day or not. Two groups of member are RESOLVED here rather than stored. A `services[].defaultDurationMinutes` is the duration in force at this location, and the two grace members carry the effective value the platform default supplies when the location stores no override. This document is therefore not a request body: writing it back unchanged materialises per-service overrides and grace values nothing had stored. That holds for a template create or edit, which would pin values the template never held — and equally for this location's own `PATCH`, where every `services[].defaultDurationMinutes` you echo back becomes an explicit per-service override that stops following the catalogue default. Send only the members you mean to pin.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/configuration" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's queue configuration.

200 · Example

{
  "template": {
    "id": "99999999-9999-4999-8999-999999999999",
    "name": "Branch standard"
  },
  "services": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "defaultDurationMinutes": 15
    }
  ],
  "windows": [
    {
      "id": "A1",
      "floor": "Ground",
      "status": "ACTIVE"
    }
  ],
  "operatingHours": [
    {
      "day": "MON",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "TUE",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "WED",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "THU",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "FRI",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "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
}

200 response schema

One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent. The document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.

template · one of · required

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Show nested fields

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Option 1 · object

The template a location is provisioned from, named so it can be shown without a second read.

id · string · required

name · string · required

Option 2 · null

services · array · required

The services this location offers, each with the duration in force here.

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

The location's service windows, active and inactive alike.

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

The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.

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

How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.

appointmentNoShowGraceSeconds · integer · required

The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.

operatorNameVisible · boolean · required

Whether the operator's name is shown to the customer at this location.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent.\n\nThe document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.",
  "properties": {
    "template": {
      "description": "The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.",
      "oneOf": [
        {
          "type": "object",
          "description": "The template a location is provisioned from, named so it can be shown without a second read.",
          "properties": {
            "id": {
              "type": "string",
              "example": "99999999-9999-4999-8999-999999999999"
            },
            "name": {
              "type": "string",
              "example": "Branch standard"
            }
          },
          "required": [
            "id",
            "name"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "services": {
      "type": "array",
      "description": "The services this location offers, each with the duration in force here.",
      "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",
      "description": "The location's service windows, active and inactive alike.",
      "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": "The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.",
      "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": "How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.",
      "example": 120
    },
    "appointmentNoShowGraceSeconds": {
      "type": "integer",
      "description": "The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.",
      "example": 900
    },
    "operatorNameVisible": {
      "type": "boolean",
      "description": "Whether the operator's name is shown to the customer at this location.",
      "example": true
    }
  },
  "required": [
    "template",
    "services",
    "windows",
    "operatingHours",
    "qrEntryMode",
    "walkInNoShowGraceSeconds",
    "appointmentNoShowGraceSeconds",
    "operatorNameVisible"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHWrite a location's queue configuration/api/integration/v1/locations/{locationId}/configuration

Write a location's queue configuration

A partial write: a member absent from the body is left alone, and a member present replaces what is stored. The answer is the whole configuration document as it stands after the write, exactly as the read returns it. The three collections are not written the same way. `services` REPLACES what the location holds — a service not named in the array is removed. `operatingHours` replaces the whole week and must name all seven days: an array that does not is refused as an `errors` entry naming `operatingHours` with code `required`, so no day is ever removed by omission. `windows` UPSERTS: an entry is merged onto the window carrying the same `id`, a `id` the location does not hold yet creates a window `ACTIVE`, and a window not named is left untouched rather than deleted. Retiring a window is therefore an entry naming it with `status` `INACTIVE`, never its absence. Nothing is written on any refusal, whichever member caused it: the field rules, the two state guards and the template-link guard are all evaluated before the first group is written. `template` is not a member of the body. A location's link is moved by the apply-template operation and cut by this operation's `detach`, never set here directly. `detach` is admission and nothing else. On a location linked to a template, a body that writes any captured field without `detach` `true` is refused 409 `location_linked_to_template`; with it, the write proceeds and the link is cut as part of writing. A body carrying `detach` `true` AND no captured field writes nothing, so it answers 200 with the link still in place — `detach` alone does not unlink. Requires a credential whose reach includes the location. Both a tenant administrator's and a location manager's credential reach this operation; a location outside the credential's reach is the 404, never a 403.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/configuration" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "services": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "defaultDurationMinutes": 20
    }
  ],
  "windows": [
    {
      "id": "A1",
      "floor": "Ground",
      "status": "ACTIVE"
    }
  ],
  "walkInNoShowGraceSeconds": 180,
  "detach": true
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "services": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "defaultDurationMinutes": 20
    }
  ],
  "windows": [
    {
      "id": "A1",
      "floor": "Ground",
      "status": "ACTIVE"
    }
  ],
  "walkInNoShowGraceSeconds": 180,
  "detach": true
}

Request schema

The configuration write body. Every member is optional; one left out is left alone, and one sent as JSON `null` is indistinguishable from an absent one, so no member can be cleared through this operation. `services` and `operatingHours` replace what the location holds. `windows` upserts by `id` and deletes nothing. `template` is not a member: see `detach`.

services · array · optional

The services the location is to offer, replacing the current set. A service the location holds today and this array does not name is removed — which is refused while it still holds open work.

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

Windows to create or merge, by `id`. A window the location holds and this array does not name is left exactly as it is; retiring one is an entry naming it with `status` `INACTIVE`.

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, replacing the current one. All seven days must be present when this member is sent; a missing day is answered as an `errors` entry naming `operatingHours` with code `required`.

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; outside that it is answered `out_of_range`.

appointmentNoShowGraceSeconds · integer · optional

Between 60 and 3600 seconds; outside that it is answered `out_of_range`.

operatorNameVisible · boolean · optional

detach · boolean · optional

The caller's acknowledgement that this write may break the location's template link. It admits the write and does nothing else: on a linked location a body writing any captured field without it is refused `location_linked_to_template`, and a body carrying it with no captured field writes nothing and leaves the link in place.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The configuration write body. Every member is optional; one left out is left alone, and one sent as JSON `null` is indistinguishable from an absent one, so no member can be cleared through this operation.\n\n`services` and `operatingHours` replace what the location holds. `windows` upserts by `id` and deletes nothing. `template` is not a member: see `detach`.",
  "properties": {
    "services": {
      "type": "array",
      "description": "The services the location is to offer, replacing the current set. A service the location holds today and this array does not name is removed — which is refused while it still holds open work.",
      "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": "Windows to create or merge, by `id`. A window the location holds and this array does not name is left exactly as it is; retiring one is an entry naming it with `status` `INACTIVE`.",
      "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, replacing the current one. All seven days must be present when this member is sent; a missing day is answered as an `errors` entry naming `operatingHours` with code `required`.",
      "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; outside that it is answered `out_of_range`.",
      "example": 180
    },
    "appointmentNoShowGraceSeconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 3600,
      "description": "Between 60 and 3600 seconds; outside that it is answered `out_of_range`.",
      "example": 900
    },
    "operatorNameVisible": {
      "type": "boolean",
      "example": true
    },
    "detach": {
      "type": "boolean",
      "description": "The caller's acknowledgement that this write may break the location's template link. It admits the write and does nothing else: on a linked location a body writing any captured field without it is refused `location_linked_to_template`, and a body carrying it with no captured field writes nothing and leaves the link in place.",
      "example": true
    }
  }
}

Responses

200 — The location's queue configuration after the write.

200 · Example

{
  "template": null,
  "services": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "defaultDurationMinutes": 20
    }
  ],
  "windows": [
    {
      "id": "A1",
      "floor": "Ground",
      "status": "ACTIVE"
    }
  ],
  "operatingHours": [
    {
      "day": "MON",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "TUE",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "WED",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "THU",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "FRI",
      "opensAt": "09:00",
      "closesAt": "18:00",
      "closed": false
    },
    {
      "day": "SAT",
      "opensAt": null,
      "closesAt": null,
      "closed": true
    },
    {
      "day": "SUN",
      "opensAt": null,
      "closesAt": null,
      "closed": true
    }
  ],
  "qrEntryMode": "SINGLE",
  "walkInNoShowGraceSeconds": 180,
  "appointmentNoShowGraceSeconds": 900,
  "operatorNameVisible": true
}

200 response schema

One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent. The document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.

template · one of · required

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Show nested fields

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Option 1 · object

The template a location is provisioned from, named so it can be shown without a second read.

id · string · required

name · string · required

Option 2 · null

services · array · required

The services this location offers, each with the duration in force here.

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

The location's service windows, active and inactive alike.

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

The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.

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

How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.

appointmentNoShowGraceSeconds · integer · required

The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.

operatorNameVisible · boolean · required

Whether the operator's name is shown to the customer at this location.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent.\n\nThe document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.",
  "properties": {
    "template": {
      "description": "The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.",
      "oneOf": [
        {
          "type": "object",
          "description": "The template a location is provisioned from, named so it can be shown without a second read.",
          "properties": {
            "id": {
              "type": "string",
              "example": "99999999-9999-4999-8999-999999999999"
            },
            "name": {
              "type": "string",
              "example": "Branch standard"
            }
          },
          "required": [
            "id",
            "name"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "services": {
      "type": "array",
      "description": "The services this location offers, each with the duration in force here.",
      "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",
      "description": "The location's service windows, active and inactive alike.",
      "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": "The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.",
      "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": "How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.",
      "example": 120
    },
    "appointmentNoShowGraceSeconds": {
      "type": "integer",
      "description": "The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.",
      "example": 900
    },
    "operatorNameVisible": {
      "type": "boolean",
      "description": "Whether the operator's name is shown to the customer at this location.",
      "example": true
    }
  },
  "required": [
    "template",
    "services",
    "windows",
    "operatingHours",
    "qrEntryMode",
    "walkInNoShowGraceSeconds",
    "appointmentNoShowGraceSeconds",
    "operatorNameVisible"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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 configuration write was refused, and nothing was written. Three codes share this status: `location_linked_to_template` when the location is still provisioned from a template and the body carried no `detach` `true`; `service_removal_blocked` when the write would drop a service that still holds a non-terminal ticket or a future appointment, with one `blockers` entry per non-zero category; and `window_deactivation_blocked` when it would set a window `INACTIVE` while operators are still assigned to it, with one `blockers` entry counting them. The two state guards are evaluated before the link guard, so a linked location whose body would also strand open work is told about the work. Branch on `code`.

409 · locationLinkedToTemplate

{
  "type": "urn:qms:problem:location_linked_to_template",
  "title": "Location Linked To Template",
  "status": 409,
  "code": "location_linked_to_template",
  "detail": "The location is provisioned from a template; send detach true to write its configuration directly."
}

409 · serviceRemovalBlocked

{
  "type": "urn:qms:problem:service_removal_blocked",
  "title": "Service Removal Blocked",
  "status": 409,
  "code": "service_removal_blocked",
  "detail": "A service cannot be removed while something still depends on it.",
  "blockers": [
    {
      "kind": "TICKET",
      "count": 3
    }
  ]
}

409 · windowDeactivationBlocked

{
  "type": "urn:qms:problem:window_deactivation_blocked",
  "title": "Window Deactivation Blocked",
  "status": 409,
  "code": "window_deactivation_blocked",
  "detail": "A window cannot be deactivated while an operator is still assigned to it.",
  "blockers": [
    {
      "kind": "OPERATOR",
      "count": 2
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

POSTApply a location template to a location/api/integration/v1/locations/{locationId}/configuration/apply-template

Apply a location template to a location

Overwrites every captured field of the location from the named template's snapshot and links the location to it. The answer is the location's configuration document as it stands afterwards, with `template` naming the template just applied. The overwrite is total for the captured groups: the location's services, windows and operating hours become the template's, and a window the template does not capture is removed rather than left behind. A location already linked to another template is relinked; no `detach` is needed and none is a member of this body. `templateId` is required. A body omitting it, or carrying it blank, is answered 400 with an `errors` entry naming `templateId` and code `required`. A `templateId` that is present but names no template of this tenant — another tenant's, a deleted one, or a value this surface could not have issued — is answered 404 `template_not_found`, one answer for all three. The apply is refused 409 `template_apply_blocked` when it would drop a service that still holds a non-terminal ticket, with one `blockers` entry counting those tickets. Nothing is written when it is. Requires a credential issued by a tenant administrator. The location's reach is checked before the body is read, so a location outside the credential's reach never reveals whether the named template exists.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/configuration/apply-template" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "templateId": "99999999-9999-4999-8999-999999999999"
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "templateId": "99999999-9999-4999-8999-999999999999"
}

Request schema

The apply-template body: the template to apply, and nothing else.

templateId · string · required

The template whose snapshot is written over the location's configuration. Required; absent or blank is answered 400 `validation_failed` naming this member, while a value naming no template of this tenant is answered 404 `template_not_found`.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The apply-template body: the template to apply, and nothing else.",
  "properties": {
    "templateId": {
      "type": "string",
      "description": "The template whose snapshot is written over the location's configuration. Required; absent or blank is answered 400 `validation_failed` naming this member, while a value naming no template of this tenant is answered 404 `template_not_found`.",
      "example": "99999999-9999-4999-8999-999999999999"
    }
  },
  "required": [
    "templateId"
  ]
}

Responses

200 — The location's configuration, as the template left it.

200 · Example

{
  "template": {
    "id": "99999999-9999-4999-8999-999999999999",
    "name": "Branch standard"
  },
  "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
}

200 response schema

One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent. The document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.

template · one of · required

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Show nested fields

The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.

Option 1 · object

The template a location is provisioned from, named so it can be shown without a second read.

id · string · required

name · string · required

Option 2 · null

services · array · required

The services this location offers, each with the duration in force here.

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

The location's service windows, active and inactive alike.

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

The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.

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

How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.

appointmentNoShowGraceSeconds · integer · required

The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.

operatorNameVisible · boolean · required

Whether the operator's name is shown to the customer at this location.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One location's queue configuration. Every member is always present; a member that does not apply is null rather than absent.\n\nThe document holds no name for anything it references: a service is its catalogue identifier, and the service's name is read from the service catalogue. The only name here is the linked template's, because a template has no read of its own a location manager can reach.",
  "properties": {
    "template": {
      "description": "The template this location is provisioned from, or null when it is independent. Read-only on the configuration write: the link is moved by the apply-template operation and cut by that write's `detach`.",
      "oneOf": [
        {
          "type": "object",
          "description": "The template a location is provisioned from, named so it can be shown without a second read.",
          "properties": {
            "id": {
              "type": "string",
              "example": "99999999-9999-4999-8999-999999999999"
            },
            "name": {
              "type": "string",
              "example": "Branch standard"
            }
          },
          "required": [
            "id",
            "name"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "services": {
      "type": "array",
      "description": "The services this location offers, each with the duration in force here.",
      "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",
      "description": "The location's service windows, active and inactive alike.",
      "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": "The weekly schedule: exactly seven entries, one per day of the week, whether the location opens that day or not.",
      "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": "How long a called walk-in ticket is held before it may be marked a no-show. The EFFECTIVE value: a location storing no override publishes the platform default rather than null. Between 30 and 600 seconds on a write.",
      "example": 120
    },
    "appointmentNoShowGraceSeconds": {
      "type": "integer",
      "description": "The same, for a ticket issued from an appointment. Between 60 and 3600 seconds on a write.",
      "example": 900
    },
    "operatorNameVisible": {
      "type": "boolean",
      "description": "Whether the operator's name is shown to the customer at this location.",
      "example": true
    }
  },
  "required": [
    "template",
    "services",
    "windows",
    "operatingHours",
    "qrEntryMode",
    "walkInNoShowGraceSeconds",
    "appointmentNoShowGraceSeconds",
    "operatorNameVisible"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — The apply named something this credential cannot see. Two codes share this status: `location_not_found` for the path's location, and `template_not_found` for the body's `templateId`. The location is resolved first, so a location outside the credential's reach never reveals whether the named template exists. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · templateNotFound

{
  "type": "urn:qms:problem:template_not_found",
  "title": "Template Not Found",
  "status": 404,
  "code": "template_not_found",
  "detail": "No location template was found for this identifier."
}

404 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 — A template apply refused because the overwrite would drop a service that still holds a non-terminal ticket, with one `blockers` entry counting those tickets. Nothing is written. The only code at this status on the apply.

409 · Example

{
  "type": "urn:qms:problem:template_apply_blocked",
  "title": "Template Apply Blocked",
  "status": 409,
  "code": "template_apply_blocked",
  "detail": "The template cannot be applied while something still depends on the service it would drop.",
  "blockers": [
    {
      "kind": "TICKET",
      "count": 3
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

GETRead which blocks a location's TV display shows/api/integration/v1/locations/{locationId}/display-channels

Read which blocks a location's TV display shows

Whether the location's in-branch TV display shows its waiting queue (`queueStatus`), its announcement banner (`announcements`) and its clock (`clock`). The active calls are always shown and are not a member of this document. Requires a credential whose reach includes the location. Both a tenant administrator's and a location manager's credential reach this operation; a location outside the credential's reach is the 404, never a 403.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/display-channels" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's display channels.

200 · Example

{
  "queueStatus": true,
  "announcements": false,
  "clock": true
}

200 response schema

Which blocks a location's TV display shows. The active calls are always shown and are not a member.

queueStatus · boolean · required

Whether the waiting queue is shown.

announcements · boolean · required

Whether the announcement banner is shown.

clock · boolean · required

Whether the date and time are shown.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "Which blocks a location's TV display shows. The active calls are always shown and are not a member.",
  "properties": {
    "queueStatus": {
      "type": "boolean",
      "description": "Whether the waiting queue is shown.",
      "example": true
    },
    "announcements": {
      "type": "boolean",
      "description": "Whether the announcement banner is shown.",
      "example": true
    },
    "clock": {
      "type": "boolean",
      "description": "Whether the date and time are shown.",
      "example": true
    }
  },
  "required": [
    "queueStatus",
    "announcements",
    "clock"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PUTSet which blocks a location's TV display shows/api/integration/v1/locations/{locationId}/display-channels

Set which blocks a location's TV display shows

Sets all three display channels of the location at once. Each of `queueStatus`, `announcements` and `clock` is required and must be a JSON boolean: a member that is absent or null is answered 400 `validation_failed` with code `required`, and a string, number or object is answered with code `invalid_format` — a value is never coerced. Nothing is written on a refusal. Any other member is ignored; the active calls are always shown and no member can hide them. Every block whose value changes writes one audit entry carrying the credential; a block saved at its current value writes nothing, and the location's paired displays refresh once the write commits. Requires a credential whose reach includes the location. Both a tenant administrator's and a location manager's credential reach this operation; a location outside the credential's reach is the 404, never a 403.

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

curl --request PUT "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/display-channels" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "queueStatus": false,
  "announcements": true,
  "clock": false
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "queueStatus": false,
  "announcements": true,
  "clock": false
}

Request schema

The display channels write body: all three members, each a JSON boolean.

queueStatus · boolean · required

Whether the waiting queue is shown.

announcements · boolean · required

Whether the announcement banner is shown.

clock · boolean · required

Whether the date and time are shown.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The display channels write body: all three members, each a JSON boolean.",
  "properties": {
    "queueStatus": {
      "type": "boolean",
      "description": "Whether the waiting queue is shown.",
      "example": false
    },
    "announcements": {
      "type": "boolean",
      "description": "Whether the announcement banner is shown.",
      "example": true
    },
    "clock": {
      "type": "boolean",
      "description": "Whether the date and time are shown.",
      "example": false
    }
  },
  "required": [
    "queueStatus",
    "announcements",
    "clock"
  ]
}

Responses

200 — The location's display channels after the write.

200 · Example

{
  "queueStatus": false,
  "announcements": true,
  "clock": false
}

200 response schema

Which blocks a location's TV display shows. The active calls are always shown and are not a member.

queueStatus · boolean · required

Whether the waiting queue is shown.

announcements · boolean · required

Whether the announcement banner is shown.

clock · boolean · required

Whether the date and time are shown.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "Which blocks a location's TV display shows. The active calls are always shown and are not a member.",
  "properties": {
    "queueStatus": {
      "type": "boolean",
      "description": "Whether the waiting queue is shown.",
      "example": true
    },
    "announcements": {
      "type": "boolean",
      "description": "Whether the announcement banner is shown.",
      "example": true
    },
    "clock": {
      "type": "boolean",
      "description": "Whether the date and time are shown.",
      "example": true
    }
  },
  "required": [
    "queueStatus",
    "announcements",
    "clock"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETList a location's operator profiles/api/integration/v1/locations/{locationId}/operators

List a location's operator profiles

Every operator profile at the location, in the shape entry members below fix. Sorted by `name` ascending; an `INVITED` profile carries no `name` and sorts last, ordered by `email` among the `INVITED` entries themselves. All three `status` values are returned — the console's `ACTIVE`-only default filter is a listing affordance this read does not apply — and no query parameter narrows the answer. The resource is the per-location profile, never the person behind it: a user holding profiles at three locations is three entries under three locations, each with its own skills, windows and status, correlated through the stable `userId` member rather than through a shared path. A location outside the credential's reach, in another tenant, `ARCHIVED`, `DELETED` or nonexistent is one answer, 404 `location_not_found`, so that the existence of another tenant's data cannot be probed and so that an archived location reads the same as an invisible one.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's operator profiles, sorted by name.

200 · Example

{
  "items": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "userId": "44444444-4444-4444-8444-444444444444",
      "email": "operator.one@example.test",
      "name": "Operator One",
      "employeeId": "EMP042",
      "status": "ACTIVE",
      "languages": [
        "EN",
        "LT"
      ],
      "serviceIds": [
        "77777777-7777-4777-8777-777777777777"
      ],
      "windowIds": [
        "A1"
      ],
      "presence": "AVAILABLE"
    }
  ]
}

200 response schema

The operator collection read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per operator profile at the location, sorted by name ascending with INVITED profiles last, ordered by email among themselves.

Show nested fields

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The operator collection read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per operator profile at the location, sorted by name ascending with INVITED profiles last, ordered by email among themselves.",
      "items": {
        "type": "object",
        "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The profile's own opaque identifier.",
            "example": "66666666-6666-4666-8666-666666666666"
          },
          "userId": {
            "type": "string",
            "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
            "example": "44444444-4444-4444-8444-444444444444"
          },
          "email": {
            "type": "string",
            "example": "operator.one@example.test"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Operator One"
          },
          "employeeId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Za-z0-9]{1,50}$",
            "maxLength": 50,
            "example": "EMP042"
          },
          "status": {
            "type": "string",
            "description": "The profile's enablement, derived the way the console derives it.",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "INVITED"
            ],
            "example": "ACTIVE"
          },
          "languages": {
            "type": "array",
            "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
            "items": {
              "type": "string"
            },
            "example": [
              "EN",
              "LT"
            ]
          },
          "serviceIds": {
            "type": "array",
            "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
            "items": {
              "type": "string"
            },
            "example": [
              "77777777-7777-4777-8777-777777777777"
            ]
          },
          "windowIds": {
            "type": "array",
            "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
            "items": {
              "type": "string"
            },
            "example": [
              "A1"
            ]
          },
          "presence": {
            "type": "string",
            "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
            "enum": [
              "AVAILABLE",
              "BUSY",
              "BREAK",
              "BACK_OFFICE",
              "OFFLINE"
            ],
            "example": "AVAILABLE"
          }
        },
        "required": [
          "id",
          "userId",
          "email",
          "name",
          "employeeId",
          "status",
          "languages",
          "serviceIds",
          "windowIds",
          "presence"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

POSTCreate an operator at a location/api/integration/v1/locations/{locationId}/operators

Create an operator at a location

Without `initialPassword` this is the invite. The address is normalised to lower case, a `User` in status `INVITED` with role `OPERATOR` is created, a 7-day-TTL invite token is generated and the invite email is sent asynchronously, so the response never waits on delivery. Answers 201 with the entry, `status` `INVITED`, carrying exactly the profile members the body supplied — `null` and empty for those it left out — until the invitee accepts. A `null` `initialPassword` is the same as an absent one. With `initialPassword` the operator is created `ACTIVE` instead, through the management console's own initial-password path: no invite token and no invite email, a local-password credential the operator must change at first sign-in. Answers 201 with `status` `ACTIVE` and `presence` `OFFLINE`, carrying the supplied profile members. A password shorter than 12 characters, an empty one included, or one in the breach set is 400 `validation_failed` with field code `password_too_short` or `password_breached` under `initialPassword`. An address that belongs to ANY user of the tenant, whatever that user's status or roles, is 422 `initial_password_not_applicable`, which ranks above `email_already_in_use`, `operator_already_at_location` and `operator_already_assigned`; a password that is itself refused is 400 first. The password is never returned, logged or audited. The body may also carry the five profile members of the edit — `name`, `employeeId`, `languages`, `serviceIds` and `windowIds` — each optional and each written to the profile at create, on every create path, under the same rules as the edit: `name` is 1-100 characters; `employeeId` is alphanumeric, 1-50 characters; `languages` and `serviceIds` take at least one entry each when sent; each language code must be active in the tenant's language catalogue; each service id must be active at this location; each window id must be an ACTIVE window of this location. A refused member is 400 `validation_failed` with an `errors` entry naming it, carrying `required`, `too_long`, `invalid_format`, `duplicate`, `not_linked_to_location`, `inactive` or `language_not_in_catalogue`. A member fault is answered ahead of every conflict on the address, so it outranks `email_already_in_use` and `initial_password_not_applicable`. A body member besides `email`, `initialPassword` and those five is refused 400 `validation_failed` with an `errors` entry naming it `not_writable`, before the location is even parsed, and nothing is written on any refusal. An address already attached to any `User` of the tenant is 409 `email_already_in_use`. An address already holding a profile AT THIS LOCATION is 409 `operator_already_at_location`. An address holding a profile at ANOTHER location is ordinarily accepted and creates a second, independent profile — the multi-branch case this surface exists to automate — except while the tenant's vocabulary still holds to one profile per user, where it is 409 `operator_already_assigned` instead. A location that is `ARCHIVED` is reachable by the credential but not open to a new profile, so the invite answers 404 `location_not_found` — the same document the two reads give that same location, even though this refusal is raised deeper, once the domain itself is reached rather than by the reach guard alone.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "email": "new.operator@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "languages": [
    "EN"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ]
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "email": "new.operator@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "languages": [
    "EN"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ]
}

Request schema

The create body: `email`, and optionally `initialPassword` and the five profile members of the edit. A member this document does not declare is refused by name with field code `not_writable`, whether or not its value would have changed anything, and nothing is written.

email · string · required

initialPassword · string | null · optional

Optional. Absent or null, the request is the invite. Present, the operator is created ACTIVE with this password instead: no invite token and no invite email, and the operator must change it at first sign-in. At least 12 characters and not in the breach set, else 400 with field code `password_too_short` or `password_breached`. Refused 422 `initial_password_not_applicable` when the address belongs to any user of the tenant. Never returned by any response.

name · string | null · optional

Optional; written at create; same validation as the profile edit; refused before any existing-user check.

employeeId · string | null · optional

Optional; written at create; same validation as the profile edit; refused before any existing-user check.

languages · array | null · optional

Optional; written at create; same validation as the profile edit; refused before any existing-user check.

Show nested fields

serviceIds · array | null · optional

Optional; written at create; same validation as the profile edit; refused before any existing-user check.

Show nested fields

windowIds · array | null · optional

Optional; written at create; same validation as the profile edit; refused before any existing-user check. The business window ids — the `windows[].id` values of the location configuration document. Each id must be an ACTIVE window of this location.

Show nested fields

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The create body: `email`, and optionally `initialPassword` and the five profile members of the edit. A member this document does not declare is refused by name with field code `not_writable`, whether or not its value would have changed anything, and nothing is written.",
  "properties": {
    "email": {
      "type": "string",
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "example": "new.operator@example.test"
    },
    "initialPassword": {
      "type": [
        "string",
        "null"
      ],
      "writeOnly": true,
      "minLength": 12,
      "description": "Optional. Absent or null, the request is the invite. Present, the operator is created ACTIVE with this password instead: no invite token and no invite email, and the operator must change it at first sign-in. At least 12 characters and not in the breach set, else 400 with field code `password_too_short` or `password_breached`. Refused 422 `initial_password_not_applicable` when the address belongs to any user of the tenant. Never returned by any response.",
      "example": "correct-horse-battery-staple"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 100,
      "description": "Optional; written at create; same validation as the profile edit; refused before any existing-user check.",
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "description": "Optional; written at create; same validation as the profile edit; refused before any existing-user check.",
      "example": "EMP042"
    },
    "languages": {
      "type": [
        "array",
        "null"
      ],
      "description": "Optional; written at create; same validation as the profile edit; refused before any existing-user check.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": [
        "array",
        "null"
      ],
      "description": "Optional; written at create; same validation as the profile edit; refused before any existing-user check.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": [
        "array",
        "null"
      ],
      "description": "Optional; written at create; same validation as the profile edit; refused before any existing-user check. The business window ids — the `windows[].id` values of the location configuration document. Each id must be an ACTIVE window of this location.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    }
  },
  "required": [
    "email"
  ]
}

Responses

201 — The operator profile as created: status INVITED, or ACTIVE when an `initialPassword` was sent, holding the profile members the body supplied.

201 · Example

{
  "id": "66666666-6666-4666-8666-666666666666",
  "userId": "44444444-4444-4444-8444-444444444444",
  "email": "new.operator@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "status": "INVITED",
  "languages": [
    "EN"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ],
  "presence": "OFFLINE"
}

201 response schema

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The profile's own opaque identifier.",
      "example": "66666666-6666-4666-8666-666666666666"
    },
    "userId": {
      "type": "string",
      "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "email": {
      "type": "string",
      "example": "operator.one@example.test"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "status": {
      "type": "string",
      "description": "The profile's enablement, derived the way the console derives it.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "INVITED"
      ],
      "example": "ACTIVE"
    },
    "languages": {
      "type": "array",
      "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    },
    "presence": {
      "type": "string",
      "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
      "enum": [
        "AVAILABLE",
        "BUSY",
        "BREAK",
        "BACK_OFFICE",
        "OFFLINE"
      ],
      "example": "AVAILABLE"
    }
  },
  "required": [
    "id",
    "userId",
    "email",
    "name",
    "employeeId",
    "status",
    "languages",
    "serviceIds",
    "windowIds",
    "presence"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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 invite was refused, and nothing was written. Three codes share this status: `operator_already_at_location` when the address already holds a profile at this location, `email_already_in_use` when it already belongs to a User of the tenant, and `operator_already_assigned` when it already holds a profile at another location. Branch on `code`.

409 · operatorAlreadyAtLocation

{
  "type": "urn:qms:problem:operator_already_at_location",
  "title": "Operator Already At Location",
  "status": 409,
  "code": "operator_already_at_location",
  "detail": "That address already holds an operator profile at this location."
}

409 · emailAlreadyInUse

{
  "type": "urn:qms:problem:email_already_in_use",
  "title": "Email Already In Use",
  "status": 409,
  "code": "email_already_in_use",
  "detail": "That address already belongs to a user of this tenant."
}

409 · operatorAlreadyAssigned

{
  "type": "urn:qms:problem:operator_already_assigned",
  "title": "Operator Already Assigned",
  "status": 409,
  "code": "operator_already_assigned",
  "detail": "That address already holds an operator profile at another location."
}

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
}

422 — An `initialPassword` was sent for an address that already belongs to a user of the tenant, whatever that user's status or roles, and nothing was written.

422 · Example

{
  "type": "urn:qms:problem:initial_password_not_applicable",
  "title": "Initial Password Not Applicable",
  "status": 422,
  "code": "initial_password_not_applicable",
  "detail": "An initial password applies only to an address no user of this tenant holds; nothing was written."
}

422 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.

500 · Example

{
  "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
}

Open operation →

GETRead a single operator profile/api/integration/v1/locations/{locationId}/operators/{operatorId}

Read a single operator profile

One operator profile. `operatorId` addresses the profile itself, never the user behind it — the same person holding profiles at other locations is a different `id` at each of them. A location outside the credential's reach, in another tenant or nonexistent is 404 `location_not_found`. A location that is `ARCHIVED` is answered `operator_not_found` instead, never `location_not_found`: the lookup that resolves one profile cannot itself tell an archived, reachable location apart from an invisible profile, so the two causes collapse onto the code a profile lookup already uses for every other one — belongs to another location, is retired, was named by an unparseable segment, or never existed. This is the one place the collection read and the single read answer an ARCHIVED location differently, and both answers are correct: the collection addresses the location itself and the single read addresses a profile inside it. Branch on `code`, never on the fact that both are 404.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators/66666666-6666-4666-8666-666666666666" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
operatorId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

operatorId: The operator profile's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The operator profile.

200 · Example

{
  "id": "66666666-6666-4666-8666-666666666666",
  "userId": "44444444-4444-4444-8444-444444444444",
  "email": "operator.one@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "status": "ACTIVE",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ],
  "presence": "AVAILABLE"
}

200 response schema

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The profile's own opaque identifier.",
      "example": "66666666-6666-4666-8666-666666666666"
    },
    "userId": {
      "type": "string",
      "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "email": {
      "type": "string",
      "example": "operator.one@example.test"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "status": {
      "type": "string",
      "description": "The profile's enablement, derived the way the console derives it.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "INVITED"
      ],
      "example": "ACTIVE"
    },
    "languages": {
      "type": "array",
      "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    },
    "presence": {
      "type": "string",
      "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
      "enum": [
        "AVAILABLE",
        "BUSY",
        "BREAK",
        "BACK_OFFICE",
        "OFFLINE"
      ],
      "example": "AVAILABLE"
    }
  },
  "required": [
    "id",
    "userId",
    "email",
    "name",
    "employeeId",
    "status",
    "languages",
    "serviceIds",
    "windowIds",
    "presence"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No operator profile answered the request. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `operator_not_found` for every other invisibility cause — an ARCHIVED location included, because the profile lookup cannot tell an archived, reachable location apart from an absent profile, so the two collapse onto the same code a profile lookup already uses. Shared by the single read, the edit, the removal, the deactivate and the reactivate. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · operatorNotFound

{
  "type": "urn:qms:problem:operator_not_found",
  "title": "Operator Not Found",
  "status": 404,
  "code": "operator_not_found",
  "detail": "No operator profile was found for this identifier at this location."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHEdit an operator profile/api/integration/v1/locations/{locationId}/operators/{operatorId}

Edit an operator profile

A partial edit: `name`, `employeeId`, `languages`, `serviceIds` and `windowIds` are each left unchanged when absent, and REPLACED — never merged — when present. Answers 200 with the updated entry. A body carrying `id`, `userId`, `email`, `status` or `presence` AT ALL is refused 400 `validation_failed` with an `errors` entry naming it `not_writable`, whether or not its value differs from the stored one, and nothing is written. `name` is 1-100 characters; `employeeId` is optional, alphanumeric, 1-50 characters; sending either `languages` or `serviceIds` requires at least one entry in each, because sending one carries the other forward unchanged; each language code must be active in the tenant's language catalogue, refused with field code `language_not_in_catalogue` when it is not; each service id must be active at this location; each window id must be an ACTIVE window of this location. A profile whose `status` is `INVITED` refuses every edit with 409 `operator_invite_pending` and writes nothing: the profile cannot be edited until the invitee accepts, whatever its create stored. The two 404 causes are exactly the single read's own — an ARCHIVED location answers `operator_not_found`, never `location_not_found`.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators/66666666-6666-4666-8666-666666666666" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Operator One",
  "employeeId": "EMP042",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ]
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
operatorId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

operatorId: The operator profile's opaque identifier.

Request body

Example body

{
  "name": "Operator One",
  "employeeId": "EMP042",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ]
}

Request schema

The profile edit body. Every member is optional and one left out is left unchanged; a member sent REPLACES the stored value. `id`, `userId`, `email`, `status` and `presence` have no slot here — a body carrying any of them at all is refused with field code `not_writable`, whether or not the value matches what is already stored.

name · string · optional

employeeId · string · optional

languages · array · optional

Show nested fields

serviceIds · array · optional

Show nested fields

windowIds · array · optional

The business window ids — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Each id must be an ACTIVE window of this location.

Show nested fields

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The profile edit body. Every member is optional and one left out is left unchanged; a member sent REPLACES the stored value. `id`, `userId`, `email`, `status` and `presence` have no slot here — a body carrying any of them at all is refused with field code `not_writable`, whether or not the value matches what is already stored.",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "example": "Operator One"
    },
    "employeeId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Each id must be an ACTIVE window of this location.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    }
  }
}

Responses

200 — The operator profile as it stands after the edit.

200 · Example

{
  "id": "66666666-6666-4666-8666-666666666666",
  "userId": "44444444-4444-4444-8444-444444444444",
  "email": "operator.one@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "status": "ACTIVE",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ],
  "presence": "AVAILABLE"
}

200 response schema

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The profile's own opaque identifier.",
      "example": "66666666-6666-4666-8666-666666666666"
    },
    "userId": {
      "type": "string",
      "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "email": {
      "type": "string",
      "example": "operator.one@example.test"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "status": {
      "type": "string",
      "description": "The profile's enablement, derived the way the console derives it.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "INVITED"
      ],
      "example": "ACTIVE"
    },
    "languages": {
      "type": "array",
      "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    },
    "presence": {
      "type": "string",
      "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
      "enum": [
        "AVAILABLE",
        "BUSY",
        "BREAK",
        "BACK_OFFICE",
        "OFFLINE"
      ],
      "example": "AVAILABLE"
    }
  },
  "required": [
    "id",
    "userId",
    "email",
    "name",
    "employeeId",
    "status",
    "languages",
    "serviceIds",
    "windowIds",
    "presence"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No operator profile answered the request. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `operator_not_found` for every other invisibility cause — an ARCHIVED location included, because the profile lookup cannot tell an archived, reachable location apart from an absent profile, so the two collapse onto the same code a profile lookup already uses. Shared by the single read, the edit, the removal, the deactivate and the reactivate. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · operatorNotFound

{
  "type": "urn:qms:problem:operator_not_found",
  "title": "Operator Not Found",
  "status": 404,
  "code": "operator_not_found",
  "detail": "No operator profile was found for this identifier at this location."
}

404 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 profile's invitee has not accepted yet, so the fields a profile edit writes have no accepted value to hold: `name`, `employeeId` and the three arrays are all null or empty on an INVITED profile, and this is the edit's only code at this status.

409 · Example

{
  "type": "urn:qms:problem:operator_invite_pending",
  "title": "Operator Invite Pending",
  "status": 409,
  "code": "operator_invite_pending",
  "detail": "The invitee has not accepted the invite yet, so the profile cannot be edited."
}

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.

500 · Example

{
  "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
}

Open operation →

DELETERemove an operator profile from a location/api/integration/v1/locations/{locationId}/operators/{operatorId}

Remove an operator profile from a location

Deletes the location's profile together with its window assignments and skills, and answers 204 with no body — the request carries no body either. Profiles at other locations are untouched; `OPERATOR` leaves the backing user's roles only when this was their last current profile. Removal is not deactivation and never substitutes for it: a caller meaning "not working this week" calls the deactivate operation below; a caller meaning "has left this branch" calls this one. A profile holding a ticket in `SERVING` is refused 409 `operator_serving_ticket`, the removal's only code at this status, and nothing is deleted; a ticket in `CALLED` is auto-transferred back to `WAITING` before the delete commits. The two 404 causes are exactly the single read's own.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators/66666666-6666-4666-8666-666666666666" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
operatorId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

operatorId: The operator profile's opaque identifier.

Request body

None. This operation carries no request body.

Responses

204 — The profile is removed. RFC 9110 gives this status no body, so this answer declares no content and none is returned.

No response body.

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No operator profile answered the request. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `operator_not_found` for every other invisibility cause — an ARCHIVED location included, because the profile lookup cannot tell an archived, reachable location apart from an absent profile, so the two collapse onto the same code a profile lookup already uses. Shared by the single read, the edit, the removal, the deactivate and the reactivate. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · operatorNotFound

{
  "type": "urn:qms:problem:operator_not_found",
  "title": "Operator Not Found",
  "status": 404,
  "code": "operator_not_found",
  "detail": "No operator profile was found for this identifier at this location."
}

404 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 profile holds a ticket in SERVING, so it cannot be deactivated or removed; `blockers` carries one `TICKET` entry and `detail` names the ticket. This entry is the code's declaration; the deactivate declares `OperatorDeactivateConflict`, which shares the status with `operator_already_inactive`, while the removal answers this entry directly — it is the removal's only code at this status.

409 · Example

{
  "type": "urn:qms:problem:operator_serving_ticket",
  "title": "Operator Serving Ticket",
  "status": 409,
  "code": "operator_serving_ticket",
  "detail": "The operator profile is serving ticket A014.",
  "blockers": [
    {
      "kind": "TICKET",
      "count": 1
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

POSTDeactivate an operator profile/api/integration/v1/locations/{locationId}/operators/{operatorId}/deactivate

Deactivate an operator profile

Moves the profile out of the matching pool — it cannot sign in and is never matched a ticket until reactivated — and answers 200 with the updated entry. The request carries no body. Deactivation is refused while the profile holds a ticket in `SERVING`: 409 `operator_serving_ticket`, carrying one `blockers` entry of kind `TICKET` and the ticket number in `detail`. A ticket in `CALLED` is auto-transferred back to `WAITING` with its context preserved rather than blocking the deactivate. Deactivating a profile that is already `INACTIVE` is 409 `operator_already_inactive`, and that guard is evaluated FIRST, so an already-inactive profile is never answered about a stale queue state. The two 404 causes are exactly the single read's own.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators/66666666-6666-4666-8666-666666666666/deactivate" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
operatorId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

operatorId: The operator profile's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The operator profile, now INACTIVE.

200 · Example

{
  "id": "66666666-6666-4666-8666-666666666666",
  "userId": "44444444-4444-4444-8444-444444444444",
  "email": "operator.one@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "status": "INACTIVE",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ],
  "presence": "OFFLINE"
}

200 response schema

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The profile's own opaque identifier.",
      "example": "66666666-6666-4666-8666-666666666666"
    },
    "userId": {
      "type": "string",
      "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "email": {
      "type": "string",
      "example": "operator.one@example.test"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "status": {
      "type": "string",
      "description": "The profile's enablement, derived the way the console derives it.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "INVITED"
      ],
      "example": "ACTIVE"
    },
    "languages": {
      "type": "array",
      "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    },
    "presence": {
      "type": "string",
      "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
      "enum": [
        "AVAILABLE",
        "BUSY",
        "BREAK",
        "BACK_OFFICE",
        "OFFLINE"
      ],
      "example": "AVAILABLE"
    }
  },
  "required": [
    "id",
    "userId",
    "email",
    "name",
    "employeeId",
    "status",
    "languages",
    "serviceIds",
    "windowIds",
    "presence"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No operator profile answered the request. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `operator_not_found` for every other invisibility cause — an ARCHIVED location included, because the profile lookup cannot tell an archived, reachable location apart from an absent profile, so the two collapse onto the same code a profile lookup already uses. Shared by the single read, the edit, the removal, the deactivate and the reactivate. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · operatorNotFound

{
  "type": "urn:qms:problem:operator_not_found",
  "title": "Operator Not Found",
  "status": 404,
  "code": "operator_not_found",
  "detail": "No operator profile was found for this identifier at this location."
}

404 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 deactivate was refused. Two codes share this status: `operator_already_inactive` when the profile cannot transition at all — evaluated FIRST — and `operator_serving_ticket` when it holds a ticket in SERVING, with one `blockers` entry naming it. Branch on `code`.

409 · operatorAlreadyInactive

{
  "type": "urn:qms:problem:operator_already_inactive",
  "title": "Operator Already Inactive",
  "status": 409,
  "code": "operator_already_inactive",
  "detail": "The operator profile is already inactive."
}

409 · operatorServingTicket

{
  "type": "urn:qms:problem:operator_serving_ticket",
  "title": "Operator Serving Ticket",
  "status": 409,
  "code": "operator_serving_ticket",
  "detail": "The operator profile is serving ticket A014.",
  "blockers": [
    {
      "kind": "TICKET",
      "count": 1
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

POSTReactivate an operator profile/api/integration/v1/locations/{locationId}/operators/{operatorId}/reactivate

Reactivate an operator profile

Restores the profile's prior windows, skills and acceptance state and answers 200 with the updated entry. The request carries no body. A profile that was deactivated before accepting its invite returns to `INVITED`, never to `ACTIVE` — reactivation restores exactly the state the deactivate captured, not a fixed one. Reactivating a profile that is not `INACTIVE` is 409 `operator_not_inactive`, evaluated FIRST. Only once that guard passes is the backing user account checked: a profile whose `User` is DISABLED is refused 409 `user_not_assignable`. The two 404 causes are exactly the single read's own.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/operators/66666666-6666-4666-8666-666666666666/reactivate" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
operatorId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

operatorId: The operator profile's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The operator profile, now ACTIVE (or INVITED — see above).

200 · Example

{
  "id": "66666666-6666-4666-8666-666666666666",
  "userId": "44444444-4444-4444-8444-444444444444",
  "email": "operator.one@example.test",
  "name": "Operator One",
  "employeeId": "EMP042",
  "status": "ACTIVE",
  "languages": [
    "EN",
    "LT"
  ],
  "serviceIds": [
    "77777777-7777-4777-8777-777777777777"
  ],
  "windowIds": [
    "A1"
  ],
  "presence": "OFFLINE"
}

200 response schema

One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.

id · string · required

The profile's own opaque identifier.

userId · string · required

The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.

email · string · required

name · string | null · required

employeeId · string | null · required

status · string · required

The profile's enablement, derived the way the console derives it.

Allowed values: "ACTIVE", "INACTIVE", "INVITED"

languages · array · required

ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.

Show nested fields

serviceIds · array · required

Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.

Show nested fields

windowIds · array · required

The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.

Show nested fields

presence · string · required

The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.

Allowed values: "AVAILABLE", "BUSY", "BREAK", "BACK_OFFICE", "OFFLINE"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One operator profile at one location — the resource this surface addresses, never the person behind it. Every member is always present; while `status` is `INVITED`, `name` and `employeeId` are null and the three arrays are empty.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The profile's own opaque identifier.",
      "example": "66666666-6666-4666-8666-666666666666"
    },
    "userId": {
      "type": "string",
      "description": "The backing user, stable across every profile the same person holds at other locations. Never a path member — correlate on this instead.",
      "example": "44444444-4444-4444-8444-444444444444"
    },
    "email": {
      "type": "string",
      "example": "operator.one@example.test"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Operator One"
    },
    "employeeId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Za-z0-9]{1,50}$",
      "maxLength": 50,
      "example": "EMP042"
    },
    "status": {
      "type": "string",
      "description": "The profile's enablement, derived the way the console derives it.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "INVITED"
      ],
      "example": "ACTIVE"
    },
    "languages": {
      "type": "array",
      "description": "ISO 639-1 codes, upper-cased, active in the tenant's language catalogue.",
      "items": {
        "type": "string"
      },
      "example": [
        "EN",
        "LT"
      ]
    },
    "serviceIds": {
      "type": "array",
      "description": "Opaque service identifiers, active at this location. Read a service's own name and duration from the service resource; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "77777777-7777-4777-8777-777777777777"
      ]
    },
    "windowIds": {
      "type": "array",
      "description": "The business window ids of this location's windows — the `windows[].id` values of the location configuration document (`GET …/locations/{locationId}/configuration`). Read a window's own floor and status there; no second copy is published here.",
      "items": {
        "type": "string"
      },
      "example": [
        "A1"
      ]
    },
    "presence": {
      "type": "string",
      "description": "The profile's live status, evaluated at the instant of the read. Read-only: no operation this document describes ever writes it.",
      "enum": [
        "AVAILABLE",
        "BUSY",
        "BREAK",
        "BACK_OFFICE",
        "OFFLINE"
      ],
      "example": "AVAILABLE"
    }
  },
  "required": [
    "id",
    "userId",
    "email",
    "name",
    "employeeId",
    "status",
    "languages",
    "serviceIds",
    "windowIds",
    "presence"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No operator profile answered the request. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `operator_not_found` for every other invisibility cause — an ARCHIVED location included, because the profile lookup cannot tell an archived, reachable location apart from an absent profile, so the two collapse onto the same code a profile lookup already uses. Shared by the single read, the edit, the removal, the deactivate and the reactivate. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · operatorNotFound

{
  "type": "urn:qms:problem:operator_not_found",
  "title": "Operator Not Found",
  "status": 404,
  "code": "operator_not_found",
  "detail": "No operator profile was found for this identifier at this location."
}

404 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 reactivate was refused. Two codes share this status: `operator_not_inactive` when the profile cannot transition at all — evaluated FIRST — and `user_not_assignable` when the backing user account is DISABLED. Branch on `code`.

409 · operatorNotInactive

{
  "type": "urn:qms:problem:operator_not_inactive",
  "title": "Operator Not Inactive",
  "status": 409,
  "code": "operator_not_inactive",
  "detail": "The operator profile is not inactive."
}

409 · userNotAssignable

{
  "type": "urn:qms:problem:user_not_assignable",
  "title": "User Not Assignable",
  "status": 409,
  "code": "user_not_assignable",
  "detail": "The user account behind this operator profile is disabled."
}

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.

500 · Example

{
  "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
}

Open operation →

GETList a location's paired TV displays/api/integration/v1/locations/{locationId}/displays

List a location's paired TV displays

Every paired TV display at the location, with the layout and colour set it shows, in the shape the entry members below fix. Sorted by `name` ascending and then by `id`. A revoked display is not listed, and no query parameter narrows the answer. A location with no paired display answers an empty `items`, not 404. Requires the `devices:read` scope. Both management levels reach the displays of the locations they manage — a location manager those of an assigned location, a tenant administrator those of every location — so `insufficient_authority` never answers this operation. A location outside the credential's reach, in another tenant, permanently deleted, nonexistent or named by a segment that is not an identifier at all is one answer, 404 `location_not_found`, so that the existence of another tenant's data cannot be probed.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/displays" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's paired displays, sorted by name.

200 · Example

{
  "items": [
    {
      "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccd",
      "name": "Entrance TV",
      "layout": "LIST",
      "palette": "DEFAULT"
    },
    {
      "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
      "name": "Lobby TV",
      "layout": "TWO_COLUMNS",
      "palette": "GREEN"
    }
  ]
}

200 response schema

The displays read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per paired display of the location that is not revoked, sorted by name ascending and then by id.

Show nested fields

One paired TV display at one location, with the two settings that decide how its board looks. Every member is always present.

id · string · required

The display's own opaque identifier.

name · string · required

The display's name, as the management console shows it.

layout · string · required

How the board arranges the called customers and the waiting queue. The values in use today are `LIST`, the default — the called customers across the full width with the waiting queue in a strip beneath them — and `TWO_COLUMNS` — the waiting queue in the left half of the screen and the called customers in the right half. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.

palette · string · required

The preset colour set the board's accents use. The values in use today are `DEFAULT`, the board's own accent colours, `NAVY` (dark blue), `GREEN`, `RED` and `GRAPHITE`. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The displays read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per paired display of the location that is not revoked, sorted by name ascending and then by id.",
      "items": {
        "type": "object",
        "description": "One paired TV display at one location, with the two settings that decide how its board looks. Every member is always present.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The display's own opaque identifier.",
            "example": "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
          },
          "name": {
            "type": "string",
            "description": "The display's name, as the management console shows it.",
            "example": "Lobby TV"
          },
          "layout": {
            "type": "string",
            "description": "How the board arranges the called customers and the waiting queue. The values in use today are `LIST`, the default — the called customers across the full width with the waiting queue in a strip beneath them — and `TWO_COLUMNS` — the waiting queue in the left half of the screen and the called customers in the right half. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.",
            "example": "TWO_COLUMNS"
          },
          "palette": {
            "type": "string",
            "description": "The preset colour set the board's accents use. The values in use today are `DEFAULT`, the board's own accent colours, `NAVY` (dark blue), `GREEN`, `RED` and `GRAPHITE`. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.",
            "example": "GREEN"
          }
        },
        "required": [
          "id",
          "name",
          "layout",
          "palette"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHSet a paired TV display's layout and colour set/api/integration/v1/locations/{locationId}/displays/{displayId}

Set a paired TV display's layout and colour set

A partial edit: `layout` and `palette` are each left unchanged when absent and set when present. A member sent as JSON `null` is indistinguishable from an absent one. Answers 200 with the display as it stands afterwards. A body that carries neither member, or only the values the display already has, changes nothing and answers 200 all the same. A change reaches the display's board without anyone touching the TV. Every setting that changes is audited, with the issuing user as actor and the credential's identifier; a setting saved at its current value records nothing. Values are matched exactly, in upper case. Both vocabularies are open: a later release may add a layout or a colour set, which is not a breaking change, so a client must tolerate a value it does not know in a response. A value this release does not serve, or a member that is not a string, is refused 400 `validation_failed` with an `errors` entry naming the member with field code `invalid_format`, and nothing is written. The body is checked before the location is parsed or reached, so a refused value answers 400 `validation_failed` even for a location outside the credential's reach. Requires the `devices:write` scope. Both management levels reach the displays of the locations they manage — a location manager those of an assigned location, a tenant administrator those of every location — so `insufficient_authority` never answers this operation. A location outside the credential's reach, in another tenant, permanently deleted, nonexistent or named by a segment that is not an identifier at all is 404 `location_not_found`. A display that is not a paired display of the location — it belongs to another location or tenant, is revoked, never existed, or was named by a segment that is not an identifier at all — is 404 `display_not_found`, never 403. Branch on `code`.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/displays/cccccccc-cccc-4ccc-8ccc-cccccccccccc" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "layout": "TWO_COLUMNS",
  "palette": "GRAPHITE"
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
displayId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

displayId: The display's opaque identifier.

Request body

Example body

{
  "layout": "TWO_COLUMNS",
  "palette": "GRAPHITE"
}

Request schema

The display settings patch body. Every member is optional and one left out is left unchanged; a member sent replaces the stored value. A member sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged. A value outside the vocabulary of the entry member of the same name is refused with field code `invalid_format`, and nothing is written.

layout · string · optional

The layout to set. The values in use today are `LIST` and `TWO_COLUMNS`.

palette · string · optional

The colour set to set. The values in use today are `DEFAULT`, `NAVY`, `GREEN`, `RED` and `GRAPHITE`.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The display settings patch body. Every member is optional and one left out is left unchanged; a member sent replaces the stored value. A member sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged. A value outside the vocabulary of the entry member of the same name is refused with field code `invalid_format`, and nothing is written.",
  "properties": {
    "layout": {
      "type": "string",
      "description": "The layout to set. The values in use today are `LIST` and `TWO_COLUMNS`.",
      "example": "TWO_COLUMNS"
    },
    "palette": {
      "type": "string",
      "description": "The colour set to set. The values in use today are `DEFAULT`, `NAVY`, `GREEN`, `RED` and `GRAPHITE`.",
      "example": "GRAPHITE"
    }
  }
}

Responses

200 — The display as it stands after the patch.

200 · Example

{
  "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "name": "Lobby TV",
  "layout": "TWO_COLUMNS",
  "palette": "GRAPHITE"
}

200 response schema

One paired TV display at one location, with the two settings that decide how its board looks. Every member is always present.

id · string · required

The display's own opaque identifier.

name · string · required

The display's name, as the management console shows it.

layout · string · required

How the board arranges the called customers and the waiting queue. The values in use today are `LIST`, the default — the called customers across the full width with the waiting queue in a strip beneath them — and `TWO_COLUMNS` — the waiting queue in the left half of the screen and the called customers in the right half. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.

palette · string · required

The preset colour set the board's accents use. The values in use today are `DEFAULT`, the board's own accent colours, `NAVY` (dark blue), `GREEN`, `RED` and `GRAPHITE`. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One paired TV display at one location, with the two settings that decide how its board looks. Every member is always present.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The display's own opaque identifier.",
      "example": "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
    },
    "name": {
      "type": "string",
      "description": "The display's name, as the management console shows it.",
      "example": "Lobby TV"
    },
    "layout": {
      "type": "string",
      "description": "How the board arranges the called customers and the waiting queue. The values in use today are `LIST`, the default — the called customers across the full width with the waiting queue in a strip beneath them — and `TWO_COLUMNS` — the waiting queue in the left half of the screen and the called customers in the right half. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.",
      "example": "TWO_COLUMNS"
    },
    "palette": {
      "type": "string",
      "description": "The preset colour set the board's accents use. The values in use today are `DEFAULT`, the board's own accent colours, `NAVY` (dark blue), `GREEN`, `RED` and `GRAPHITE`. The vocabulary is open: a later release may add a value, and a client must tolerate one it does not know.",
      "example": "GREEN"
    }
  },
  "required": [
    "id",
    "name",
    "layout",
    "palette"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No display answered the patch. Two codes share this status: `location_not_found` when the location itself is outside the credential's reach, in another tenant or nonexistent, and `display_not_found` for every other invisibility cause. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · displayNotFound

{
  "type": "urn:qms:problem:display_not_found",
  "title": "Display Not Found",
  "status": 404,
  "code": "display_not_found",
  "detail": "No display was found for this identifier at this location."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's languages/api/integration/v1/locations/{locationId}/languages

Read a location's languages

The languages one location offers, in the order the location lists them: the first is the location's default. Each entry says which customer surfaces offer the language, and whether the language has since been deactivated in the workspace language catalogue — a deactivated language stays in the list but is not offered to customers. A location the credential does not reach, a location belonging to another tenant, a permanently deleted location, and a path segment that is not an identifier at all are one and the same answer.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/languages" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's languages, in position order.

200 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": true,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    },
    {
      "code": "LT",
      "position": 2,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": false,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    }
  ]
}

200 response schema

A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per language of the location, in position order.

Show nested fields

One language of a location's list.

code · string · required

The platform language code, in upper case.

position · integer · required

The language's place in the location's list; the first is the default.

surfaces · object · required

Whether each customer surface offers the language.

Show nested fields

Whether each customer surface offers the language.

TABLET_KIOSK · boolean · required

WEB_BOOKING · boolean · required

IN_BRANCH_DISPLAY · boolean · required

TICKET_PAGE · boolean · required

deactivatedAtTenantLevel · boolean · required

Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per language of the location, in position order.",
      "items": {
        "type": "object",
        "description": "One language of a location's list.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The platform language code, in upper case.",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the location's list; the first is the default.",
            "example": 1
          },
          "surfaces": {
            "type": "object",
            "description": "Whether each customer surface offers the language.",
            "properties": {
              "TABLET_KIOSK": {
                "type": "boolean",
                "example": true
              },
              "WEB_BOOKING": {
                "type": "boolean",
                "example": true
              },
              "IN_BRANCH_DISPLAY": {
                "type": "boolean",
                "example": true
              },
              "TICKET_PAGE": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "TABLET_KIOSK",
              "WEB_BOOKING",
              "IN_BRANCH_DISPLAY",
              "TICKET_PAGE"
            ],
            "additionalProperties": false
          },
          "deactivatedAtTenantLevel": {
            "type": "boolean",
            "description": "Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.",
            "example": false
          }
        },
        "required": [
          "code",
          "position",
          "surfaces",
          "deactivatedAtTenantLevel"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

POSTAdd a language to a location/api/integration/v1/locations/{locationId}/languages

Add a language to a location

Appends one language of the workspace language catalogue to the location's list, last, with every surface on. The code is matched case-insensitively and listed in upper case. The answer is the whole list as it stands after the write. Requires a credential whose reach includes the location. Both a tenant administrator's and a location manager's credential reach this operation; a location outside the credential's reach is the 404, never a 403.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/languages" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "code": "LT"
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "code": "LT"
}

Request schema

code · string · required

A language of the workspace language catalogue, matched case-insensitively.

Raw JSON Schema

application/json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "A language of the workspace language catalogue, matched case-insensitively.",
      "example": "LT"
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Responses

201 — The location's languages after the write.

201 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": true,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    },
    {
      "code": "LT",
      "position": 2,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": true,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    }
  ]
}

201 response schema

A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per language of the location, in position order.

Show nested fields

One language of a location's list.

code · string · required

The platform language code, in upper case.

position · integer · required

The language's place in the location's list; the first is the default.

surfaces · object · required

Whether each customer surface offers the language.

Show nested fields

Whether each customer surface offers the language.

TABLET_KIOSK · boolean · required

WEB_BOOKING · boolean · required

IN_BRANCH_DISPLAY · boolean · required

TICKET_PAGE · boolean · required

deactivatedAtTenantLevel · boolean · required

Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per language of the location, in position order.",
      "items": {
        "type": "object",
        "description": "One language of a location's list.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The platform language code, in upper case.",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the location's list; the first is the default.",
            "example": 1
          },
          "surfaces": {
            "type": "object",
            "description": "Whether each customer surface offers the language.",
            "properties": {
              "TABLET_KIOSK": {
                "type": "boolean",
                "example": true
              },
              "WEB_BOOKING": {
                "type": "boolean",
                "example": true
              },
              "IN_BRANCH_DISPLAY": {
                "type": "boolean",
                "example": true
              },
              "TICKET_PAGE": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "TABLET_KIOSK",
              "WEB_BOOKING",
              "IN_BRANCH_DISPLAY",
              "TICKET_PAGE"
            ],
            "additionalProperties": false
          },
          "deactivatedAtTenantLevel": {
            "type": "boolean",
            "description": "Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.",
            "example": false
          }
        },
        "required": [
          "code",
          "position",
          "surfaces",
          "deactivatedAtTenantLevel"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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 language is already in the location's list.

409 · Example

{
  "type": "urn:qms:problem:language_already_listed",
  "title": "Language Already Listed",
  "status": 409,
  "code": "language_already_listed",
  "detail": "The language is already in this location's list."
}

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
}

422 — The code is not an active language of the workspace language catalogue, so it cannot be added to a location.

422 · Example

{
  "type": "urn:qms:problem:language_not_active",
  "title": "Language Not Active",
  "status": 422,
  "code": "language_not_active",
  "detail": "The language is not active in the tenant's language catalogue."
}

422 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.

500 · Example

{
  "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
}

Open operation →

PATCHReorder a location language or change its surfaces/api/integration/v1/locations/{locationId}/languages/{code}

Reorder a location language or change its surfaces

A partial write: a member absent from the body is left alone. At least one of `position` and `surfaces` must be present. `position` moves the language to that place in the list; a value outside the list — below 1 or above its size — moves it to the nearest end. `surfaces` names only the surfaces to change; a surface it does not name keeps its value, and an empty `surfaces` object changes nothing. The answer is the whole list as it stands after the write. Requires a credential whose reach includes the location; a location outside the credential's reach is the 404, never a 403.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/languages/LT" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "position": 1,
  "surfaces": {
    "WEB_BOOKING": false
  }
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
code	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

code: The platform language code, matched case-insensitively.

Request body

Example body

{
  "position": 1,
  "surfaces": {
    "WEB_BOOKING": false
  }
}

Request schema

At least one member must be present.

position · integer · optional

The place to move the language to. A value below 1 moves it to the first place and a value above the list's size to the last.

surfaces · object · optional

The surfaces to change. A surface left out keeps its value.

Show nested fields

The surfaces to change. A surface left out keeps its value.

TABLET_KIOSK · boolean · optional

WEB_BOOKING · boolean · optional

IN_BRANCH_DISPLAY · boolean · optional

TICKET_PAGE · boolean · optional

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "At least one member must be present.",
  "properties": {
    "position": {
      "type": "integer",
      "description": "The place to move the language to. A value below 1 moves it to the first place and a value above the list's size to the last.",
      "example": 1
    },
    "surfaces": {
      "type": "object",
      "description": "The surfaces to change. A surface left out keeps its value.",
      "properties": {
        "TABLET_KIOSK": {
          "type": "boolean",
          "example": true
        },
        "WEB_BOOKING": {
          "type": "boolean",
          "example": false
        },
        "IN_BRANCH_DISPLAY": {
          "type": "boolean",
          "example": true
        },
        "TICKET_PAGE": {
          "type": "boolean",
          "example": true
        }
      },
      "additionalProperties": false
    }
  },
  "minProperties": 1,
  "additionalProperties": false
}

Responses

200 — The location's languages after the write.

200 · Example

{
  "items": [
    {
      "code": "LT",
      "position": 1,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": false,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    },
    {
      "code": "EN",
      "position": 2,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": true,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    }
  ]
}

200 response schema

A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per language of the location, in position order.

Show nested fields

One language of a location's list.

code · string · required

The platform language code, in upper case.

position · integer · required

The language's place in the location's list; the first is the default.

surfaces · object · required

Whether each customer surface offers the language.

Show nested fields

Whether each customer surface offers the language.

TABLET_KIOSK · boolean · required

WEB_BOOKING · boolean · required

IN_BRANCH_DISPLAY · boolean · required

TICKET_PAGE · boolean · required

deactivatedAtTenantLevel · boolean · required

Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per language of the location, in position order.",
      "items": {
        "type": "object",
        "description": "One language of a location's list.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The platform language code, in upper case.",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the location's list; the first is the default.",
            "example": 1
          },
          "surfaces": {
            "type": "object",
            "description": "Whether each customer surface offers the language.",
            "properties": {
              "TABLET_KIOSK": {
                "type": "boolean",
                "example": true
              },
              "WEB_BOOKING": {
                "type": "boolean",
                "example": true
              },
              "IN_BRANCH_DISPLAY": {
                "type": "boolean",
                "example": true
              },
              "TICKET_PAGE": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "TABLET_KIOSK",
              "WEB_BOOKING",
              "IN_BRANCH_DISPLAY",
              "TICKET_PAGE"
            ],
            "additionalProperties": false
          },
          "deactivatedAtTenantLevel": {
            "type": "boolean",
            "description": "Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.",
            "example": false
          }
        },
        "required": [
          "code",
          "position",
          "surfaces",
          "deactivatedAtTenantLevel"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — Nothing was found to act on. Two codes share this status: `location_not_found` when the location is outside the credential's reach, belongs to another tenant, was permanently deleted or was named by a segment that is not an identifier; and `language_not_at_location` when the location is reachable but its list does not hold the code. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · languageNotAtLocation

{
  "type": "urn:qms:problem:language_not_at_location",
  "title": "Language Not At Location",
  "status": 404,
  "code": "language_not_at_location",
  "detail": "No language with this code is in this location's list."
}

404 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.

500 · Example

{
  "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
}

Open operation →

DELETERemove a language from a location/api/integration/v1/locations/{locationId}/languages/{code}

Remove a language from a location

Takes the language out of the location's list and closes the gap, so positions stay consecutive from 1. A location must keep at least one language: removing the last one is refused. The answer is the list that remains. Requires a credential whose reach includes the location; a location outside the credential's reach is the 404, never a 403.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/languages/LT" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
code	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

code: The platform language code, matched case-insensitively.

Request body

None. This operation carries no request body.

Responses

200 — The location's remaining languages.

200 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "surfaces": {
        "TABLET_KIOSK": true,
        "WEB_BOOKING": true,
        "IN_BRANCH_DISPLAY": true,
        "TICKET_PAGE": true
      },
      "deactivatedAtTenantLevel": false
    }
  ]
}

200 response schema

A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per language of the location, in position order.

Show nested fields

One language of a location's list.

code · string · required

The platform language code, in upper case.

position · integer · required

The language's place in the location's list; the first is the default.

surfaces · object · required

Whether each customer surface offers the language.

Show nested fields

Whether each customer surface offers the language.

TABLET_KIOSK · boolean · required

WEB_BOOKING · boolean · required

IN_BRANCH_DISPLAY · boolean · required

TICKET_PAGE · boolean · required

deactivatedAtTenantLevel · boolean · required

Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's languages: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per language of the location, in position order.",
      "items": {
        "type": "object",
        "description": "One language of a location's list.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The platform language code, in upper case.",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the location's list; the first is the default.",
            "example": 1
          },
          "surfaces": {
            "type": "object",
            "description": "Whether each customer surface offers the language.",
            "properties": {
              "TABLET_KIOSK": {
                "type": "boolean",
                "example": true
              },
              "WEB_BOOKING": {
                "type": "boolean",
                "example": true
              },
              "IN_BRANCH_DISPLAY": {
                "type": "boolean",
                "example": true
              },
              "TICKET_PAGE": {
                "type": "boolean",
                "example": true
              }
            },
            "required": [
              "TABLET_KIOSK",
              "WEB_BOOKING",
              "IN_BRANCH_DISPLAY",
              "TICKET_PAGE"
            ],
            "additionalProperties": false
          },
          "deactivatedAtTenantLevel": {
            "type": "boolean",
            "description": "Whether the language has been deactivated in the workspace language catalogue since it was added. A deactivated language stays listed but is not offered to customers.",
            "example": false
          }
        },
        "required": [
          "code",
          "position",
          "surfaces",
          "deactivatedAtTenantLevel"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — Nothing was found to act on. Two codes share this status: `location_not_found` when the location is outside the credential's reach, belongs to another tenant, was permanently deleted or was named by a segment that is not an identifier; and `language_not_at_location` when the location is reachable but its list does not hold the code. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · languageNotAtLocation

{
  "type": "urn:qms:problem:language_not_at_location",
  "title": "Language Not At Location",
  "status": 404,
  "code": "language_not_at_location",
  "detail": "No language with this code is in this location's list."
}

404 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
}

422 — The language is the only one the location lists, and a location must keep at least one.

422 · Example

{
  "type": "urn:qms:problem:last_location_language",
  "title": "Last Location Language",
  "status": 422,
  "code": "last_location_language",
  "detail": "A location must keep at least one language."
}

422 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's services/api/integration/v1/locations/{locationId}/services

Read a location's services

The services one location offers, in the order the location lists them (`position`, from 1). Each entry carries the catalogue service's `id` and `code`, its tenant-wide `catalogueName`, and `names`: one member per language in the location's language list — including a language since deactivated in the workspace language catalogue — whose value is the location's display-name override for that language, or `null` when it has none. A stored override for a language no longer in the location's list is not emitted, and neither is a service the location does not offer. A location the credential does not reach, a location belonging to another tenant, a permanently deleted location, and a path segment that is not an identifier at all are one and the same answer.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/services" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's services, in position order.

200 · Example

{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "code": "P663",
      "catalogueName": "Cash services",
      "position": 1,
      "names": {
        "LT": "Kasa",
        "EN": null
      }
    },
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "code": "P664",
      "catalogueName": "Card services",
      "position": 2,
      "names": {
        "LT": null,
        "EN": null
      }
    }
  ]
}

200 response schema

A location's services: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.

items · array · required

One entry per service of the location, in position order.

Show nested fields

One service of a location's list.

id · string · required

The catalogue service's opaque identifier.

code · string · required

The catalogue service's code, which never changes.

catalogueName · string · required

The service's tenant-wide name in the catalogue.

position · integer · required

The service's place in the location's list.

names · object · required

The location's display name for the service, keyed by language code: one member per language in the location's language list, the override or `null` where the location has none. A name is at most 80 characters after trimming.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's services: an object carrying exactly one member, never a bare array, so a later member can be added without breaking a generated client.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per service of the location, in position order.",
      "items": {
        "type": "object",
        "description": "One service of a location's list.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The catalogue service's opaque identifier.",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "code": {
            "type": "string",
            "description": "The catalogue service's code, which never changes.",
            "example": "P663"
          },
          "catalogueName": {
            "type": "string",
            "description": "The service's tenant-wide name in the catalogue.",
            "example": "Cash services"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The service's place in the location's list.",
            "example": 1
          },
          "names": {
            "type": "object",
            "description": "The location's display name for the service, keyed by language code: one member per language in the location's language list, the override or `null` where the location has none. A name is at most 80 characters after trimming.",
            "additionalProperties": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 80
            },
            "example": {
              "LT": "Kasa",
              "EN": null
            }
          }
        },
        "required": [
          "id",
          "code",
          "catalogueName",
          "position",
          "names"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHReorder a location service or set its display names/api/integration/v1/locations/{locationId}/services/{serviceId}

Reorder a location service or set its display names

The same write the console's location services page makes. A partial write: a member absent from the body is left alone, and at least one of `position` and `names` must be present. `position` moves the service to that place in the location's list; a value outside the list — below 1 or above its size — moves it to the nearest end, and the other services are renumbered contiguously. `names` is keyed by language code, matched exactly (upper case, as `names` is read): a string sets that language's display name for this location, and `null`, an empty string or a blank string clears it. A language `names` leaves out keeps its override. A name is at most 80 characters after trimming. A key that is not in the location's language list is refused `not_writable`, a key for a language deactivated in the workspace language catalogue `inactive`, and a longer name `too_long`; those `names` refusals of one body are reported together. A refusal of the body's shape — an unknown member, an `invalid_format` value, neither `position` nor `names` present — is reported first and alone. A refused body changes nothing — the order included. The service's `code` never changes: a body carrying a `code` member is refused. The answer is the updated entry. Requires a credential whose reach includes the location. Both a tenant administrator's and a location manager's credential reach this operation; a location outside the credential's reach is the 404, never a 403. A service the location does not offer, one of another tenant, or a segment that is not an identifier is 404 `service_not_found`.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/services/33333333-3333-4333-8333-333333333333" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "position": 1,
  "names": {
    "LT": "Kasa",
    "EN": null
  }
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
serviceId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

serviceId: The catalogue service's opaque identifier.

Request body

Example body

{
  "position": 1,
  "names": {
    "LT": "Kasa",
    "EN": null
  }
}

Request schema

At least one member must be present.

position · integer · optional

The place to move the service to. A value below 1 moves it to the first place and a value above the list's size to the last.

names · object · optional

The display names to set, keyed by language code exactly as `names` is read. A string sets the name, and `null`, an empty or a blank string clears it; a language left out keeps its override. A name is at most 80 characters after trimming.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "At least one member must be present.",
  "properties": {
    "position": {
      "type": "integer",
      "description": "The place to move the service to. A value below 1 moves it to the first place and a value above the list's size to the last.",
      "example": 1
    },
    "names": {
      "type": "object",
      "description": "The display names to set, keyed by language code exactly as `names` is read. A string sets the name, and `null`, an empty or a blank string clears it; a language left out keeps its override. A name is at most 80 characters after trimming.",
      "additionalProperties": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 80
      },
      "example": {
        "LT": "Kasa",
        "EN": null
      }
    }
  },
  "minProperties": 1,
  "additionalProperties": false
}

Responses

200 — The updated entry.

200 · Example

{
  "id": "33333333-3333-4333-8333-333333333333",
  "code": "P663",
  "catalogueName": "Cash services",
  "position": 1,
  "names": {
    "LT": "Kasa",
    "EN": null
  }
}

200 response schema

One service of a location's list.

id · string · required

The catalogue service's opaque identifier.

code · string · required

The catalogue service's code, which never changes.

catalogueName · string · required

The service's tenant-wide name in the catalogue.

position · integer · required

The service's place in the location's list.

names · object · required

The location's display name for the service, keyed by language code: one member per language in the location's language list, the override or `null` where the location has none. A name is at most 80 characters after trimming.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of a location's list.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The catalogue service's opaque identifier.",
      "example": "33333333-3333-4333-8333-333333333333"
    },
    "code": {
      "type": "string",
      "description": "The catalogue service's code, which never changes.",
      "example": "P663"
    },
    "catalogueName": {
      "type": "string",
      "description": "The service's tenant-wide name in the catalogue.",
      "example": "Cash services"
    },
    "position": {
      "type": "integer",
      "minimum": 1,
      "description": "The service's place in the location's list.",
      "example": 1
    },
    "names": {
      "type": "object",
      "description": "The location's display name for the service, keyed by language code: one member per language in the location's language list, the override or `null` where the location has none. A name is at most 80 characters after trimming.",
      "additionalProperties": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 80
      },
      "example": {
        "LT": "Kasa",
        "EN": null
      }
    }
  },
  "required": [
    "id",
    "code",
    "catalogueName",
    "position",
    "names"
  ],
  "additionalProperties": false
}

400 — The location service edit was refused before anything was written, the order included. Two codes share this status: `validation_failed` when a member the body sent is not acceptable — one `errors` entry per offending field, every `names.<code>` refusal of the body together; a refusal of the body's shape is reported first and alone — and `service_code_immutable` when the body carries a `code` member at all. Branch on `code`.

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation.",
  "errors": [
    {
      "field": "names.PL",
      "code": "not_writable"
    }
  ]
}

400 · serviceCodeImmutable

{
  "type": "urn:qms:problem:service_code_immutable",
  "title": "Service Code Immutable",
  "status": 400,
  "code": "service_code_immutable",
  "detail": "The service code cannot be changed after creation."
}

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — Nothing was found to act on. Two codes share this status: `location_not_found` when the location is outside the credential's reach, belongs to another tenant, was permanently deleted or was named by a segment that is not an identifier; and `service_not_found` when the location is reachable but does not offer the service, the service belongs to another tenant, or the segment is not an identifier. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · serviceNotFound

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's visit reasons/api/integration/v1/locations/{locationId}/visit-reasons

Read a location's visit reasons

The visit reasons operators record for a visit at this location, in the order the location lists them. The `status` query selects `active` (the default), `archived` or `all`, matched case-insensitively; any other value, an empty one included, is refused 400 `validation_failed` with field `status` and code `invalid_format`. Requires the `locations:read` scope. A location the credential does not reach, a location belonging to another tenant, a permanently deleted location, and a path segment that is not an identifier at all are one and the same answer, 404 `location_not_found`.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/visit-reasons" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
status	query	no	{"type":"string","enum":["active","archived","all"],"default":"active"}

locationId: The location's opaque identifier.

status: Which reasons to list, matched case-insensitively. Absent means `active`.

Request body

None. This operation carries no request body.

Responses

200 — The location's visit reasons.

200 · Example

{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Account opening",
      "displayOrder": 0,
      "status": "ACTIVE"
    },
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "name": "Card issue",
      "displayOrder": 1,
      "status": "ACTIVE"
    }
  ]
}

200 response schema

A location's visit reasons: an object carrying exactly one member, never a bare array.

items · array · required

One entry per reason, in display order.

Show nested fields

One visit reason of a location.

id · string · uuid · required

The reason's identifier.

name · string · required

The reason's name, as operators see it.

displayOrder · integer · required

The reason's place in the location's list, counted from 0. An archived reason keeps the place it last held, so a value can repeat across statuses.

status · string · required

Whether operators can pick the reason.

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's visit reasons: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per reason, in display order.",
      "items": {
        "type": "object",
        "description": "One visit reason of a location.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The reason's identifier.",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The reason's name, as operators see it.",
            "example": "Account opening"
          },
          "displayOrder": {
            "type": "integer",
            "minimum": 0,
            "description": "The reason's place in the location's list, counted from 0. An archived reason keeps the place it last held, so a value can repeat across statuses.",
            "example": 1
          },
          "status": {
            "type": "string",
            "description": "Whether operators can pick the reason.",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          }
        },
        "required": [
          "id",
          "name",
          "displayOrder",
          "status"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PUTReplace a location's visit reasons/api/integration/v1/locations/{locationId}/visit-reasons

Replace a location's visit reasons

Replaces the location's visit reasons with the submitted list, in the submitted order, the way the console's visit-reason editor saves. An entry that carries the `id` of one of the location's reasons keeps that reason and renames or reorders it, and when that reason was archived it is active again; an entry without `id` is a new reason; a reason of the location that no entry names is archived. The answer is the location's reasons of every status after the write. An empty `reasons` list archives every active reason. A client that sends no `id` on an entry creates a new reason every time, so replaying the same request archives the earlier reasons and creates new ones: send the `id`s to keep identity. Names are 1-100 characters after trimming and unique within the list case-insensitively. The write is all or nothing: a refused list changes nothing. A refusal is 400 `validation_failed` whose `errors` name `reasons` (`required` when absent or null, `invalid_format` when not an array), `reasons[i]` (`invalid_format` when not an object), `reasons[i].id` (`invalid_format` when not a UUID string, `not_found`, `duplicate`), `reasons[i].name` (`required`, `invalid_format` when not a string, `too_long`, `duplicate`), or any other member of the body or of an entry (`not_writable`). Requires the `locations:write` scope; a location outside the credential's reach is the 404, never a 403.

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

curl --request PUT "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/visit-reasons" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "reasons": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Account opening"
    },
    {
      "name": "Loan consultation"
    }
  ]
}'

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

Example body

{
  "reasons": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Account opening"
    },
    {
      "name": "Loan consultation"
    }
  ]
}

Request schema

The location's complete list of visit reasons. An entry that names the `id` of one of the location's reasons keeps that reason; an entry without `id` is a new reason, so a retried request that carries no `id` archives the earlier reasons and creates new ones. A reason no entry names is archived. An entry naming an archived reason's `id` makes it active again. An empty list archives every active reason.

reasons · array · required

The reasons in the order the location lists them.

Show nested fields

id · string · uuid · optional

The identifier of an existing reason of this location; absent for a new reason.

name · string · required

The reason's name: 1-100 characters after trimming, unique in the list case-insensitively.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The location's complete list of visit reasons. An entry that names the `id` of one of the location's reasons keeps that reason; an entry without `id` is a new reason, so a retried request that carries no `id` archives the earlier reasons and creates new ones. A reason no entry names is archived. An entry naming an archived reason's `id` makes it active again. An empty list archives every active reason.",
  "properties": {
    "reasons": {
      "type": "array",
      "description": "The reasons in the order the location lists them.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The identifier of an existing reason of this location; absent for a new reason.",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The reason's name: 1-100 characters after trimming, unique in the list case-insensitively.",
            "example": "Account opening"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "reasons"
  ],
  "additionalProperties": false
}

Responses

200 — The location's visit reasons of every status after the write.

200 · Example

{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Account opening",
      "displayOrder": 0,
      "status": "ACTIVE"
    },
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "name": "Card issue",
      "displayOrder": 1,
      "status": "ARCHIVED"
    },
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "Loan consultation",
      "displayOrder": 1,
      "status": "ACTIVE"
    }
  ]
}

200 response schema

A location's visit reasons: an object carrying exactly one member, never a bare array.

items · array · required

One entry per reason, in display order.

Show nested fields

One visit reason of a location.

id · string · uuid · required

The reason's identifier.

name · string · required

The reason's name, as operators see it.

displayOrder · integer · required

The reason's place in the location's list, counted from 0. An archived reason keeps the place it last held, so a value can repeat across statuses.

status · string · required

Whether operators can pick the reason.

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's visit reasons: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per reason, in display order.",
      "items": {
        "type": "object",
        "description": "One visit reason of a location.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The reason's identifier.",
            "example": "33333333-3333-4333-8333-333333333333"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The reason's name, as operators see it.",
            "example": "Account opening"
          },
          "displayOrder": {
            "type": "integer",
            "minimum": 0,
            "description": "The reason's place in the location's list, counted from 0. An archived reason keeps the place it last held, so a value can repeat across statuses.",
            "example": 1
          },
          "status": {
            "type": "string",
            "description": "Whether operators can pick the reason.",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          }
        },
        "required": [
          "id",
          "name",
          "displayOrder",
          "status"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

DELETEDelete a location's visit reason/api/integration/v1/locations/{locationId}/visit-reasons/{reasonId}

Delete a location's visit reason

Deletes one visit reason of the location. The answer is empty. Requires the `locations:write` scope. A location outside the credential's reach is 404 `location_not_found`; a reason the location does not hold is 404 `visit_reason_not_found`. Branch on `code`.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/visit-reasons/33333333-3333-4333-8333-333333333333" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}
reasonId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

reasonId: The visit reason's opaque identifier.

Request body

None. This operation carries no request body.

Responses

204 — The visit reason is deleted. RFC 9110 gives this status no body, so this answer declares no content and none is returned.

No response body.

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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — Nothing was found to act on. Two codes share this status: `location_not_found` when the location is outside the credential's reach, belongs to another tenant, was permanently deleted or was named by a segment that is not an identifier; and `visit_reason_not_found` when the location is reachable but does not hold the reason. Branch on `code`.

404 · locationNotFound

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 · visitReasonNotFound

{
  "type": "urn:qms:problem:visit_reason_not_found",
  "title": "Visit Reason Not Found",
  "status": 404,
  "code": "visit_reason_not_found",
  "detail": "No visit reason with this identifier is in this location's catalogue."
}

404 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.

500 · Example

{
  "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
}

Open operation →

GETRead a location's readiness checklist/api/integration/v1/locations/{locationId}/readiness

Read a location's readiness checklist

Whether the location is ready to serve customers: the five steps of the console's readiness checklist, in the console's order — services assigned, working hours configured, an active window, at least one operator fully configured, and at least one active visit reason — each with its status as the console shows it at the same instant. An incomplete `OPERATORS` step names which of its three conditions are missing. The checklist is advisory: no operation refuses a request because a step is incomplete. Requires the `locations:read` scope. Both management levels reach the readiness of the locations they manage — a location manager that of an assigned location, a tenant administrator that of every location — so `insufficient_authority` never answers this operation. A location outside the credential's reach, in another tenant, permanently deleted, nonexistent or named by a segment that is not an identifier at all is one answer, 404 `location_not_found`, so that the existence of another tenant's data cannot be probed.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/locations/22222222-2222-4222-8222-222222222222/readiness" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
locationId	path	yes	{"type":"string"}

locationId: The location's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The location's readiness checklist.

200 · Example

{
  "steps": [
    {
      "key": "SERVICES",
      "complete": true,
      "missing": []
    },
    {
      "key": "WORKING_HOURS",
      "complete": true,
      "missing": []
    },
    {
      "key": "WINDOWS",
      "complete": false,
      "missing": []
    },
    {
      "key": "OPERATORS",
      "complete": false,
      "missing": [
        "SERVICE"
      ]
    },
    {
      "key": "VISIT_REASONS",
      "complete": true,
      "missing": []
    }
  ],
  "completeCount": 3,
  "totalCount": 5,
  "allComplete": false
}

200 response schema

A location's readiness checklist.

steps · array · required

The five checklist steps, always in this order: SERVICES, WORKING_HOURS, WINDOWS, OPERATORS, VISIT_REASONS.

Show nested fields

One step of the readiness checklist.

key · string · required

Which step this is.

Allowed values: "SERVICES", "WORKING_HOURS", "WINDOWS", "OPERATORS", "VISIT_REASONS"

complete · boolean · required

Whether the step is complete, as the console checklist shows it.

missing · array · required

For an incomplete OPERATORS step, the conditions the location's best-configured operator still lacks; empty for every other step and for a complete OPERATORS step.

Show nested fields

Allowed values: "WINDOW", "LANGUAGE", "SERVICE"

completeCount · integer · required

The number of steps whose `complete` is true.

totalCount · integer · required

The number of entries in `steps`; always 5.

allComplete · boolean · required

True exactly when `completeCount` equals `totalCount`.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "A location's readiness checklist.",
  "properties": {
    "steps": {
      "type": "array",
      "description": "The five checklist steps, always in this order: SERVICES, WORKING_HOURS, WINDOWS, OPERATORS, VISIT_REASONS.",
      "minItems": 5,
      "maxItems": 5,
      "items": {
        "type": "object",
        "description": "One step of the readiness checklist.",
        "properties": {
          "key": {
            "type": "string",
            "description": "Which step this is.",
            "enum": [
              "SERVICES",
              "WORKING_HOURS",
              "WINDOWS",
              "OPERATORS",
              "VISIT_REASONS"
            ],
            "example": "OPERATORS"
          },
          "complete": {
            "type": "boolean",
            "description": "Whether the step is complete, as the console checklist shows it.",
            "example": false
          },
          "missing": {
            "type": "array",
            "uniqueItems": true,
            "description": "For an incomplete OPERATORS step, the conditions the location's best-configured operator still lacks; empty for every other step and for a complete OPERATORS step.",
            "items": {
              "type": "string",
              "enum": [
                "WINDOW",
                "LANGUAGE",
                "SERVICE"
              ]
            },
            "example": [
              "SERVICE"
            ]
          }
        },
        "required": [
          "key",
          "complete",
          "missing"
        ],
        "additionalProperties": false
      }
    },
    "completeCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5,
      "description": "The number of steps whose `complete` is true.",
      "example": 2
    },
    "totalCount": {
      "type": "integer",
      "minimum": 5,
      "maximum": 5,
      "description": "The number of entries in `steps`; always 5.",
      "example": 5
    },
    "allComplete": {
      "type": "boolean",
      "description": "True exactly when `completeCount` equals `totalCount`.",
      "example": false
    }
  },
  "required": [
    "steps",
    "completeCount",
    "totalCount",
    "allComplete"
  ],
  "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.

401 · Example

{
  "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 authenticated credential does not carry a scope that admits this operation. The scope check runs before every other admission check, so this refusal displaces `insufficient_authority` on an operation that requires both.

403 · Example

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential 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
}

404 — No location was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:location_not_found",
  "title": "Location Not Found",
  "status": 404,
  "code": "location_not_found",
  "detail": "No location was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Contract

Open operation →

GETFetch this OpenAPI document/api/integration/v1/openapi.json

Fetch this OpenAPI document

Serves this document itself, rendered as JSON, so a client generator can be pointed at the running build. The body is the JSON rendering of the committed YAML and changes only when the committed document does.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/openapi.json" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — This OpenAPI document, rendered as JSON. The body is an OpenAPI document object; it is described as a plain object here on purpose, so that a generator is not asked to model the OpenAPI meta-schema.

200 response schema

Raw JSON Schema

application/json

{
  "type": "object"
}

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.

401 · Example

{
  "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
}

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.

500 · Example

{
  "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
}

Services

Open operation →

GETList the tenant's service catalogue/api/integration/v1/services

List the tenant's service catalogue

Every service of the tenant, sorted by name ascending, archived ones alongside active ones and told apart by `status`. Unlike the location collection this read is not narrowed by the locations the credential reaches: the service catalogue is tenant-wide. The answer is always the object `{"items": [...]}`, never a bare array, and it is never paginated. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/services" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's services, sorted by name.

200 · Example

{
  "items": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "name": "Account opening",
      "code": "ACCT",
      "defaultDurationMinutes": 15,
      "displayPrefix": "A",
      "status": "ACTIVE"
    }
  ]
}

200 response schema

The service collection read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per service of the tenant, sorted by name.

Show nested fields

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The service collection read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per service of the tenant, sorted by name.",
      "items": {
        "type": "object",
        "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
        "properties": {
          "id": {
            "type": "string",
            "example": "77777777-7777-4777-8777-777777777777"
          },
          "name": {
            "type": "string",
            "example": "Account opening"
          },
          "code": {
            "type": "string",
            "description": "The service's own short code, fixed at creation.",
            "example": "ACCT"
          },
          "defaultDurationMinutes": {
            "type": "integer",
            "description": "How long one appointment for this service is planned to take.",
            "example": 15
          },
          "displayPrefix": {
            "type": "string",
            "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
            "example": "A"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          }
        },
        "required": [
          "id",
          "name",
          "code",
          "defaultDurationMinutes",
          "displayPrefix",
          "status"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

POSTCreate a service/api/integration/v1/services

Create a service

Creates a service in the credential's own tenant and answers it with `status` `ACTIVE`. `name`, `defaultDurationMinutes` and `displayPrefix` are required; an omitted one is reported in `errors` under its own name. `code` is optional: a body without it, or with it `null` or blank, gets a code filled in from the service name — its first four Latin letters or digits, upper case, diacritics removed, with the lowest free number appended when another service of the tenant already holds it — and the entry answered carries it. A name with no Latin letter or digit gets `S` plus the lowest free number. `displayPrefix` is the leading letters of the numbers the service issues and must not already be held by another service of the tenant; a `code` that is sent must likewise be free. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/services" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A"
}'

Parameters

None.

Request body

Example body

{
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A"
}

Request schema

The service create body. `code` is optional; the other three members are required. `paddingWidth` is deliberately not a member: the entry does not publish it, so this surface neither reads nor writes one and the system default stands.

name · string · required

code · string | null · optional

The service's own short code. Must not be held by another service. Filled in from the service name when absent, null or blank.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service will issue. Must not be held by another service of the tenant.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The service create body. `code` is optional; the other three members are required. `paddingWidth` is deliberately not a member: the entry does not publish it, so this surface neither reads nor writes one and the system default stands.",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 80,
      "example": "Account opening"
    },
    "code": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Z0-9]{1,4}$",
      "description": "The service's own short code. Must not be held by another service. Filled in from the service name when absent, null or blank.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 480,
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "pattern": "^[A-Z]{1,2}$",
      "description": "The leading letters of the ticket numbers this service will issue. Must not be held by another service of the tenant.",
      "example": "A"
    }
  },
  "required": [
    "name",
    "defaultDurationMinutes",
    "displayPrefix"
  ]
}

Responses

201 — The service as created.

201 · Example

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A",
  "status": "ACTIVE"
}

201 response schema

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
  "properties": {
    "id": {
      "type": "string",
      "example": "77777777-7777-4777-8777-777777777777"
    },
    "name": {
      "type": "string",
      "example": "Account opening"
    },
    "code": {
      "type": "string",
      "description": "The service's own short code, fixed at creation.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
      "example": "A"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ARCHIVED"
      ],
      "example": "ACTIVE"
    }
  },
  "required": [
    "id",
    "name",
    "code",
    "defaultDurationMinutes",
    "displayPrefix",
    "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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

GETRead a single service/api/integration/v1/services/{serviceId}

Read a single service

One service of the tenant, active or archived. A service of another tenant, a service that does not exist, and a path segment that is not an identifier at all are one and the same answer. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/services/77777777-7777-4777-8777-777777777777" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
serviceId	path	yes	{"type":"string"}

serviceId: The service's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The service.

200 · Example

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A",
  "status": "ACTIVE"
}

200 response schema

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
  "properties": {
    "id": {
      "type": "string",
      "example": "77777777-7777-4777-8777-777777777777"
    },
    "name": {
      "type": "string",
      "example": "Account opening"
    },
    "code": {
      "type": "string",
      "description": "The service's own short code, fixed at creation.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
      "example": "A"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ARCHIVED"
      ],
      "example": "ACTIVE"
    }
  },
  "required": [
    "id",
    "name",
    "code",
    "defaultDurationMinutes",
    "displayPrefix",
    "status"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No service was found for this identifier. In another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHEdit a service/api/integration/v1/services/{serviceId}

Edit a service

A partial edit of `name` and `defaultDurationMinutes`: a member absent from the body is left unchanged. The service's `displayPrefix` is carried forward unchanged, and the 200 answer publishes it. A body carrying a `code` member at all is refused 400 `service_code_immutable`, a value equal to the stored one included: the contract refuses the member rather than the change, so the answer never depends on the caller's knowledge of current state. That refusal is decided before the identifier is looked at, so it does not depend on the named service existing either. Requires a credential issued by a tenant administrator.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/services/77777777-7777-4777-8777-777777777777" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Account opening and advice"
}'

Parameters

Name	In	Required	Schema
serviceId	path	yes	{"type":"string"}

serviceId: The service's opaque identifier.

Request body

Example body

{
  "name": "Account opening and advice"
}

Request schema

The service edit body: `name` and `defaultDurationMinutes` only, each left unchanged when absent. Either sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged — so neither can be cleared through this operation. `code` is not a member at all — a body carrying one is refused `service_code_immutable`, a value equal to the stored one and a JSON `null` included, because the refusal is decided on the member's presence. `displayPrefix` is likewise not a member and is carried forward unchanged.

name · string · optional

defaultDurationMinutes · integer · optional

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The service edit body: `name` and `defaultDurationMinutes` only, each left unchanged when absent. Either sent as JSON `null` is indistinguishable from an absent one — both leave the stored value unchanged — so neither can be cleared through this operation. `code` is not a member at all — a body carrying one is refused `service_code_immutable`, a value equal to the stored one and a JSON `null` included, because the refusal is decided on the member's presence. `displayPrefix` is likewise not a member and is carried forward unchanged.",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 80,
      "example": "Account opening and advice"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 480,
      "example": 20
    }
  }
}

Responses

200 — The service as it stands after the edit.

200 · Example

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Account opening and advice",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A",
  "status": "ACTIVE"
}

200 response schema

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
  "properties": {
    "id": {
      "type": "string",
      "example": "77777777-7777-4777-8777-777777777777"
    },
    "name": {
      "type": "string",
      "example": "Account opening"
    },
    "code": {
      "type": "string",
      "description": "The service's own short code, fixed at creation.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
      "example": "A"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ARCHIVED"
      ],
      "example": "ACTIVE"
    }
  },
  "required": [
    "id",
    "name",
    "code",
    "defaultDurationMinutes",
    "displayPrefix",
    "status"
  ]
}

400 — The service edit was refused before anything was written. Two codes share this status: `validation_failed` when a member the body sent is not acceptable, and `service_code_immutable` when the body carries a `code` member at all. Branch on `code`.

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation.",
  "errors": [
    {
      "field": "defaultDurationMinutes",
      "code": "out_of_range"
    }
  ]
}

400 · serviceCodeImmutable

{
  "type": "urn:qms:problem:service_code_immutable",
  "title": "Service Code Immutable",
  "status": 400,
  "code": "service_code_immutable",
  "detail": "The service code cannot be changed after creation."
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No service was found for this identifier. In another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

POSTArchive a service/api/integration/v1/services/{serviceId}/archive

Archive a service

Moves an active service to `status` `ARCHIVED` and answers the updated service. The request carries no body. Three refusals share the 409. A service that is already archived cannot transition at all and is answered `service_already_archived`, and that guard is evaluated before anything is counted. A service a location template still captures is answered `service_in_template`, whose `detail` names the templates; a service blocked by anything else is answered `archive_blocked`. Those two carry one `blockers` entry per non-zero category, and which of them applies is decided by the catalogue rather than by this surface. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/services/77777777-7777-4777-8777-777777777777/archive" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
serviceId	path	yes	{"type":"string"}

serviceId: The service's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The service, now archived.

200 · Example

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A",
  "status": "ARCHIVED"
}

200 response schema

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
  "properties": {
    "id": {
      "type": "string",
      "example": "77777777-7777-4777-8777-777777777777"
    },
    "name": {
      "type": "string",
      "example": "Account opening"
    },
    "code": {
      "type": "string",
      "description": "The service's own short code, fixed at creation.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
      "example": "A"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ARCHIVED"
      ],
      "example": "ACTIVE"
    }
  },
  "required": [
    "id",
    "name",
    "code",
    "defaultDurationMinutes",
    "displayPrefix",
    "status"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No service was found for this identifier. In another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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 service archive was refused. Three codes share this status: `service_already_archived` when the service cannot transition at all, `service_in_template` when a location template still captures the service, whose `detail` names those templates, and `archive_blocked` for every other blocking category. The transition guard is evaluated before anything is counted, so an already-archived service is never answered about a blocker that may since have cleared; the other two carry one `blockers` entry per non-zero category. Branch on `code`.

409 · serviceAlreadyArchived

{
  "type": "urn:qms:problem:service_already_archived",
  "title": "Service Already Archived",
  "status": 409,
  "code": "service_already_archived",
  "detail": "The service is already archived."
}

409 · serviceInTemplate

{
  "type": "urn:qms:problem:service_in_template",
  "title": "Service In Template",
  "status": 409,
  "code": "service_in_template",
  "detail": "This service is captured by the following location templates: Branch default.",
  "blockers": [
    {
      "kind": "TEMPLATE",
      "count": 1
    }
  ]
}

409 · archiveBlocked

{
  "type": "urn:qms:problem:archive_blocked",
  "title": "Archive Blocked",
  "status": 409,
  "code": "archive_blocked",
  "detail": "The entry cannot be archived while something still depends on it.",
  "blockers": [
    {
      "kind": "LOCATION",
      "count": 2
    }
  ]
}

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.

500 · Example

{
  "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
}

Open operation →

POSTReactivate an archived service/api/integration/v1/services/{serviceId}/reactivate

Reactivate an archived service

Moves an archived service back to `status` `ACTIVE` and answers the updated service. The request carries no body. A service that is not archived is answered 409 `service_not_archived`, and that guard is evaluated before anything else, so a service that is already active is never told its own name or `code` is taken. A service whose name or `code` has since been taken by another active service is answered 400 with an `errors` entry naming the member. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/services/77777777-7777-4777-8777-777777777777/reactivate" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
serviceId	path	yes	{"type":"string"}

serviceId: The service's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The service, now active.

200 · Example

{
  "id": "77777777-7777-4777-8777-777777777777",
  "name": "Account opening",
  "code": "ACCT",
  "defaultDurationMinutes": 15,
  "displayPrefix": "A",
  "status": "ACTIVE"
}

200 response schema

One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.

id · string · required

name · string · required

code · string · required

The service's own short code, fixed at creation.

defaultDurationMinutes · integer · required

How long one appointment for this service is planned to take.

displayPrefix · string · required

The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.

status · string · required

Allowed values: "ACTIVE", "ARCHIVED"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One service of the tenant's catalogue. Every member is always present. Group membership is deliberately absent: service groups are a capability domain of their own and no scope value names them.",
  "properties": {
    "id": {
      "type": "string",
      "example": "77777777-7777-4777-8777-777777777777"
    },
    "name": {
      "type": "string",
      "example": "Account opening"
    },
    "code": {
      "type": "string",
      "description": "The service's own short code, fixed at creation.",
      "example": "ACCT"
    },
    "defaultDurationMinutes": {
      "type": "integer",
      "description": "How long one appointment for this service is planned to take.",
      "example": 15
    },
    "displayPrefix": {
      "type": "string",
      "description": "The leading letters of the ticket numbers this service issues. The width the number is padded to is not published here — it is a property of the ticket number, and this document describes no ticket-numbering operation.",
      "example": "A"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ARCHIVED"
      ],
      "example": "ACTIVE"
    }
  },
  "required": [
    "id",
    "name",
    "code",
    "defaultDurationMinutes",
    "displayPrefix",
    "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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No service was found for this identifier. In another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:service_not_found",
  "title": "Service Not Found",
  "status": 404,
  "code": "service_not_found",
  "detail": "No service was found for this identifier."
}

404 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 — A reactivate aimed at a service that is not archived. The only code at this status on the service reactivate.

409 · Example

{
  "type": "urn:qms:problem:service_not_archived",
  "title": "Service Not Archived",
  "status": 409,
  "code": "service_not_archived",
  "detail": "The service is not archived."
}

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.

500 · Example

{
  "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
}

Branding

Open operation →

GETRead the tenant's branding logo URL/api/integration/v1/branding

Read the tenant's branding logo URL

The tenant's saved branding logo, as the URL the management console serves it from. `logoUrl` is always present and is null when the tenant has saved no logo. The URL addresses the console surface under `/api/v1/`, not this one, and is NOT fetchable with an API credential: that surface is session-authenticated, so an `Authorization: Api-Key` header authenticates nothing on it. Treat the value as an identifier of the saved logo rather than as a link this credential can follow. The logo is not writable here; the homepage settings have their own operations. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/branding" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's branding logo URL, or null.

200 · Example

{
  "logoUrl": "/api/v1/m/branding/logo"
}

200 response schema

The tenant's saved branding, as this surface publishes it.

logoUrl · string | null · required

Where the management console serves the tenant's saved logo from, or null when the tenant has saved none. A console path, not a path on this surface: it is not fetchable with an API credential.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The tenant's saved branding, as this surface publishes it.",
  "properties": {
    "logoUrl": {
      "type": [
        "string",
        "null"
      ],
      "description": "Where the management console serves the tenant's saved logo from, or null when the tenant has saved none. A console path, not a path on this surface: it is not fetchable with an API credential.",
      "example": "/api/v1/m/branding/logo"
    }
  },
  "required": [
    "logoUrl"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

GETRead the tenant's customer homepage settings/api/integration/v1/branding/homepage

Read the tenant's customer homepage settings

The welcome text per language, the contact phone, the contact email and the help link the customer homepage shows. `welcomeText` holds one entry per language of the tenant's language set, keyed by the uppercase platform language code; text stored for a language outside the set is kept but not returned. `phone`, `email` and `helpLink` are always present and are null when unset. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/branding/homepage" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's homepage settings.

200 · Example

{
  "welcomeText": {
    "LT": "Sveiki atvykę",
    "EN": "Welcome"
  },
  "phone": "+370 5 123 4567",
  "email": null,
  "helpLink": "https://example.com/help"
}

200 response schema

The tenant's customer homepage settings, as this surface publishes them. Every member is always present; an unset value is null.

welcomeText · object · required

The welcome text per language of the tenant's language set, keyed by the uppercase platform language code. A language with no text is absent from the object.

phone · string | null · required

email · string | null · required

helpLink · string | null · required

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The tenant's customer homepage settings, as this surface publishes them. Every member is always present; an unset value is null.",
  "properties": {
    "welcomeText": {
      "type": "object",
      "description": "The welcome text per language of the tenant's language set, keyed by the uppercase platform language code. A language with no text is absent from the object.",
      "additionalProperties": {
        "type": "string"
      },
      "example": {
        "LT": "Sveiki atvykę"
      }
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 32,
      "example": "+370 5 123 4567"
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "example": "hello@example.com"
    },
    "helpLink": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2048,
      "example": "https://example.com/help"
    }
  },
  "required": [
    "welcomeText",
    "phone",
    "email",
    "helpLink"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

PUTReplace the tenant's customer homepage settings/api/integration/v1/branding/homepage

Replace the tenant's customer homepage settings

Replaces every homepage setting with the body's values: a member that is absent, null or blank clears the stored value, and the welcome text of each language of the tenant's language set is replaced the same way. Welcome text stored for a language outside the set is left untouched. Values are trimmed. A welcome text is at most 500 characters, a phone at most 32, a help link an absolute `http` or `https` URL of at most 2048 characters, and an email must pass the signup email format. A non-blank `welcomeText` value keyed outside the language set is refused `invalid_locale`. A refusal is 400 `validation_failed` naming every failing field as `welcomeText.<CODE>`, `phone`, `email` or `helpLink` with the code `too_long`, `invalid_format` or `invalid_locale`, and nothing is written. Every save is audited, even one that changes nothing. Requires a credential issued by a tenant administrator.

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

curl --request PUT "$QMS_BASE_URL/api/integration/v1/branding/homepage" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "welcomeText": {
    "LT": "Sveiki atvykę",
    "EN": "Welcome"
  },
  "phone": "+370 5 123 4567",
  "email": "hello@example.com",
  "helpLink": "https://example.com/help"
}'

Parameters

None.

Request body

Example body

{
  "welcomeText": {
    "LT": "Sveiki atvykę",
    "EN": "Welcome"
  },
  "phone": "+370 5 123 4567",
  "email": "hello@example.com",
  "helpLink": "https://example.com/help"
}

Request schema

The homepage settings write body. A member that is absent, null or blank clears the stored value.

welcomeText · object · optional

The welcome text per language, keyed by the uppercase platform language code of the tenant's language set.

phone · string | null · optional

email · string | null · optional

helpLink · string | null · optional

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The homepage settings write body. A member that is absent, null or blank clears the stored value.",
  "properties": {
    "welcomeText": {
      "type": "object",
      "description": "The welcome text per language, keyed by the uppercase platform language code of the tenant's language set.",
      "additionalProperties": {
        "type": [
          "string",
          "null"
        ],
        "maxLength": 500
      },
      "example": {
        "LT": "Sveiki atvykę"
      }
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 32,
      "example": "+370 5 123 4567"
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "example": "hello@example.com"
    },
    "helpLink": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2048,
      "example": "https://example.com/help"
    }
  }
}

Responses

200 — The settings as they stand after the write.

200 · Example

{
  "welcomeText": {
    "LT": "Sveiki atvykę",
    "EN": "Welcome"
  },
  "phone": "+370 5 123 4567",
  "email": "hello@example.com",
  "helpLink": "https://example.com/help"
}

200 response schema

The tenant's customer homepage settings, as this surface publishes them. Every member is always present; an unset value is null.

welcomeText · object · required

The welcome text per language of the tenant's language set, keyed by the uppercase platform language code. A language with no text is absent from the object.

phone · string | null · required

email · string | null · required

helpLink · string | null · required

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The tenant's customer homepage settings, as this surface publishes them. Every member is always present; an unset value is null.",
  "properties": {
    "welcomeText": {
      "type": "object",
      "description": "The welcome text per language of the tenant's language set, keyed by the uppercase platform language code. A language with no text is absent from the object.",
      "additionalProperties": {
        "type": "string"
      },
      "example": {
        "LT": "Sveiki atvykę"
      }
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 32,
      "example": "+370 5 123 4567"
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "example": "hello@example.com"
    },
    "helpLink": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2048,
      "example": "https://example.com/help"
    }
  },
  "required": [
    "welcomeText",
    "phone",
    "email",
    "helpLink"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Templates

Open operation →

GETList the tenant's location templates/api/integration/v1/location-templates

List the tenant's location templates

Every location template of the tenant, sorted by name ascending, each with its captured configuration and the locations provisioned from it. Templates are tenant-wide rather than narrowed by the locations the credential reaches, so this read never answers 404. The answer is always the object `{"items": [...]}`, never a bare array, and it is never paginated. The operation declares no query parameter, and one supplied anyway changes neither the status nor the body. Requires a credential issued by a tenant administrator — on this read as well as on the writes.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/location-templates" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's location templates, sorted by name.

200 · Example

{
  "items": [
    {
      "id": "99999999-9999-4999-8999-999999999999",
      "name": "Branch standard",
      "description": "The layout every high-street branch starts from.",
      "linkedLocationIds": [
        "22222222-2222-4222-8222-222222222222"
      ],
      "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
      }
    }
  ]
}

200 response schema

The template collection read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per template of the tenant, sorted by name.

Show nested fields

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": "The template collection read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per template of the tenant, sorted by name.",
      "items": {
        "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"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

POSTCreate a location template/api/integration/v1/location-templates

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. `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

• 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

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

Example 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.

201 · Example

{
  "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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

GETRead a single location template/api/integration/v1/location-templates/{templateId}

Read a single location template

One template of the tenant, with its captured configuration and the locations provisioned from it. A template belonging to another tenant, a deleted one, and a path segment that is not an identifier at all are one and the same answer. Requires a credential issued by a tenant administrator. The authority refusal is decided on the route and the issuing user alone, never on whether the named template exists, so a credential without it is answered 403 for a template that does not exist too.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/location-templates/99999999-9999-4999-8999-999999999999" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
templateId	path	yes	{"type":"string"}

templateId: The template's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The template.

200 · Example

{
  "id": "99999999-9999-4999-8999-999999999999",
  "name": "Branch standard",
  "description": "The layout every high-street branch starts from.",
  "linkedLocationIds": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "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
  }
}

200 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"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No location template was found for this identifier. Belonging to another tenant, deleted, and never having existed are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:template_not_found",
  "title": "Template Not Found",
  "status": 404,
  "code": "template_not_found",
  "detail": "No location template was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHEdit a location template/api/integration/v1/location-templates/{templateId}

Edit a location template

A partial edit at the top level: `name`, `description` and `configuration` are each left unchanged when absent. `configuration` is partial one level down too — a `configuration` carrying `operatingHours` alone replaces the captured schedule and leaves the captured services and windows as they were. Inside `configuration` a group that IS carried replaces what the template captured, all three of them: a service or a window not named in the array it belongs to is dropped from the template, and a carried `operatingHours` must name all seven days or is refused `required`, so no day is dropped by omission. That is where a template differs from a location — on the location write `windows` upserts and deletes nothing, while here a captured window not named in the array is deleted. `services` and `operatingHours` replace on both. Editing a template changes no location already provisioned from it. Each linked location keeps the configuration it holds and stays linked; the template's new snapshot reaches a location only when it is applied again. Requires a credential issued by a tenant administrator.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/location-templates/99999999-9999-4999-8999-999999999999" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Branch standard, extended hours",
  "configuration": {
    "operatingHours": [
      {
        "day": "MON",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "TUE",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "WED",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "THU",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "FRI",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "SAT",
        "opensAt": null,
        "closesAt": null,
        "closed": true
      },
      {
        "day": "SUN",
        "opensAt": null,
        "closesAt": null,
        "closed": true
      }
    ]
  }
}'

Parameters

Name	In	Required	Schema
templateId	path	yes	{"type":"string"}

templateId: The template's opaque identifier.

Request body

Example body

{
  "name": "Branch standard, extended hours",
  "configuration": {
    "operatingHours": [
      {
        "day": "MON",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "TUE",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "WED",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "THU",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "FRI",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "SAT",
        "opensAt": null,
        "closesAt": null,
        "closed": true
      },
      {
        "day": "SUN",
        "opensAt": null,
        "closesAt": null,
        "closed": true
      }
    ]
  }
}

Request schema

The template edit body. Every member is optional and one left out is left unchanged, `configuration` included — and `configuration` is partial one level down as well, so a group it does not carry keeps whatever the template captured.

name · string · optional

description · string · optional

configuration · object · optional

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 edit body. Every member is optional and one left out is left unchanged, `configuration` included — and `configuration` is partial one level down as well, so a group it does not carry keeps whatever the template captured.",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "example": "Branch standard, extended hours"
    },
    "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
        }
      }
    }
  }
}

Responses

200 — The template as it stands after the edit.

200 · Example

{
  "id": "99999999-9999-4999-8999-999999999999",
  "name": "Branch standard, extended hours",
  "description": "The layout every high-street branch starts from.",
  "linkedLocationIds": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "configuration": {
    "services": [
      {
        "id": "77777777-7777-4777-8777-777777777777",
        "defaultDurationMinutes": 30
      }
    ],
    "windows": [
      {
        "id": "A1",
        "floor": "Ground",
        "status": "ACTIVE"
      }
    ],
    "operatingHours": [
      {
        "day": "MON",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "TUE",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "WED",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "THU",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "closed": false
      },
      {
        "day": "FRI",
        "opensAt": "08:00",
        "closesAt": "19:00",
        "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
  }
}

200 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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No location template was found for this identifier. Belonging to another tenant, deleted, and never having existed are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:template_not_found",
  "title": "Template Not Found",
  "status": 404,
  "code": "template_not_found",
  "detail": "No location template was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

DELETEDelete a location template/api/integration/v1/location-templates/{templateId}

Delete a location template

Deletes the template and answers 204 with no body. The request carries no body either. Every location provisioned from the template becomes independent: its `template` member reads null from the next configuration read, and the configuration it holds — services, windows, operating hours and the scalars — is left exactly as it was. Nothing about a linked location is undone by the delete, and a linked location never blocks it. Requires a credential issued by a tenant administrator.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/location-templates/99999999-9999-4999-8999-999999999999" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
templateId	path	yes	{"type":"string"}

templateId: The template's opaque identifier.

Request body

None. This operation carries no request body.

Responses

204 — The template is deleted. RFC 9110 gives this status no body, so this answer declares no content and none is returned.

No response body.

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No location template was found for this identifier. Belonging to another tenant, deleted, and never having existed are one answer, so that the existence of another tenant's data cannot be probed, and a path segment that is not an identifier at all names nothing for the same reason.

404 · Example

{
  "type": "urn:qms:problem:template_not_found",
  "title": "Template Not Found",
  "status": 404,
  "code": "template_not_found",
  "detail": "No location template was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Other

Open operation →

GETList the active subscription plans/api/integration/v1/plans

List the active subscription plans

Every active subscription plan, in display order and then by plan id. Every price is in euro cents for every workspace, whatever currency the workspace shows elsewhere; no response carries a currency member. Prices are whole euro cents: `monthlyPriceCents` is the monthly price, `quarterlyPriceCents` the price of three months at a ten percent discount and `annualPriceCents` the price of twelve months at a twenty percent discount. The monthly price less the discount is rounded down to a whole euro, then multiplied by three or twelve months, so both are whole multiples of 100 cents. `maxLocations` is the number of locations the plan allows. A deactivated plan is not listed. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/plans" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The active subscription plans, in display order.

200 · Example

{
  "items": [
    {
      "planId": "starter",
      "displayName": "Starter",
      "monthlyPriceCents": 7900,
      "quarterlyPriceCents": 21300,
      "annualPriceCents": 75600,
      "maxLocations": 1
    },
    {
      "planId": "starter-plus",
      "displayName": "Starter Plus",
      "monthlyPriceCents": 12900,
      "quarterlyPriceCents": 34800,
      "annualPriceCents": 123600,
      "maxLocations": 3
    },
    {
      "planId": "business",
      "displayName": "Business",
      "monthlyPriceCents": 17900,
      "quarterlyPriceCents": 48300,
      "annualPriceCents": 171600,
      "maxLocations": 5
    }
  ]
}

200 response schema

The plan list read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per active plan, in display order and then by plan id.

Show nested fields

One active subscription plan. Every member is always present.

planId · string · required

The plan's stable identifier, a lowercase slug.

displayName · string · required

The plan's name as the platform operator entered it.

monthlyPriceCents · integer · int64 · required

The monthly price in euro cents.

quarterlyPriceCents · integer · int64 · required

The price of three months at a ten percent discount, in euro cents.

annualPriceCents · integer · int64 · required

The price of twelve months at a twenty percent discount, in euro cents.

maxLocations · integer · required

The number of locations the plan allows.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The plan list read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per active plan, in display order and then by plan id.",
      "items": {
        "type": "object",
        "description": "One active subscription plan. Every member is always present.",
        "properties": {
          "planId": {
            "type": "string",
            "description": "The plan's stable identifier, a lowercase slug.",
            "example": "starter"
          },
          "displayName": {
            "type": "string",
            "description": "The plan's name as the platform operator entered it.",
            "example": "Starter"
          },
          "monthlyPriceCents": {
            "type": "integer",
            "format": "int64",
            "description": "The monthly price in euro cents.",
            "example": 7900
          },
          "quarterlyPriceCents": {
            "type": "integer",
            "format": "int64",
            "description": "The price of three months at a ten percent discount, in euro cents.",
            "example": 21300
          },
          "annualPriceCents": {
            "type": "integer",
            "format": "int64",
            "description": "The price of twelve months at a twenty percent discount, in euro cents.",
            "example": 75600
          },
          "maxLocations": {
            "type": "integer",
            "description": "The number of locations the plan allows.",
            "example": 1
          }
        },
        "required": [
          "planId",
          "displayName",
          "monthlyPriceCents",
          "quarterlyPriceCents",
          "annualPriceCents",
          "maxLocations"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Settings

Open operation →

GETRead the tenant's customer authentication policy/api/integration/v1/settings/customer-authentication

Read the tenant's customer authentication policy

The tenant-wide policy governing whether a ticket carries a customer's identity: `off`, `optional` or `required`. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/settings/customer-authentication" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's customer authentication policy.

200 · Example

{
  "policy": "optional"
}

200 response schema

The tenant's customer authentication policy, as this surface publishes it.

policy · string · required

Allowed values: "off", "optional", "required"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The tenant's customer authentication policy, as this surface publishes it.",
  "properties": {
    "policy": {
      "type": "string",
      "enum": [
        "off",
        "optional",
        "required"
      ],
      "example": "optional"
    }
  },
  "required": [
    "policy"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

PUTSet the tenant's customer authentication policy/api/integration/v1/settings/customer-authentication

Set the tenant's customer authentication policy

Sets the tenant-wide policy to `off`, `optional` or `required`. `policy` is required and must be one of the three values; any other value, or an absent member, is refused 400 `validation_failed` naming `policy`. Setting `optional` or `required` while the tenant has no enabled identity-provider registration is refused 422 `idp_not_configured`, and the stored value is left unchanged. Setting `required` while the primary registration carries `activatedWithoutTest` is refused 409 `primary_not_verified`; run a test sign-in of the primary in the management console first. The stored value is left unchanged. Setting the value already stored writes nothing and answers 200 with that same value. Requires a credential issued by a tenant administrator.

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

curl --request PUT "$QMS_BASE_URL/api/integration/v1/settings/customer-authentication" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "policy": "required"
}'

Parameters

None.

Request body

Example body

{
  "policy": "required"
}

Request schema

The customer authentication policy write body: `policy` alone, required, and must be one of the three values.

policy · string · required

Allowed values: "off", "optional", "required"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The customer authentication policy write body: `policy` alone, required, and must be one of the three values.",
  "properties": {
    "policy": {
      "type": "string",
      "enum": [
        "off",
        "optional",
        "required"
      ],
      "example": "required"
    }
  },
  "required": [
    "policy"
  ]
}

Responses

200 — The policy as it stands after the write.

200 · Example

{
  "policy": "required"
}

200 response schema

The tenant's customer authentication policy, as this surface publishes it.

policy · string · required

Allowed values: "off", "optional", "required"

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The tenant's customer authentication policy, as this surface publishes it.",
  "properties": {
    "policy": {
      "type": "string",
      "enum": [
        "off",
        "optional",
        "required"
      ],
      "example": "optional"
    }
  },
  "required": [
    "policy"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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 primary registration carries `activatedWithoutTest` while the customer authentication policy would be `required`. Nothing was written; run a test sign-in of the primary in the management console first.

409 · Example

{
  "type": "urn:qms:problem:primary_not_verified",
  "title": "Primary Not Verified",
  "status": 409,
  "code": "primary_not_verified",
  "detail": "The primary would carry activatedWithoutTest while the customer-authentication policy is required."
}

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
}

422 — The write set the policy to `optional` or `required` while the tenant has no enabled identity-provider registration. The stored value is left unchanged.

422 · Example

{
  "type": "urn:qms:problem:idp_not_configured",
  "title": "Idp Not Configured",
  "status": 422,
  "code": "idp_not_configured",
  "detail": "The tenant has no customer identity configured."
}

422 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.

500 · Example

{
  "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
}

Open operation →

GETList the tenant's identity-provider registrations/api/integration/v1/settings/identity-providers

List the tenant's identity-provider registrations

Every identity-provider registration of the tenant, in display order, each with its client authentication state. `clientSecretConfigured` is true when a client secret is stored for this registration, and the secret itself and its ciphertext are never sent, on this read or on any other. `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/settings/identity-providers" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The tenant's identity-provider registrations, in display order.

200 · Example

{
  "items": [
    {
      "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "displayName": "Acme SSO",
      "kind": "OIDC",
      "enabled": true,
      "primary": true,
      "issuerUrl": "https://sso.example.com",
      "clientId": "acme-qms",
      "clientAuthMethod": "none",
      "clientSecretConfigured": false,
      "clientSecretUpdatedAt": null,
      "verifiedAt": null,
      "activatedWithoutTest": false
    },
    {
      "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
      "displayName": "Acme Support Desk SSO",
      "kind": "OIDC",
      "enabled": true,
      "primary": false,
      "issuerUrl": "https://support-sso.example.com",
      "clientId": "acme-support-qms",
      "clientAuthMethod": "client_secret_basic",
      "clientSecretConfigured": true,
      "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
      "verifiedAt": "2026-09-10T09:05:00.000Z",
      "activatedWithoutTest": false
    }
  ]
}

200 response schema

The identity-provider list read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per identity-provider registration of the tenant, in display order.

Show nested fields

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The identity-provider list read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per identity-provider registration of the tenant, in display order.",
      "items": {
        "type": "object",
        "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The registration's own opaque identifier.",
            "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
          },
          "displayName": {
            "type": "string",
            "example": "Acme Support Desk SSO"
          },
          "kind": {
            "type": "string",
            "description": "The adapter kind this registration configures.",
            "enum": [
              "OIDC"
            ],
            "example": "OIDC"
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the tenant's primary identity provider.",
            "example": false
          },
          "issuerUrl": {
            "type": [
              "string",
              "null"
            ],
            "example": "https://support-sso.example.com"
          },
          "clientId": {
            "type": [
              "string",
              "null"
            ],
            "example": "acme-support-qms"
          },
          "clientAuthMethod": {
            "type": "string",
            "description": "How this registration authenticates the token request.",
            "enum": [
              "none",
              "client_secret_basic",
              "client_secret_post"
            ],
            "example": "client_secret_basic"
          },
          "clientSecretConfigured": {
            "type": "boolean",
            "description": "Whether a client secret is stored for this registration.",
            "example": true
          },
          "clientSecretUpdatedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the stored client secret was last set or replaced, or null when none is stored.",
            "example": "2026-09-10T09:00:00.000Z"
          },
          "verifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
            "example": "2026-09-10T09:05:00.000Z"
          },
          "activatedWithoutTest": {
            "type": "boolean",
            "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
            "example": false
          }
        },
        "required": [
          "id",
          "displayName",
          "kind",
          "enabled",
          "primary",
          "issuerUrl",
          "clientId",
          "clientAuthMethod",
          "clientSecretConfigured",
          "clientSecretUpdatedAt",
          "verifiedAt",
          "activatedWithoutTest"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

POSTCreate an identity-provider registration/api/integration/v1/settings/identity-providers

Create an identity-provider registration

Creates a registration of the given `kind` from the connection details in the body — the same rules the tenant-admin console's create applies. `kind`, `displayName`, `issuerUrl` and `clientId` are required; an unrecognised `kind` is refused 400 `unknown_client_idp_kind`, a missing `issuerUrl` 400 `issuer_url_required` and a missing `clientId` 400 `client_id_required`. A secret-based `clientAuthMethod` takes its `clientSecret` here, stored sealed and never sent back. The registration is created disabled, not primary and unverified, with `verifiedAt` null and `activatedWithoutTest` false; the primary is unchanged. Enable it with the enable operation. Answers 201 with the new registration. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "kind": "OIDC",
  "displayName": "Acme Support Desk SSO",
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecret": "CHANGE-ME-EXAMPLE-CLIENT-SECRET"
}'

Parameters

None.

Request body

Example body

{
  "kind": "OIDC",
  "displayName": "Acme Support Desk SSO",
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecret": "CHANGE-ME-EXAMPLE-CLIENT-SECRET"
}

Request schema

The create body. `clientSecret` is write-only: it is never present on a response.

kind · string · required

The adapter kind to configure. Only `OIDC` is supported.

displayName · string · required

issuerUrl · string · required

The https issuer URL of the provider.

clientId · string · required

clientAuthMethod · string · optional

How the registration authenticates the token request. Absent means `none`.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecret · string · optional

scopes · array · optional

The scopes to request. Absent applies the default scopes.

Show nested fields

nameClaim · string · optional

emailClaim · string · optional

languageClaim · string · optional

priorityClaim · string · optional

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The create body. `clientSecret` is write-only: it is never present on a response.",
  "properties": {
    "kind": {
      "type": "string",
      "description": "The adapter kind to configure. Only `OIDC` is supported.",
      "example": "OIDC"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "issuerUrl": {
      "type": "string",
      "description": "The https issuer URL of the provider.",
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": "string",
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How the registration authenticates the token request. Absent means `none`.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecret": {
      "type": "string",
      "writeOnly": true,
      "maxLength": 512,
      "example": "CHANGE-ME-EXAMPLE-CLIENT-SECRET"
    },
    "scopes": {
      "type": "array",
      "description": "The scopes to request. Absent applies the default scopes.",
      "items": {
        "type": "string"
      },
      "example": [
        "openid",
        "email"
      ]
    },
    "nameClaim": {
      "type": "string",
      "example": "name"
    },
    "emailClaim": {
      "type": "string",
      "example": "email"
    },
    "languageClaim": {
      "type": "string",
      "example": "locale"
    },
    "priorityClaim": {
      "type": "string",
      "example": "priority"
    }
  },
  "required": [
    "kind",
    "displayName",
    "issuerUrl",
    "clientId"
  ]
}

Responses

201 — The new registration.

201 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": false,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": null,
  "activatedWithoutTest": false
}

201 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

400 — The create or reconfigure was refused before anything was written. Branch on `code`: `issuer_url_required`, `client_id_required`, `unknown_client_idp_kind` (create), `adapter_kind_immutable` (reconfigure), the four client-authentication codes (`unsupported_client_auth_method`, `client_secret_required`, `client_secret_not_allowed`, `client_secret_invalid`) and `validation_failed` for a body that could not be read, for a create with a missing or blank `kind` or `displayName`, and for a reconfigure with a member of the wrong type (`kind`, `acceptUnverified`) or a blank `displayName`; the `errors` array names the member.

400 · issuerUrlRequired

{
  "type": "urn:qms:problem:issuer_url_required",
  "title": "Issuer Url Required",
  "status": 400,
  "code": "issuer_url_required",
  "detail": "An https issuer URL is required."
}

400 · clientIdRequired

{
  "type": "urn:qms:problem:client_id_required",
  "title": "Client Id Required",
  "status": 400,
  "code": "client_id_required",
  "detail": "A client id is required."
}

400 · unknownClientIdpKind

{
  "type": "urn:qms:problem:unknown_client_idp_kind",
  "title": "Unknown Client Idp Kind",
  "status": 400,
  "code": "unknown_client_idp_kind",
  "detail": "This identity-provider kind is not supported."
}

400 · adapterKindImmutable

{
  "type": "urn:qms:problem:adapter_kind_immutable",
  "title": "Adapter Kind Immutable",
  "status": 400,
  "code": "adapter_kind_immutable",
  "detail": "The kind of a registration cannot be changed after creation."
}

400 · unsupportedClientAuthMethod

{
  "type": "urn:qms:problem:unsupported_client_auth_method",
  "title": "Unsupported Client Authentication Method",
  "status": 400,
  "code": "unsupported_client_auth_method",
  "detail": "This client authentication method is not supported."
}

400 · clientSecretRequired

{
  "type": "urn:qms:problem:client_secret_required",
  "title": "Client Secret Required",
  "status": 400,
  "code": "client_secret_required",
  "detail": "This client authentication method needs a client secret and none is stored."
}

400 · clientSecretNotAllowed

{
  "type": "urn:qms:problem:client_secret_not_allowed",
  "title": "Client Secret Not Allowed",
  "status": 400,
  "code": "client_secret_not_allowed",
  "detail": "The method none does not accept a client secret."
}

400 · clientSecretInvalid

{
  "type": "urn:qms:problem:client_secret_invalid",
  "title": "Client Secret Invalid",
  "status": 400,
  "code": "client_secret_invalid",
  "detail": "The client secret value is not acceptable."
}

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation."
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

503 — The client secret could not be sealed because the deployment's key-management service is unavailable. Nothing was written; retry once the service is reachable again.

503 · Example

{
  "type": "urn:qms:problem:client_secret_storage_unavailable",
  "title": "Client Secret Storage Unavailable",
  "status": 503,
  "code": "client_secret_storage_unavailable",
  "detail": "Client secret storage is unavailable; nothing was written."
}

503 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
}

Open operation →

POSTReorder the tenant's identity-provider registrations/api/integration/v1/settings/identity-providers/reorder

Reorder the tenant's identity-provider registrations

Applies `orderedIds` as the new display order. The list must name the tenant's complete set of registrations, each exactly once; anything else, an identifier that names no registration included, is refused 400 `reorder_set_incomplete` and the order is unchanged. An absent `orderedIds` is refused 400 `validation_failed`. Answers 200 with the registrations in their new order. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/reorder" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "orderedIds": [
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
  ]
}'

Parameters

None.

Request body

Example body

{
  "orderedIds": [
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
  ]
}

Request schema

The reorder body.

orderedIds · array · required

The tenant's complete set of registration identifiers, each exactly once, in the new display order.

Show nested fields

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The reorder body.",
  "properties": {
    "orderedIds": {
      "type": "array",
      "description": "The tenant's complete set of registration identifiers, each exactly once, in the new display order.",
      "items": {
        "type": "string"
      },
      "example": [
        "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
        "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
      ]
    }
  },
  "required": [
    "orderedIds"
  ]
}

Responses

200 — The tenant's registrations in their new display order.

200 · Example

{
  "items": [
    {
      "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
      "displayName": "Acme Support Desk SSO",
      "kind": "OIDC",
      "enabled": true,
      "primary": false,
      "issuerUrl": "https://support-sso.example.com",
      "clientId": "acme-support-qms",
      "clientAuthMethod": "client_secret_basic",
      "clientSecretConfigured": true,
      "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
      "verifiedAt": "2026-09-10T09:05:00.000Z",
      "activatedWithoutTest": false
    }
  ]
}

200 response schema

The identity-provider list read's answer: an object carrying exactly one member, never a bare array.

items · array · required

One entry per identity-provider registration of the tenant, in display order.

Show nested fields

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The identity-provider list read's answer: an object carrying exactly one member, never a bare array.",
  "properties": {
    "items": {
      "type": "array",
      "description": "One entry per identity-provider registration of the tenant, in display order.",
      "items": {
        "type": "object",
        "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The registration's own opaque identifier.",
            "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
          },
          "displayName": {
            "type": "string",
            "example": "Acme Support Desk SSO"
          },
          "kind": {
            "type": "string",
            "description": "The adapter kind this registration configures.",
            "enum": [
              "OIDC"
            ],
            "example": "OIDC"
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the tenant's primary identity provider.",
            "example": false
          },
          "issuerUrl": {
            "type": [
              "string",
              "null"
            ],
            "example": "https://support-sso.example.com"
          },
          "clientId": {
            "type": [
              "string",
              "null"
            ],
            "example": "acme-support-qms"
          },
          "clientAuthMethod": {
            "type": "string",
            "description": "How this registration authenticates the token request.",
            "enum": [
              "none",
              "client_secret_basic",
              "client_secret_post"
            ],
            "example": "client_secret_basic"
          },
          "clientSecretConfigured": {
            "type": "boolean",
            "description": "Whether a client secret is stored for this registration.",
            "example": true
          },
          "clientSecretUpdatedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the stored client secret was last set or replaced, or null when none is stored.",
            "example": "2026-09-10T09:00:00.000Z"
          },
          "verifiedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
            "example": "2026-09-10T09:05:00.000Z"
          },
          "activatedWithoutTest": {
            "type": "boolean",
            "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
            "example": false
          }
        },
        "required": [
          "id",
          "displayName",
          "kind",
          "enabled",
          "primary",
          "issuerUrl",
          "clientId",
          "clientAuthMethod",
          "clientSecretConfigured",
          "clientSecretUpdatedAt",
          "verifiedAt",
          "activatedWithoutTest"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

400 — The reorder was refused before anything was written. Two codes share this status: `reorder_set_incomplete` when `orderedIds` is not the tenant's complete set of registrations, each exactly once, and `validation_failed` when it is absent. Branch on `code`.

400 · reorderSetIncomplete

{
  "type": "urn:qms:problem:reorder_set_incomplete",
  "title": "Reorder Set Incomplete",
  "status": 400,
  "code": "reorder_set_incomplete",
  "detail": "A reorder names the tenant's complete set of registration ids, each exactly once."
}

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation."
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

GETRead a single identity-provider registration/api/integration/v1/settings/identity-providers/{providerId}

Read a single identity-provider registration

One identity-provider registration, in the same shape the collection read gives each entry. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The identity-provider registration.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": true,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PATCHReconfigure an identity-provider registration/api/integration/v1/settings/identity-providers/{providerId}

Reconfigure an identity-provider registration

Changes the members the body names and keeps every one it omits. An explicit `null` clears an optional member (`scopes` and the claim names fall back to their defaults) and is refused for `issuerUrl` and `clientId`, which a registration always holds. `kind` is immutable: a value other than the stored one is refused 400 `adapter_kind_immutable`. The same refusals as the create apply to the connection details. A change to the connection or the client secret clears `verifiedAt`. On an enabled registration it is refused 409 `registration_not_verified` unless the request sets `acceptUnverified` to true: the issuer URL the registration would then hold is checked before anything is written, a failed check is refused 422 `connection_check_failed` naming the failure in `checkCode`, and a passing one applies the change with `activatedWithoutTest` true. While the customer authentication policy is `required` the same change on the primary is refused 409 `primary_not_verified` instead, before the check runs. A change that needs no test applies as it would without `acceptUnverified` and sets no marker. Answers 200 with the updated registration. Requires a credential issued by a tenant administrator.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "issuerUrl": "https://login.example.com",
  "acceptUnverified": true
}'

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

Example body

{
  "issuerUrl": "https://login.example.com",
  "acceptUnverified": true
}

Request schema

The reconfigure body. A member the body omits keeps its stored value; an explicit `null` on `scopes` or a claim name clears it, and on `issuerUrl` or `clientId` is refused. `clientSecret` is write-only: it is never present on a response, and omitting it leaves any stored secret untouched.

kind · string · optional

Must equal the stored kind; any other value is refused.

displayName · string · optional

issuerUrl · string | null · optional

clientId · string | null · optional

clientAuthMethod · string · optional

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecret · string · optional

scopes · array | null · optional

Show nested fields

nameClaim · string | null · optional

emailClaim · string | null · optional

languageClaim · string | null · optional

priorityClaim · string | null · optional

acceptUnverified · boolean · optional

Applies a connection change without a test sign-in after a passing connection check. Absent means false.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The reconfigure body. A member the body omits keeps its stored value; an explicit `null` on `scopes` or a claim name clears it, and on `issuerUrl` or `clientId` is refused. `clientSecret` is write-only: it is never present on a response, and omitting it leaves any stored secret untouched.",
  "properties": {
    "kind": {
      "type": "string",
      "description": "Must equal the stored kind; any other value is refused.",
      "example": "OIDC"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://login.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecret": {
      "type": "string",
      "writeOnly": true,
      "maxLength": 512,
      "example": "CHANGE-ME-EXAMPLE-CLIENT-SECRET"
    },
    "scopes": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "openid",
        "email"
      ]
    },
    "nameClaim": {
      "type": [
        "string",
        "null"
      ],
      "example": "name"
    },
    "emailClaim": {
      "type": [
        "string",
        "null"
      ],
      "example": "email"
    },
    "languageClaim": {
      "type": [
        "string",
        "null"
      ],
      "example": "locale"
    },
    "priorityClaim": {
      "type": [
        "string",
        "null"
      ],
      "example": "priority"
    },
    "acceptUnverified": {
      "type": "boolean",
      "description": "Applies a connection change without a test sign-in after a passing connection check. Absent means false.",
      "example": false
    }
  }
}

Responses

200 — The registration as it stands after the write.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": true,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

400 — The create or reconfigure was refused before anything was written. Branch on `code`: `issuer_url_required`, `client_id_required`, `unknown_client_idp_kind` (create), `adapter_kind_immutable` (reconfigure), the four client-authentication codes (`unsupported_client_auth_method`, `client_secret_required`, `client_secret_not_allowed`, `client_secret_invalid`) and `validation_failed` for a body that could not be read, for a create with a missing or blank `kind` or `displayName`, and for a reconfigure with a member of the wrong type (`kind`, `acceptUnverified`) or a blank `displayName`; the `errors` array names the member.

400 · issuerUrlRequired

{
  "type": "urn:qms:problem:issuer_url_required",
  "title": "Issuer Url Required",
  "status": 400,
  "code": "issuer_url_required",
  "detail": "An https issuer URL is required."
}

400 · clientIdRequired

{
  "type": "urn:qms:problem:client_id_required",
  "title": "Client Id Required",
  "status": 400,
  "code": "client_id_required",
  "detail": "A client id is required."
}

400 · unknownClientIdpKind

{
  "type": "urn:qms:problem:unknown_client_idp_kind",
  "title": "Unknown Client Idp Kind",
  "status": 400,
  "code": "unknown_client_idp_kind",
  "detail": "This identity-provider kind is not supported."
}

400 · adapterKindImmutable

{
  "type": "urn:qms:problem:adapter_kind_immutable",
  "title": "Adapter Kind Immutable",
  "status": 400,
  "code": "adapter_kind_immutable",
  "detail": "The kind of a registration cannot be changed after creation."
}

400 · unsupportedClientAuthMethod

{
  "type": "urn:qms:problem:unsupported_client_auth_method",
  "title": "Unsupported Client Authentication Method",
  "status": 400,
  "code": "unsupported_client_auth_method",
  "detail": "This client authentication method is not supported."
}

400 · clientSecretRequired

{
  "type": "urn:qms:problem:client_secret_required",
  "title": "Client Secret Required",
  "status": 400,
  "code": "client_secret_required",
  "detail": "This client authentication method needs a client secret and none is stored."
}

400 · clientSecretNotAllowed

{
  "type": "urn:qms:problem:client_secret_not_allowed",
  "title": "Client Secret Not Allowed",
  "status": 400,
  "code": "client_secret_not_allowed",
  "detail": "The method none does not accept a client secret."
}

400 · clientSecretInvalid

{
  "type": "urn:qms:problem:client_secret_invalid",
  "title": "Client Secret Invalid",
  "status": 400,
  "code": "client_secret_invalid",
  "detail": "The client secret value is not acceptable."
}

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation."
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 write needs a test it does not have. Two codes share this status: `registration_not_verified` when the registration is not verified and the request did not set `acceptUnverified`, and `primary_not_verified` when `acceptUnverified` would leave the primary carrying `activatedWithoutTest` under a required policy. Nothing was written. Branch on `code`.

409 · registrationNotVerified

{
  "type": "urn:qms:problem:registration_not_verified",
  "title": "Registration Not Verified",
  "status": 409,
  "code": "registration_not_verified",
  "detail": "The registration's connection is not verified."
}

409 · primaryNotVerified

{
  "type": "urn:qms:problem:primary_not_verified",
  "title": "Primary Not Verified",
  "status": 409,
  "code": "primary_not_verified",
  "detail": "The primary would carry activatedWithoutTest while the customer-authentication policy is required."
}

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
}

422 — The request set `acceptUnverified` and the connection check of the issuer URL the registration would hold failed. `checkCode` names the failure: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Nothing was written.

422 · Example

{
  "type": "urn:qms:problem:connection_check_failed",
  "title": "Connection Check Failed",
  "status": 422,
  "code": "connection_check_failed",
  "detail": "The connection check of the resulting issuer URL failed; nothing was written.",
  "checkCode": "unreachable"
}

422 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.

500 · Example

{
  "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
}

503 — The client secret could not be sealed because the deployment's key-management service is unavailable. Nothing was written; retry once the service is reachable again.

503 · Example

{
  "type": "urn:qms:problem:client_secret_storage_unavailable",
  "title": "Client Secret Storage Unavailable",
  "status": 503,
  "code": "client_secret_storage_unavailable",
  "detail": "Client secret storage is unavailable; nothing was written."
}

503 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
}

Open operation →

DELETERemove an identity-provider registration/api/integration/v1/settings/identity-providers/{providerId}

Remove an identity-provider registration

Deletes the registration together with its stored client secret. The primary cannot be removed while other registrations exist (409 `primary_registration_cannot_be_removed`), and the last registration cannot be removed while the customer authentication policy is not `off` (409 `policy_requires_idp`). Answers 204. Requires a credential issued by a tenant administrator.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

None. This operation carries no request body.

Responses

204 — The registration was removed.

No response body.

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 registration cannot be removed. Two codes share this status: `primary_registration_cannot_be_removed` while other registrations exist, and `policy_requires_idp` for the last registration while the customer authentication policy is not `off`. Nothing was removed. Branch on `code`.

409 · primaryRegistrationCannotBeRemoved

{
  "type": "urn:qms:problem:primary_registration_cannot_be_removed",
  "title": "Primary Registration Cannot Be Removed",
  "status": 409,
  "code": "primary_registration_cannot_be_removed",
  "detail": "The primary registration cannot be removed while other registrations exist."
}

409 · policyRequiresIdp

{
  "type": "urn:qms:problem:policy_requires_idp",
  "title": "Policy Requires Idp",
  "status": 409,
  "code": "policy_requires_idp",
  "detail": "The customer-authentication policy requires customer identity to stay configured."
}

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.

500 · Example

{
  "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
}

Open operation →

POSTEnable an identity-provider registration/api/integration/v1/settings/identity-providers/{providerId}/enable

Enable an identity-provider registration

Enables the registration. It becomes the primary when the tenant holds no enabled primary. An enabled registration answers 200 and changes nothing. An unverified registration is refused 409 `registration_not_verified` unless the optional body sets `acceptUnverified` to true; no connection check runs without it. With it, the stored issuer URL is checked before anything is written, a failed check is refused 422 `connection_check_failed` naming the failure in `checkCode`, and a passing one enables the registration with `activatedWithoutTest` true and `verifiedAt` null. When the registration would become the primary while the customer authentication policy is `required`, it is refused 409 `primary_not_verified` instead, before the check runs. Answers 200 with the registration. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab/enable" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "acceptUnverified": true
}'

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

Example body

{
  "acceptUnverified": true
}

Request schema

The optional body of the enable operation.

acceptUnverified · boolean · optional

Enables an unverified registration after a passing connection check of its stored issuer URL. Absent means false.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The optional body of the enable operation.",
  "properties": {
    "acceptUnverified": {
      "type": "boolean",
      "description": "Enables an unverified registration after a passing connection check of its stored issuer URL. Absent means false.",
      "example": true
    }
  }
}

Responses

200 — The registration as it stands after the write.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": true,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 write needs a test it does not have. Two codes share this status: `registration_not_verified` when the registration is not verified and the request did not set `acceptUnverified`, and `primary_not_verified` when `acceptUnverified` would leave the primary carrying `activatedWithoutTest` under a required policy. Nothing was written. Branch on `code`.

409 · registrationNotVerified

{
  "type": "urn:qms:problem:registration_not_verified",
  "title": "Registration Not Verified",
  "status": 409,
  "code": "registration_not_verified",
  "detail": "The registration's connection is not verified."
}

409 · primaryNotVerified

{
  "type": "urn:qms:problem:primary_not_verified",
  "title": "Primary Not Verified",
  "status": 409,
  "code": "primary_not_verified",
  "detail": "The primary would carry activatedWithoutTest while the customer-authentication policy is required."
}

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
}

422 — The request set `acceptUnverified` and the connection check of the issuer URL the registration would hold failed. `checkCode` names the failure: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Nothing was written.

422 · Example

{
  "type": "urn:qms:problem:connection_check_failed",
  "title": "Connection Check Failed",
  "status": 422,
  "code": "connection_check_failed",
  "detail": "The connection check of the resulting issuer URL failed; nothing was written.",
  "checkCode": "unreachable"
}

422 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.

500 · Example

{
  "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
}

Open operation →

POSTDisable an identity-provider registration/api/integration/v1/settings/identity-providers/{providerId}/disable

Disable an identity-provider registration

Disables the registration and clears its `activatedWithoutTest` marker. The primary cannot be disabled (409 `primary_registration_cannot_be_disabled`); designate another primary first. A disabled registration answers 200 and changes nothing. Answers 200 with the registration. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab/disable" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The registration as it stands after the write.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": false,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 registration is the primary and cannot be disabled. Designate another primary first.

409 · Example

{
  "type": "urn:qms:problem:primary_registration_cannot_be_disabled",
  "title": "Primary Registration Cannot Be Disabled",
  "status": 409,
  "code": "primary_registration_cannot_be_disabled",
  "detail": "The primary registration cannot be disabled."
}

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.

500 · Example

{
  "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
}

Open operation →

POSTDesignate an identity-provider registration as the primary/api/integration/v1/settings/identity-providers/{providerId}/primary

Designate an identity-provider registration as the primary

Makes the registration the primary; the previous primary stays enabled and stops being the primary. A disabled registration is refused 409 `disabled_registration_cannot_be_primary`. A registration that carries `activatedWithoutTest` can be designated while the customer authentication policy is not `required`; under `required` it is refused 409 `primary_not_verified`. An enabled registration that was neither tested nor activated without a test, as every registration enabled before that option existed, is refused 409 `registration_not_verified`. A registration that is already the primary answers 200 and changes nothing. Answers 200 with the registration. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab/primary" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The registration as it stands after the write.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": true,
  "primary": true,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 registration cannot be designated the primary. Three codes share this status: `disabled_registration_cannot_be_primary`, `registration_not_verified` and `primary_not_verified`. Nothing was written. Branch on `code`.

409 · disabledRegistrationCannotBePrimary

{
  "type": "urn:qms:problem:disabled_registration_cannot_be_primary",
  "title": "Disabled Registration Cannot Be Primary",
  "status": 409,
  "code": "disabled_registration_cannot_be_primary",
  "detail": "A disabled registration cannot be designated primary."
}

409 · registrationNotVerified

{
  "type": "urn:qms:problem:registration_not_verified",
  "title": "Registration Not Verified",
  "status": 409,
  "code": "registration_not_verified",
  "detail": "The registration's connection is not verified."
}

409 · primaryNotVerified

{
  "type": "urn:qms:problem:primary_not_verified",
  "title": "Primary Not Verified",
  "status": 409,
  "code": "primary_not_verified",
  "detail": "The primary would carry activatedWithoutTest while the customer-authentication policy is required."
}

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.

500 · Example

{
  "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
}

Open operation →

POSTTest an identity-provider registration's stored connection/api/integration/v1/settings/identity-providers/{providerId}/connection-check

Test an identity-provider registration's stored connection

Runs the same OIDC discovery check the tenant-admin console's own connection check runs, against the registration's STORED issuer URL — no request body is read. Answers 200 whether discovery succeeds or fails, and also for a registration that stores no issuer URL, which fails with `invalid_document`; a failed discovery is reported through `outcome` and `code`, not through the HTTP status. Nothing is written or audited: neither `verifiedAt` nor any other member of the registration is changed by this check. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab/connection-check" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

None. This operation carries no request body.

Responses

200 — The connection check's outcome.

200 · discovered

{
  "outcome": "discovered",
  "issuer": "https://support-sso.example.com",
  "authorizationEndpoint": "https://support-sso.example.com/authorize",
  "tokenEndpoint": "https://support-sso.example.com/token",
  "jwksUri": "https://support-sso.example.com/jwks",
  "userInfoEndpoint": "https://support-sso.example.com/userinfo",
  "code": null
}

200 · failed

{
  "outcome": "failed",
  "issuer": null,
  "authorizationEndpoint": null,
  "tokenEndpoint": null,
  "jwksUri": null,
  "userInfoEndpoint": null,
  "code": "unreachable"
}

200 response schema

The connection check's answer. `outcome` is `discovered` or `failed`. A `discovered` outcome carries `issuer`, `authorizationEndpoint`, `tokenEndpoint` and `jwksUri`; `userInfoEndpoint` is null when the discovery document names none. A `failed` outcome carries `code`, one of the closed discovery-failure vocabulary, and leaves the other members null. Nothing is stored or changed by this check.

outcome · string · required

Allowed values: "discovered", "failed"

issuer · string | null · required

authorizationEndpoint · string | null · required

tokenEndpoint · string | null · required

jwksUri · string | null · required

userInfoEndpoint · string | null · required

code · string | null · required

The discovery-failure code; present only when outcome is failed.

Allowed values: "unreachable", "timeout", "not_https", "private_address", "issuer_mismatch", "missing_endpoint", "invalid_document", null

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The connection check's answer. `outcome` is `discovered` or `failed`. A `discovered` outcome carries `issuer`, `authorizationEndpoint`, `tokenEndpoint` and `jwksUri`; `userInfoEndpoint` is null when the discovery document names none. A `failed` outcome carries `code`, one of the closed discovery-failure vocabulary, and leaves the other members null. Nothing is stored or changed by this check.",
  "properties": {
    "outcome": {
      "type": "string",
      "enum": [
        "discovered",
        "failed"
      ],
      "example": "discovered"
    },
    "issuer": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "authorizationEndpoint": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com/authorize"
    },
    "tokenEndpoint": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com/token"
    },
    "jwksUri": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com/jwks"
    },
    "userInfoEndpoint": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com/userinfo"
    },
    "code": {
      "type": [
        "string",
        "null"
      ],
      "description": "The discovery-failure code; present only when outcome is failed.",
      "enum": [
        "unreachable",
        "timeout",
        "not_https",
        "private_address",
        "issuer_mismatch",
        "missing_endpoint",
        "invalid_document",
        null
      ],
      "example": null
    }
  },
  "required": [
    "outcome",
    "issuer",
    "authorizationEndpoint",
    "tokenEndpoint",
    "jwksUri",
    "userInfoEndpoint",
    "code"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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.

500 · Example

{
  "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
}

Open operation →

PUTSet, replace or erase an identity-provider's client authentication/api/integration/v1/settings/identity-providers/{providerId}/client-authentication

Set, replace or erase an identity-provider's client authentication

Sets the registration's client authentication method and, for a secret-based method, its client secret — the same rule the tenant-admin console update uses. `clientAuthMethod` is `none`, `client_secret_basic` or `client_secret_post`; a value this build does not support, or a missing `clientAuthMethod`, is refused 400 `unsupported_client_auth_method`. `clientSecret` is optional. Omitted or empty, the stored secret (if any) is left untouched — switching between the two secret-based methods without sending one keeps the stored secret and its `clientSecretUpdatedAt`. Sent for a secret-based method, it REPLACES whatever was stored and moves `clientSecretUpdatedAt`; sent while the resulting method is `none`, it is refused 400 `client_secret_not_allowed` and nothing is written. A secret-based method with no secret sent and none stored is refused 400 `client_secret_required`. A malformed secret value is refused 400 `client_secret_invalid`. Switching the method to `none` erases the stored secret, with no separate confirmation step. The secret itself and its ciphertext are never sent back, on the 200 answer or on any refusal body. An enabled registration refuses a write that changes its connection with 409 `registration_not_verified` unless the request sets `acceptUnverified` to true; a write that changes nothing is answered 200. With `acceptUnverified` the stored issuer URL is checked before anything is written, a failed check is refused 422 `connection_check_failed` naming the failure in `checkCode`, and a passing one applies the change with `activatedWithoutTest` true; while the customer authentication policy is `required` the same change on the primary is refused 409 `primary_not_verified` instead. On a disabled registration a change applies and clears `verifiedAt`. Answers 200 with the updated registration. Requires a credential issued by a tenant administrator.

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

curl --request PUT "$QMS_BASE_URL/api/integration/v1/settings/identity-providers/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab/client-authentication" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "clientAuthMethod": "client_secret_basic",
  "clientSecret": "CHANGE-ME-EXAMPLE-CLIENT-SECRET",
  "acceptUnverified": false
}'

Parameters

Name	In	Required	Schema
providerId	path	yes	{"type":"string"}

providerId: The registration's opaque identifier.

Request body

Example body

{
  "clientAuthMethod": "client_secret_basic",
  "clientSecret": "CHANGE-ME-EXAMPLE-CLIENT-SECRET",
  "acceptUnverified": false
}

Request schema

The client-authentication write body. `clientSecret` is write-only: it is never present on a response, and omitting it (or sending an empty value) leaves any stored secret untouched.

clientAuthMethod · string · required

The client authentication method to set.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecret · string · optional

acceptUnverified · boolean · optional

Applies the change without a test sign-in after a passing connection check. Absent means false.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The client-authentication write body. `clientSecret` is write-only: it is never present on a response, and omitting it (or sending an empty value) leaves any stored secret untouched.",
  "properties": {
    "clientAuthMethod": {
      "type": "string",
      "description": "The client authentication method to set.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecret": {
      "type": "string",
      "writeOnly": true,
      "maxLength": 512,
      "example": "CHANGE-ME-EXAMPLE-CLIENT-SECRET"
    },
    "acceptUnverified": {
      "type": "boolean",
      "description": "Applies the change without a test sign-in after a passing connection check. Absent means false.",
      "example": false
    }
  },
  "required": [
    "clientAuthMethod"
  ]
}

Responses

200 — The registration as it stands after the write.

200 · Example

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab",
  "displayName": "Acme Support Desk SSO",
  "kind": "OIDC",
  "enabled": true,
  "primary": false,
  "issuerUrl": "https://support-sso.example.com",
  "clientId": "acme-support-qms",
  "clientAuthMethod": "client_secret_basic",
  "clientSecretConfigured": true,
  "clientSecretUpdatedAt": "2026-09-10T09:00:00.000Z",
  "verifiedAt": "2026-09-10T09:05:00.000Z",
  "activatedWithoutTest": false
}

200 response schema

One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.

id · string · required

The registration's own opaque identifier.

displayName · string · required

kind · string · required

The adapter kind this registration configures.

Allowed values: "OIDC"

enabled · boolean · required

primary · boolean · required

Whether this is the tenant's primary identity provider.

issuerUrl · string | null · required

clientId · string | null · required

clientAuthMethod · string · required

How this registration authenticates the token request.

Allowed values: "none", "client_secret_basic", "client_secret_post"

clientSecretConfigured · boolean · required

Whether a client secret is stored for this registration.

clientSecretUpdatedAt · string | null · required

When the stored client secret was last set or replaced, or null when none is stored.

verifiedAt · string | null · required

When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.

activatedWithoutTest · boolean · required

Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "One identity-provider registration and its client authentication state — never the client secret or its ciphertext. Every member is always present; `issuerUrl`, `clientId`, `clientSecretUpdatedAt` and `verifiedAt` are null rather than absent when the registration carries none.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The registration's own opaque identifier.",
      "example": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaab"
    },
    "displayName": {
      "type": "string",
      "example": "Acme Support Desk SSO"
    },
    "kind": {
      "type": "string",
      "description": "The adapter kind this registration configures.",
      "enum": [
        "OIDC"
      ],
      "example": "OIDC"
    },
    "enabled": {
      "type": "boolean",
      "example": true
    },
    "primary": {
      "type": "boolean",
      "description": "Whether this is the tenant's primary identity provider.",
      "example": false
    },
    "issuerUrl": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://support-sso.example.com"
    },
    "clientId": {
      "type": [
        "string",
        "null"
      ],
      "example": "acme-support-qms"
    },
    "clientAuthMethod": {
      "type": "string",
      "description": "How this registration authenticates the token request.",
      "enum": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "example": "client_secret_basic"
    },
    "clientSecretConfigured": {
      "type": "boolean",
      "description": "Whether a client secret is stored for this registration.",
      "example": true
    },
    "clientSecretUpdatedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the stored client secret was last set or replaced, or null when none is stored.",
      "example": "2026-09-10T09:00:00.000Z"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When a test sign-in last verified this registration's connection, or null when it never has been. A change to the connection or the client secret clears it back to null.",
      "example": "2026-09-10T09:05:00.000Z"
    },
    "activatedWithoutTest": {
      "type": "boolean",
      "description": "Whether the registration was enabled, or its connection changed, on an explicit request to accept it without a test sign-in. Such a registration has `verifiedAt` null, cannot be designated the primary in the management console, and cannot be the primary under a required customer authentication policy. A test sign-in of the stored connection or disabling the registration clears it.",
      "example": false
    }
  },
  "required": [
    "id",
    "displayName",
    "kind",
    "enabled",
    "primary",
    "issuerUrl",
    "clientId",
    "clientAuthMethod",
    "clientSecretConfigured",
    "clientSecretUpdatedAt",
    "verifiedAt",
    "activatedWithoutTest"
  ]
}

400 — The client-authentication write was refused before anything was written. Five codes share this status: `unsupported_client_auth_method` when `clientAuthMethod` is absent or names a method this build does not support, `client_secret_required` when the resulting method is secret-based and no secret is supplied or stored, `client_secret_not_allowed` when a secret is supplied while the resulting method is `none`, `client_secret_invalid` when the supplied secret value is malformed, and `validation_failed` when the request body could not be read at all. Branch on `code`.

400 · unsupportedClientAuthMethod

{
  "type": "urn:qms:problem:unsupported_client_auth_method",
  "title": "Unsupported Client Authentication Method",
  "status": 400,
  "code": "unsupported_client_auth_method",
  "detail": "This client authentication method is not supported."
}

400 · clientSecretRequired

{
  "type": "urn:qms:problem:client_secret_required",
  "title": "Client Secret Required",
  "status": 400,
  "code": "client_secret_required",
  "detail": "This client authentication method needs a client secret and none is stored."
}

400 · clientSecretNotAllowed

{
  "type": "urn:qms:problem:client_secret_not_allowed",
  "title": "Client Secret Not Allowed",
  "status": 400,
  "code": "client_secret_not_allowed",
  "detail": "The method none does not accept a client secret."
}

400 · clientSecretInvalid

{
  "type": "urn:qms:problem:client_secret_invalid",
  "title": "Client Secret Invalid",
  "status": 400,
  "code": "client_secret_invalid",
  "detail": "The client secret value is not acceptable."
}

400 · validationFailed

{
  "type": "urn:qms:problem:validation_failed",
  "title": "Validation Failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "The request body failed field validation."
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — No identity-provider registration was found for this identifier. Outside the credential's reach, in another tenant and nonexistent are one answer, so that the existence of another tenant's data cannot be probed.

404 · Example

{
  "type": "urn:qms:problem:registration_not_found",
  "title": "Registration Not Found",
  "status": 404,
  "code": "registration_not_found",
  "detail": "No identity provider was found for this identifier."
}

404 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 write needs a test it does not have. Two codes share this status: `registration_not_verified` when the registration is not verified and the request did not set `acceptUnverified`, and `primary_not_verified` when `acceptUnverified` would leave the primary carrying `activatedWithoutTest` under a required policy. Nothing was written. Branch on `code`.

409 · registrationNotVerified

{
  "type": "urn:qms:problem:registration_not_verified",
  "title": "Registration Not Verified",
  "status": 409,
  "code": "registration_not_verified",
  "detail": "The registration's connection is not verified."
}

409 · primaryNotVerified

{
  "type": "urn:qms:problem:primary_not_verified",
  "title": "Primary Not Verified",
  "status": 409,
  "code": "primary_not_verified",
  "detail": "The primary would carry activatedWithoutTest while the customer-authentication policy is required."
}

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
}

422 — The request set `acceptUnverified` and the connection check of the issuer URL the registration would hold failed. `checkCode` names the failure: `unreachable`, `timeout`, `not_https`, `private_address`, `issuer_mismatch`, `missing_endpoint` or `invalid_document`. Nothing was written.

422 · Example

{
  "type": "urn:qms:problem:connection_check_failed",
  "title": "Connection Check Failed",
  "status": 422,
  "code": "connection_check_failed",
  "detail": "The connection check of the resulting issuer URL failed; nothing was written.",
  "checkCode": "unreachable"
}

422 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.

500 · Example

{
  "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
}

503 — The client secret could not be sealed because the deployment's key-management service is unavailable. Nothing was written; retry once the service is reachable again.

503 · Example

{
  "type": "urn:qms:problem:client_secret_storage_unavailable",
  "title": "Client Secret Storage Unavailable",
  "status": 503,
  "code": "client_secret_storage_unavailable",
  "detail": "Client secret storage is unavailable; nothing was written."
}

503 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
}

Open operation →

GETRead the tenant's language catalogue/api/integration/v1/settings/languages

Read the tenant's language catalogue

The languages the tenant offers, ordered by `position` starting at 1. The language at the first active position is the default. Codes are uppercase platform language codes. Requires a credential issued by a tenant administrator.

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

curl --request GET "$QMS_BASE_URL/api/integration/v1/settings/languages" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

None.

Request body

None. This operation carries no request body.

Responses

200 — The whole catalogue.

200 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "active": true
    },
    {
      "code": "LT",
      "position": 2,
      "active": true
    },
    {
      "code": "PL",
      "position": 3,
      "active": false
    }
  ]
}

200 response schema

The whole language catalogue, ordered by `position`.

items · array · required

Show nested fields

One language of the tenant's catalogue.

code · string · required

The uppercase platform language code.

position · integer · required

The language's place in the catalogue, starting at 1 and contiguous.

active · boolean · required

Whether the language is currently offered.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The whole language catalogue, ordered by `position`.",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One language of the tenant's catalogue.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The uppercase platform language code.",
            "pattern": "^[A-Z]{2}$",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the catalogue, starting at 1 and contiguous.",
            "example": 2
          },
          "active": {
            "type": "boolean",
            "description": "Whether the language is currently offered.",
            "example": true
          }
        },
        "required": [
          "code",
          "position",
          "active"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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.

500 · Example

{
  "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
}

Open operation →

POSTAdd a language to the tenant's catalogue/api/integration/v1/settings/languages

Add a language to the tenant's catalogue

Appends the language to the end of the catalogue, active. The code is case-insensitive and answered uppercase. A missing, blank or non-string `code` is refused 400 `validation_failed` naming `code`. A code that is not an ISO 639-1 language code is refused 422 `unknown_language_code`, a language the platform is not translated into 422 `language_not_platform_translated`, and a language already in the catalogue 422 `language_already_present`. Nothing is written on a refusal. Every change is audited. Answers 201 with the whole catalogue. Requires a credential issued by a tenant administrator.

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

curl --request POST "$QMS_BASE_URL/api/integration/v1/settings/languages" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "code": "PL"
}'

Parameters

None.

Request body

Example body

{
  "code": "PL"
}

Request schema

The language to add.

code · string · required

An ISO 639-1 language code, case-insensitive.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The language to add.",
  "properties": {
    "code": {
      "type": "string",
      "description": "An ISO 639-1 language code, case-insensitive.",
      "example": "PL"
    }
  },
  "required": [
    "code"
  ]
}

Responses

201 — The whole catalogue as it stands after the write.

201 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "active": true
    },
    {
      "code": "PL",
      "position": 2,
      "active": true
    }
  ]
}

201 response schema

The whole language catalogue, ordered by `position`.

items · array · required

Show nested fields

One language of the tenant's catalogue.

code · string · required

The uppercase platform language code.

position · integer · required

The language's place in the catalogue, starting at 1 and contiguous.

active · boolean · required

Whether the language is currently offered.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The whole language catalogue, ordered by `position`.",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One language of the tenant's catalogue.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The uppercase platform language code.",
            "pattern": "^[A-Z]{2}$",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the catalogue, starting at 1 and contiguous.",
            "example": 2
          },
          "active": {
            "type": "boolean",
            "description": "Whether the language is currently offered.",
            "example": true
          }
        },
        "required": [
          "code",
          "position",
          "active"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

422 — The language add was refused and nothing was written. Three codes share this status: `unknown_language_code`, `language_not_platform_translated` and `language_already_present`. Branch on `code`.

422 · unknownLanguageCode

{
  "type": "urn:qms:problem:unknown_language_code",
  "title": "Unknown Language Code",
  "status": 422,
  "code": "unknown_language_code",
  "detail": "The code is not an ISO 639-1 language code."
}

422 · languageNotPlatformTranslated

{
  "type": "urn:qms:problem:language_not_platform_translated",
  "title": "Language Not Platform Translated",
  "status": 422,
  "code": "language_not_platform_translated",
  "detail": "The platform is not translated into this language."
}

422 · languageAlreadyPresent

{
  "type": "urn:qms:problem:language_already_present",
  "title": "Language Already Present",
  "status": 422,
  "code": "language_already_present",
  "detail": "The language is already in the catalogue."
}

422 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.

500 · Example

{
  "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
}

Open operation →

PATCHActivate, deactivate or reorder a language/api/integration/v1/settings/languages/{code}

Activate, deactivate or reorder a language

The body sets exactly one of `active` and `position`. Setting both or neither is refused 422 `ambiguous_language_update`; a member of the wrong type is refused 400 `validation_failed` naming the member. `position` is clamped into the range of the catalogue and the other languages are renumbered contiguously. English cannot be deactivated: 422 `default_language_protected`. A code not in the catalogue is refused 404 `language_not_found`. Every change is audited. Answers 200 with the whole catalogue. Requires a credential issued by a tenant administrator.

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

curl --request PATCH "$QMS_BASE_URL/api/integration/v1/settings/languages/PL" \
  --header "Authorization: Api-Key $QMS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "active": false
}'

Parameters

Name	In	Required	Schema
code	path	yes	{"type":"string"}

code: The language's code, case-insensitive.

Request body

Example body

{
  "active": false
}

Request schema

Exactly one of `active` and `position`. A body that sets both or neither is refused 422 `ambiguous_language_update`.

active · boolean · optional

Activates or deactivates the language.

position · integer · optional

The new place of the language, clamped into the range of the catalogue.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "Exactly one of `active` and `position`. A body that sets both or neither is refused 422 `ambiguous_language_update`.",
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Activates or deactivates the language.",
      "example": false
    },
    "position": {
      "type": "integer",
      "description": "The new place of the language, clamped into the range of the catalogue.",
      "example": 1
    }
  }
}

Responses

200 — The whole catalogue as it stands after the write.

200 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "active": true
    },
    {
      "code": "PL",
      "position": 2,
      "active": false
    }
  ]
}

200 response schema

The whole language catalogue, ordered by `position`.

items · array · required

Show nested fields

One language of the tenant's catalogue.

code · string · required

The uppercase platform language code.

position · integer · required

The language's place in the catalogue, starting at 1 and contiguous.

active · boolean · required

Whether the language is currently offered.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The whole language catalogue, ordered by `position`.",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One language of the tenant's catalogue.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The uppercase platform language code.",
            "pattern": "^[A-Z]{2}$",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the catalogue, starting at 1 and contiguous.",
            "example": 2
          },
          "active": {
            "type": "boolean",
            "description": "Whether the language is currently offered.",
            "example": true
          }
        },
        "required": [
          "code",
          "position",
          "active"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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`.

400 · Example

{
  "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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — The catalogue holds no language with the code in the path. Nothing was written.

404 · Example

{
  "type": "urn:qms:problem:language_not_found",
  "title": "Language Not Found",
  "status": 404,
  "code": "language_not_found",
  "detail": "No language with this code is in the catalogue."
}

404 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
}

422 — The language update was refused and nothing was written. Two codes share this status: `ambiguous_language_update` when the body sets both or neither of `active` and `position`, and `default_language_protected` when it deactivates English. Branch on `code`.

422 · ambiguousLanguageUpdate

{
  "type": "urn:qms:problem:ambiguous_language_update",
  "title": "Ambiguous Language Update",
  "status": 422,
  "code": "ambiguous_language_update",
  "detail": "A language update must set exactly one of active or position."
}

422 · defaultLanguageProtected

{
  "type": "urn:qms:problem:default_language_protected",
  "title": "Default Language Protected",
  "status": 422,
  "code": "default_language_protected",
  "detail": "English can be neither removed nor deactivated."
}

422 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.

500 · Example

{
  "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
}

Open operation →

DELETERemove a language from the tenant's catalogue/api/integration/v1/settings/languages/{code}

Remove a language from the tenant's catalogue

Removes the language and renumbers the others contiguously. English cannot be removed: 422 `default_language_protected`. A language still offered by a location or held as a skill by an operator is refused 409 `language_in_use`, with `blockers` counting the kinds `LOCATION` and `OPERATOR`. A code not in the catalogue is refused 404 `language_not_found`. Every change is audited. Answers 200 with the whole catalogue. Requires a credential issued by a tenant administrator.

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

curl --request DELETE "$QMS_BASE_URL/api/integration/v1/settings/languages/PL" \
  --header "Authorization: Api-Key $QMS_API_KEY"

Parameters

Name	In	Required	Schema
code	path	yes	{"type":"string"}

code: The language's code, case-insensitive.

Request body

None. This operation carries no request body.

Responses

200 — The whole catalogue as it stands after the removal.

200 · Example

{
  "items": [
    {
      "code": "EN",
      "position": 1,
      "active": true
    }
  ]
}

200 response schema

The whole language catalogue, ordered by `position`.

items · array · required

Show nested fields

One language of the tenant's catalogue.

code · string · required

The uppercase platform language code.

position · integer · required

The language's place in the catalogue, starting at 1 and contiguous.

active · boolean · required

Whether the language is currently offered.

Raw JSON Schema

application/json

{
  "type": "object",
  "description": "The whole language catalogue, ordered by `position`.",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One language of the tenant's catalogue.",
        "properties": {
          "code": {
            "type": "string",
            "description": "The uppercase platform language code.",
            "pattern": "^[A-Z]{2}$",
            "example": "LT"
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "The language's place in the catalogue, starting at 1 and contiguous.",
            "example": 2
          },
          "active": {
            "type": "boolean",
            "description": "Whether the language is currently offered.",
            "example": true
          }
        },
        "required": [
          "code",
          "position",
          "active"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}

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.

401 · Example

{
  "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.

403 · insufficientScope

{
  "type": "urn:qms:problem:insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API credential does not reach this operation."
}

403 · insufficientAuthority

{
  "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
}

404 — The catalogue holds no language with the code in the path. Nothing was written.

404 · Example

{
  "type": "urn:qms:problem:language_not_found",
  "title": "Language Not Found",
  "status": 404,
  "code": "language_not_found",
  "detail": "No language with this code is in the catalogue."
}

404 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 language is still offered by a location or held as a skill by an operator, so it cannot be removed. `blockers` carries one entry per non-zero category, of the kinds `LOCATION` and `OPERATOR`. Nothing was removed.

409 · Example

{
  "type": "urn:qms:problem:language_in_use",
  "title": "Language In Use",
  "status": 409,
  "code": "language_in_use",
  "detail": "The language is still offered by a location or held as a skill by an operator.",
  "blockers": [
    {
      "kind": "LOCATION",
      "count": 2
    },
    {
      "kind": "OPERATOR",
      "count": 1
    }
  ]
}

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
}

422 — English cannot be removed. Nothing was removed.

422 · Example

{
  "type": "urn:qms:problem:default_language_protected",
  "title": "Default Language Protected",
  "status": 422,
  "code": "default_language_protected",
  "detail": "English can be neither removed nor deactivated."
}

422 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.

500 · Example

{
  "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
}