Skip to content
Sections

Reservations & waitlist

Read the owning public intent verification state

GET/public/reservations/{publicHandle}/intents/{intentId}

Reads only redacted intent and verification state for the exact native channel and original request fingerprint under current Origin and presentation authorization. The intent identifier alone grants no authority. This operation does not return a contact value, code, reservation details or manage capability, create a booking, or extend any deadline.

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.

Connection guide

Parameters

publicHandlePath · Required

Published native reservation channel owning the intent.

string
Full definition
{
  "type": "string",
  "example": "example"
}
intentIdPath · Required

Original verification intent UUID bound to the request fingerprint and current Origin/presentation; its identity grants no management or payment authority.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}
originHeader · Optional

Actual 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 · uri
Full definition
{
  "type": "string",
  "format": "uri",
  "maxLength": 2048,
  "example": "https://example.test/resource"
}
x-hallify-connection-idHeader · Optional

Optional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.

string · uuid
Full 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.
ReservationPublicPendingIntentDto
Full definition
{
  "$ref": "#/components/schemas/ReservationPublicPendingIntentDto"
}
Example response · 200 · application/json
{
  "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.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "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.

intentIdRequired

Exact pending or historical intent identifier; its value alone grants no read or management authority.

string · uuid
Full 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"
}
kindRequired

Whether this intent requests a booking or a remote waitlist entry.

string
Full definition
{
  "type": "string",
  "description": "Whether this intent requests a booking or a remote waitlist entry.",
  "enum": [
    "BOOKING",
    "WAITLIST"
  ],
  "example": "BOOKING"
}
statusRequired

Stored native intent status. Expiry is also evaluated against serverTime, without changing the persisted lifecycle during a read.

string
Full 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"
}
expiresAtRequired

Original intent or capacity-hold expiry; reading never extends it.

string · date-time
Full definition
{
  "type": "string",
  "description": "Original intent or capacity-hold expiry; reading never extends it.",
  "format": "date-time",
  "example": "2026-12-31T18:00:00.000Z"
}
expiredRequired

Whether the original intent expiry has passed at serverTime.

boolean
Full definition
{
  "type": "boolean",
  "description": "Whether the original intent expiry has passed at serverTime.",
  "example": true
}
canVerifyRequired

Whether this unconsumed intent and native contact challenge currently permit verification. Native conversion still rechecks capacity, current presentation and commercial admission.

boolean
Full 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
}
verificationRequired

Current redacted native contact-verification state. Delivery acceptance and code verification are separate; this state grants no reservation management authority.

object
Full 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
  }
}
serverTimeRequired

Server instant used for the current expiry and retry projection.

string · date-time
Full 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.

statusCodeRequired

HTTP status code repeated from the response.

integer
Full definition
{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}
errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string
Full 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"
}
codeRequired

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.

string
Full 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."
}
messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string
Full 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."
}
translationKeyRequired

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.

string
Full 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."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full 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"
  }
}
validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array
Full 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"
    }
  ]
}
detailsOptional

Optional domain-specific blocker or validation details

oneOf
Full 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.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string
Full definition
{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}
translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string
Full 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."
}
codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string
Full definition
{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}
messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string
Full 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."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full 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"
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.