Authentication
x-hallify-widget-context: <HALLIFY_STOREFRONT_WIDGET_CONTEXT>Short-lived server-authenticated widget presentation proof. It binds the configured frame origin to the exact verified parent binding and connection authority. Widget new demand requires this proof; existing native capabilities remain separate and retain their original authority and deadlines.
Parameters
publicHandlePath · RequiredPublished native reservation channel owning the intent.
stringFull definition
{ "type": "string", "example": "example" }intentIdPath · RequiredOriginal verification intent UUID bound to the request fingerprint and current Origin/presentation; its identity grants no management or payment authority.
string · uuidFull definition
{ "type": "string", "format": "uuid", "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }originHeader · OptionalActual browser request Origin used for current presentation authorization. New demand and Storefront-bound continuations require it. Canonical Hallify browser requests use the origin configured by HALLIFY_PUBLIC_APP_URL. This header provides request context and does not authenticate a caller or replace the applicable guest credential.
string · uriFull definition
{ "type": "string", "format": "uri", "maxLength": 2048, "example": "https://example.test/resource" }x-hallify-connection-idHeader · OptionalOptional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.
string · uuidFull definition
{ "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
Responses
200Returns the current pending, consumed or expired intent state and safe verification expiry, delivery and resend metadata.
Full definition
{
"$ref": "#/components/schemas/ReservationPublicPendingIntentDto"
}{
"intentId": "fd46d9cb-163b-4669-8f68-6b8456779efd",
"kind": "BOOKING",
"status": "PENDING_VERIFICATION",
"expiresAt": "2026-12-31T18:00:00.000Z",
"expired": true,
"canVerify": true,
"verification": {
"verificationId": "904a18d4-c890-4387-8e14-bc52c879c7ff",
"expiresAt": "2026-12-31T18:00:00.000Z",
"status": "PENDING",
"deliveryStatus": "QUEUED",
"attemptsRemaining": 0,
"canResend": true,
"resendAvailableAt": null
},
"serverTime": "2026-12-31T18:00:00.000Z"
}404The exact channel, intent, request fingerprint or current presentation is unavailable; no intent ownership or contact detail is disclosed.
Full definition
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"statusCode": 404,
"error": "errors:http.notFound",
"code": "HTTP_NOT_FOUND",
"message": "errors:http.notFound",
"translationKey": "errors:http.notFound"
}Schemas
ReservationPublicPendingIntentDto
Current intent and contact-verification state for the exact owning channel and original request fingerprint under current Origin and presentation authorization. It contains no contact value, code, owner details or manage capability.
intentIdRequiredExact pending or historical intent identifier; its value alone grants no read or management authority.
string · uuidFull definition
{ "type": "string", "description": "Exact pending or historical intent identifier; its value alone grants no read or management authority.", "format": "uuid", "example": "fd46d9cb-163b-4669-8f68-6b8456779efd" }kindRequiredWhether this intent requests a booking or a remote waitlist entry.
stringFull definition
{ "type": "string", "description": "Whether this intent requests a booking or a remote waitlist entry.", "enum": [ "BOOKING", "WAITLIST" ], "example": "BOOKING" }statusRequiredStored native intent status. Expiry is also evaluated against serverTime, without changing the persisted lifecycle during a read.
stringFull definition
{ "type": "string", "description": "Stored native intent status. Expiry is also evaluated against serverTime, without changing the persisted lifecycle during a read.", "enum": [ "PENDING_VERIFICATION", "VERIFIED", "CONSUMED", "CANCELED", "EXPIRED" ], "example": "PENDING_VERIFICATION" }expiresAtRequiredOriginal intent or capacity-hold expiry; reading never extends it.
string · date-timeFull definition
{ "type": "string", "description": "Original intent or capacity-hold expiry; reading never extends it.", "format": "date-time", "example": "2026-12-31T18:00:00.000Z" }expiredRequiredWhether the original intent expiry has passed at serverTime.
booleanFull definition
{ "type": "boolean", "description": "Whether the original intent expiry has passed at serverTime.", "example": true }canVerifyRequiredWhether this unconsumed intent and native contact challenge currently permit verification. Native conversion still rechecks capacity, current presentation and commercial admission.
booleanFull definition
{ "type": "boolean", "description": "Whether this unconsumed intent and native contact challenge currently permit verification. Native conversion still rechecks capacity, current presentation and commercial admission.", "example": true }verificationRequiredCurrent redacted native contact-verification state. Delivery acceptance and code verification are separate; this state grants no reservation management authority.
objectFull definition
{ "type": "object", "description": "Current redacted native contact-verification state. Delivery acceptance and code verification are separate; this state grants no reservation management authority.", "additionalProperties": false, "required": [ "verificationId", "expiresAt", "status", "deliveryStatus", "attemptsRemaining", "canResend", "resendAvailableAt" ], "properties": { "verificationId": { "type": "string", "description": "Contact-verification identifier for this exact intent.", "format": "uuid", "example": "904a18d4-c890-4387-8e14-bc52c879c7ff" }, "expiresAt": { "type": "string", "description": "Native contact-code expiry, independent of the capacity-hold or waitlist-intent expiry.", "format": "date-time", "example": "2026-12-31T18:00:00.000Z" }, "status": { "type": "string", "description": "Native challenge lifecycle: pending code, verified identity, consumed proof, or an expired or locked challenge. A consumed proof does not disclose or renew a manage capability.", "enum": [ "PENDING", "VERIFIED", "CONSUMED", "EXPIRED", "LOCKED" ], "example": "PENDING" }, "deliveryStatus": { "type": "string", "description": "Native verification-delivery state. Queued, sending and Core-pending work is unfinished; sent/delivered evidence does not verify the code. Failed, unknown or Core-unknown work never implies successful delivery or permission for a replacement send.", "enum": [ "QUEUED", "SENDING", "CORE_PENDING", "CORE_UNKNOWN", "CORE_FAILED", "SENT", "DELIVERED", "FAILED", "RECEIVED" ], "example": "QUEUED" }, "attemptsRemaining": { "type": "integer", "description": "Remaining native attempts for the pending contact code.", "minimum": 0, "example": 0 }, "canResend": { "type": "boolean", "description": "Whether current native verification policy and the unexpired pending intent permit requesting a resend now. Execution rechecks the policy.", "example": true }, "resendAvailableAt": { "type": "string", "description": "Native cooldown boundary before intent expiry, or null when no further resend window is currently available. This timestamp alone does not grant resend permission.", "format": "date-time", "nullable": true, "example": "2026-12-31T18:00:00.000Z" } }, "example": { "verificationId": "904a18d4-c890-4387-8e14-bc52c879c7ff", "expiresAt": "2026-12-31T18:00:00.000Z", "status": "PENDING", "deliveryStatus": "QUEUED", "attemptsRemaining": 0, "canResend": true, "resendAvailableAt": null } }serverTimeRequiredServer instant used for the current expiry and retry projection.
string · date-timeFull definition
{ "type": "string", "description": "Server instant used for the current expiry and retry projection.", "format": "date-time", "example": "2026-12-31T18:00:00.000Z" }
Full definition
{
"type": "object",
"description": "Current intent and contact-verification state for the exact owning channel and original request fingerprint under current Origin and presentation authorization. It contains no contact value, code, owner details or manage capability.",
"additionalProperties": false,
"required": [
"intentId",
"kind",
"status",
"expiresAt",
"expired",
"canVerify",
"verification",
"serverTime"
],
"properties": {
"intentId": {
"type": "string",
"description": "Exact pending or historical intent identifier; its value alone grants no read or management authority.",
"format": "uuid",
"example": "fd46d9cb-163b-4669-8f68-6b8456779efd"
},
"kind": {
"type": "string",
"description": "Whether this intent requests a booking or a remote waitlist entry.",
"enum": [
"BOOKING",
"WAITLIST"
],
"example": "BOOKING"
},
"status": {
"type": "string",
"description": "Stored native intent status. Expiry is also evaluated against serverTime, without changing the persisted lifecycle during a read.",
"enum": [
"PENDING_VERIFICATION",
"VERIFIED",
"CONSUMED",
"CANCELED",
"EXPIRED"
],
"example": "PENDING_VERIFICATION"
},
"expiresAt": {
"type": "string",
"description": "Original intent or capacity-hold expiry; reading never extends it.",
"format": "date-time",
"example": "2026-12-31T18:00:00.000Z"
},
"expired": {
"type": "boolean",
"description": "Whether the original intent expiry has passed at serverTime.",
"example": true
},
"canVerify": {
"type": "boolean",
"description": "Whether this unconsumed intent and native contact challenge currently permit verification. Native conversion still rechecks capacity, current presentation and commercial admission.",
"example": true
},
"verification": {
"type": "object",
"description": "Current redacted native contact-verification state. Delivery acceptance and code verification are separate; this state grants no reservation management authority.",
"additionalProperties": false,
"required": [
"verificationId",
"expiresAt",
"status",
"deliveryStatus",
"attemptsRemaining",
"canResend",
"resendAvailableAt"
],
"properties": {
"verificationId": {
"type": "string",
"description": "Contact-verification identifier for this exact intent.",
"format": "uuid",
"example": "904a18d4-c890-4387-8e14-bc52c879c7ff"
},
"expiresAt": {
"type": "string",
"description": "Native contact-code expiry, independent of the capacity-hold or waitlist-intent expiry.",
"format": "date-time",
"example": "2026-12-31T18:00:00.000Z"
},
"status": {
"type": "string",
"description": "Native challenge lifecycle: pending code, verified identity, consumed proof, or an expired or locked challenge. A consumed proof does not disclose or renew a manage capability.",
"enum": [
"PENDING",
"VERIFIED",
"CONSUMED",
"EXPIRED",
"LOCKED"
],
"example": "PENDING"
},
"deliveryStatus": {
"type": "string",
"description": "Native verification-delivery state. Queued, sending and Core-pending work is unfinished; sent/delivered evidence does not verify the code. Failed, unknown or Core-unknown work never implies successful delivery or permission for a replacement send.",
"enum": [
"QUEUED",
"SENDING",
"CORE_PENDING",
"CORE_UNKNOWN",
"CORE_FAILED",
"SENT",
"DELIVERED",
"FAILED",
"RECEIVED"
],
"example": "QUEUED"
},
"attemptsRemaining": {
"type": "integer",
"description": "Remaining native attempts for the pending contact code.",
"minimum": 0,
"example": 0
},
"canResend": {
"type": "boolean",
"description": "Whether current native verification policy and the unexpired pending intent permit requesting a resend now. Execution rechecks the policy.",
"example": true
},
"resendAvailableAt": {
"type": "string",
"description": "Native cooldown boundary before intent expiry, or null when no further resend window is currently available. This timestamp alone does not grant resend permission.",
"format": "date-time",
"nullable": true,
"example": "2026-12-31T18:00:00.000Z"
}
},
"example": {
"verificationId": "904a18d4-c890-4387-8e14-bc52c879c7ff",
"expiresAt": "2026-12-31T18:00:00.000Z",
"status": "PENDING",
"deliveryStatus": "QUEUED",
"attemptsRemaining": 0,
"canResend": true,
"resendAvailableAt": null
}
},
"serverTime": {
"type": "string",
"description": "Server instant used for the current expiry and retry projection.",
"format": "date-time",
"example": "2026-12-31T18:00:00.000Z"
}
},
"example": {
"intentId": "fd46d9cb-163b-4669-8f68-6b8456779efd",
"kind": "BOOKING",
"status": "PENDING_VERIFICATION",
"expiresAt": "2026-12-31T18:00:00.000Z",
"expired": true,
"canVerify": true,
"verification": {
"verificationId": "904a18d4-c890-4387-8e14-bc52c879c7ff",
"expiresAt": "2026-12-31T18:00:00.000Z",
"status": "PENDING",
"deliveryStatus": "QUEUED",
"attemptsRemaining": 0,
"canResend": true,
"resendAvailableAt": null
},
"serverTime": "2026-12-31T18:00:00.000Z"
}
}TranslatedErrorDto
Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.
statusCodeRequiredHTTP status code repeated from the response.
integerFull definition
{ "type": "integer", "description": "HTTP status code repeated from the response.", "example": 400 }errorRequiredTranslation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.
stringFull definition
{ "type": "string", "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.", "example": "errors.request.invalid" }codeRequiredStable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.
stringFull definition
{ "type": "string", "example": "HTTP_BAD_REQUEST", "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions." }messageRequiredTranslation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.
stringFull definition
{ "type": "string", "example": "errors:http.badRequest", "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application." }translationKeyRequiredCanonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.
stringFull definition
{ "type": "string", "example": "errors:http.badRequest", "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull definition
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.", "example": { "exampleKey": "example" } }validationErrorsOptionalField validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.
arrayFull definition
{ "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" }, "example": [ { "field": "email", "translationKey": "validation:isEmail", "code": "isEmail", "message": "validation:isEmail" } ] }detailsOptionalOptional domain-specific blocker or validation details
oneOfFull definition
{ "description": "Optional domain-specific blocker or validation details", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" }, "example": [ "example" ] }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "example": { "exampleKey": "example" } } ], "example": [ "example" ] }
Full definition
{
"type": "object",
"properties": {
"statusCode": {
"type": "integer",
"description": "HTTP status code repeated from the response.",
"example": 400
},
"error": {
"type": "string",
"description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
"example": "errors.request.invalid"
},
"code": {
"type": "string",
"example": "HTTP_BAD_REQUEST",
"description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
},
"message": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
},
"translationKey": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
"example": {
"exampleKey": "example"
}
},
"validationErrors": {
"description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationErrorDto"
},
"example": [
{
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
]
},
"details": {
"description": "Optional domain-specific blocker or validation details",
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"example": [
"example"
]
}
},
"required": [
"statusCode",
"error",
"code",
"message",
"translationKey"
],
"description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
"example": {
"statusCode": 400,
"error": "errors:http.badRequest",
"code": "HTTP_BAD_REQUEST",
"message": "errors:http.badRequest",
"translationKey": "errors:http.badRequest"
}
}ValidationErrorDto
Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.
fieldRequiredPublic field path. Nested properties and array indices are separated by dots.
stringFull definition
{ "type": "string", "example": "email", "description": "Public field path. Nested properties and array indices are separated by dots." }translationKeyRequiredTranslation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.
stringFull definition
{ "type": "string", "example": "validation:isEmail", "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog." }codeRequiredStable validator identifier for this field failure. Custom validators may define additional identifiers.
stringFull definition
{ "type": "string", "example": "isEmail", "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers." }messageRequiredTranslation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.
stringFull definition
{ "type": "string", "example": "validation:isEmail", "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull definition
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.", "example": { "exampleKey": "example" } }
Full definition
{
"type": "object",
"properties": {
"field": {
"type": "string",
"example": "email",
"description": "Public field path. Nested properties and array indices are separated by dots."
},
"translationKey": {
"type": "string",
"example": "validation:isEmail",
"description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
},
"code": {
"type": "string",
"example": "isEmail",
"description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
},
"message": {
"type": "string",
"example": "validation:isEmail",
"description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
"example": {
"exampleKey": "example"
}
}
},
"required": [
"field",
"translationKey",
"code",
"message"
],
"description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
"example": {
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
}JsonValue
Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.
Full definition
{
"oneOf": [
{
"type": "string",
"nullable": true,
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
"example": "example"
}