--- title: Quick Reference slug: frameworks/tkou-quick-reference createdAt: 2026-05-26T06:33:03.000Z --- # Reference This section provides a consolidated quick-reference for developers who have already read the document and need to look up field details or terminology without navigating the full specification. ## Consolidated Request Field Reference The tables below list every inbound request field across the four required lifecycle endpoints. Use this as a single-page lookup when implementing or debugging your integration. Fields marked as *required* must be handled by your integration when present. Optional fields may or may not be sent depending on site configuration - your implementation must not fail if they are absent. ### Common Fields (all lifecycle endpoints) | Field | Type | Endpoints | Required | Notes | | ---------------- | ---------------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `visitId` | UUID v4 | Provision, Activate, Deprovision | Yes | Primary idempotency key. Stable for the entire visit lifecycle. | | `siteId` | UUID v4 | Provision, Activate, Deprovision | Yes | Sine site identifier. | | `externalId` | string | Verify, Provision, Activate, Deprovision | No | Integration-specific reference string configured in Sine. Max 256 characters. Present only if configured. | | `credentialType` | string | Provision, Activate, Deprovision | No | `digital`, `physical`, or `virtual`. | | `accessGroups` | array of strings | Provision, Activate, Deprovision | No | ACS access group IDs to apply. May be updated between Provision and Activate. | ### Provision-Only Fields | Field | Type | Required | Notes | | -------------------- | --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `validFrom` | string (ISO 8601 UTC) | Yes | Start of credential validity window. Provision only - not sent in Activate or Deprovision. | | `validTo` | string (ISO 8601 UTC) | Yes | End of credential validity window. Provision only - not sent in Activate or Deprovision. | | `visitor` | object | Yes | Contains `firstName`, `lastName`, and optional `email`, `mobile`, `photoURL`. | | `visitor.firstName` | string | Yes | Visitor's first name. | | `visitor.lastName` | string | Yes | Visitor's last name. | | `visitor.email` | string | No | Visitor's email address. | | `visitor.mobile` | string | No | Phone number in E.164 format (e.g. `+61400000000`). | | `visitor.photoURL` | string | No | Signed, ephemeral photo URL. Do not persist beyond the current request. | | `visitorType` | object | No | Visitor classification. Includes `id` and `name`. | | `company` | object | No | Visitor's company. Includes `id` and `name`. | | `host` | object | No | Employee the visitor is meeting. Includes `id`, `firstName`, `lastName`, and optional `email`, `mobile`, `hostGroup`, `hostGroupName`. | | `host.hostGroup` | string | No (required when `host` is present) | Access group or department identifier for the host. | | `host.hostGroupName` | string | No | Human-readable name for the host group. | | `checkoutUrl` | string | No | ACS checkout callback URL. Format: `{base}/callbacks/checkout/{jwt}?teamId={teamId}`. Also requires `x-sine-api-key` header on the callback call. | | `badgeNumber` | string | No | Pre-assigned card number. Present for `physical` credential flows. | | `zoneId` | string | No | Legacy. Zone identifier when zone feature is enabled. | | `zoneDetails` | object | No | Legacy. Zone `id`, `name`, and `externalId` when zone feature is enabled. | ### Activate and Deprovision Fields | Field | Type | Required | Notes | | ------------------------- | ------ | -------- | ---------------------------------------------------------------------------------- | | `accessControlVisitId` | string | Yes | Your ACS-side identifier returned in the Provision response. | | `accessControlLocationId` | string | No | Your ACS location partition key returned in the Provision response, if applicable. | | `badgeNumber` | string | Yes | The credential value (`barcode`) returned in the Provision response. | ### Deprovision Query Parameter | Parameter | Type | Location | Notes | | ---------------- | ------- | ------------ | --------------------------------------------------------------------------------------------------- | | `deactivateOnly` | boolean | Query string | When `true`, disable access without destructive deletion. Absent or `false` means full deprovision. | ## Consolidated Response Field Reference ### Provision Response | Field | Type | Required | Notes | | ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | string | Yes | Must be `PROVISIONED`. | | `data.barcode` | string | Yes | Credential value (QR code data or card number). For digital credentials: must be non-sequential and non-guessable. For physical: echo the `badgeNumber` from the request. | | `data.accessControlVisitId` | string | Yes | Your ACS-side identifier. Sine stores and returns this in all subsequent Activate and Deprovision calls. | | `data.accessControlLocationId` | string | No | Optional ACS location partition key. Stored and echoed back by Sine. | | `data.destinationName` | string | No | Display label for badge printing or QR display. | | `data.destinationId` | string | No | Identifier for the destination. | ### Activate Response | Field | Type | Required | Notes | | ------ | ------ | -------- | -------------------- | | `code` | string | Yes | Must be `ACTIVATED`. | ### Deprovision Response | Field | Type | Required | Notes | | ------ | ------ | -------- | ------------------------ | | `code` | string | Yes | Must be `DEPROVISIONED`. | ### Verify Response | Field | Type | Required | Notes | | ------ | ------ | -------- | ------------------ | | `code` | string | Yes | Must be `SUCCESS`. | ### Access Groups Response | Field | Type | Required | Notes | | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | `results` | array | Yes | List of access group objects. Each entry includes `id` and `name`. | | `results[].id` | string | Yes | Opaque ACS group identifier. This value is sent as `accessGroups` entries in lifecycle requests. | | `results[].name` | string | Yes | Human-readable group name shown in the Sine interface. | | `nextLink` | string | No | Full URL for the next page. Omit when no further pages exist. | ### Error Response (all endpoints) | Field | Type | Required | Notes | | --------- | ------ | -------- | ----------------------------------------------------------------------------------- | | `code` | string | Yes | A short machine-readable error code (e.g. `INVALID_CREDENTIAL`, `ACS_UNAVAILABLE`). | | `message` | string | Yes | A human-readable description of the failure. | ## Endpoint Behaviour Summary | Endpoint | Method | Blocking | Idempotent | Expected success code | Expected success HTTP status | | ---------------- | ------ | -------------------- | ---------- | --------------------- | ---------------------------- | | `/verify` | POST | Yes | Yes | `SUCCESS` | `200` | | `/provision` | POST | Yes (Sine waits) | Yes | `PROVISIONED` | `201` | | `/activate` | POST | No (fire-and-forget) | Yes | `ACTIVATED` | `200` | | `/deprovision` | POST | No (fire-and-forget) | Yes | `DEPROVISIONED` | `200` | | `/access-groups` | GET | N/A | Yes | N/A | `200` | ## Glossary Terms are listed in the order they are most likely encountered during implementation. | Term | Definition | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ACI** | Access Control Integration. Sine's standardised REST integration specification for connecting third-party access control systems to the Sine visitor lifecycle. | | **Integration endpoint** | The HTTPS API you build and host that receives ACI calls from Sine and translates them into ACS-specific operations. | | **ACS** | Access Control System. The physical security system responsible for controlling access at readers, turnstiles, doors, and gates. | | **Visit** | The Sine record representing a visitor's time-bounded presence at a site. Each visit has a unique `visitId` and maps to one credential lifecycle. | | **Visitor** | The person checking into a site via Sine. In your ACS, the equivalent record may be called a cardholder, person, occupant, or similar - these are functionally equivalent for ACI purposes. | | **Credential** | The access token presented at a reader (QR code value, physical card number, or virtual credential value). In Sine, this is the value returned as `barcode` from Provision. | | **Cardholder** | The person record in the ACS that holds one or more credentials. For most ACI integrations, a new cardholder is created per visit during Provision. | | **Access group** | A logical access entitlement grouping defined in the ACS (for example, Level 2, Car Park, Plant Room). Sine administrators select groups from a list sourced from your `/access-groups` endpoint. | | **visitId** | The primary Sine identifier for a visit. A UUID v4 value. Present in every lifecycle request and should be used as your idempotency key. | | **siteId** | Sine's identifier for the site/location. Present in every lifecycle request. | | **externalId** | An optional integration-specific reference string configured in Sine, passed to your endpoint on every request. Useful for multi-site integrations sharing a single endpoint. | | **accessControlVisitId** | The ACS-side identifier your Provision response returns. Sine stores this and echoes it back in every subsequent Activate and Deprovision call. Used to resolve the target credential without re-querying. | | **accessControlLocationId** | An optional ACS location partition key returned by your Provision response. Echoed back by Sine in later calls. Useful for multi-location ACS deployments that require a location context alongside the visit ID. | | **barcode** | The credential value returned in the Provision response (`data.barcode`). For digital credentials, this is an ACS-generated value. For physical credentials, this echoes the `badgeNumber` from the request. | | **badgeNumber** | The credential identifier sent by Sine in Activate and Deprovision requests. Corresponds to the `barcode` value from the Provision response. Also sent in Provision requests for physical card flows. | | **credentialType** | Specifies how a credential should be interpreted: `digital` (ACS generates a QR-compatible value), `physical` (Sine provides a pre-assigned card number), or `virtual` (vendor-specific mobile credential). | | **Provision** | The first lifecycle call. Creates a credential in the ACS in an inactive state and returns correlation identifiers. Sine blocks check-in on this response. | | **Activate** | The second lifecycle call. Enables access in the ACS for a previously provisioned credential. Called after Sine's approval checks pass. Non-blocking from Sine's perspective. | | **Deprovision** | The final lifecycle call. Revokes or deactivates a credential at the end of the visit. Non-blocking from Sine's perspective. | | **Verify** | A connectivity and authentication check called during integration setup and when administrators test the integration. No ACS operations are expected. | | **validFrom** | ISO 8601 UTC timestamp for the start of the credential validity window. Sent in Provision only. | | **validTo** | ISO 8601 UTC timestamp for the end of the credential validity window. Sent in Provision only. | | **deactivateOnly** | A query parameter on Deprovision (`?deactivateOnly=true`). When present, instructs your integration to disable access without destructive deletion. The default (absent or `false`) is full deprovision. | | **checkoutUrl** | A callback URL your ACS can call when a visitor badges out at an exit reader (ACS-initiated checkout). Format: `{base}/callbacks/checkout/{jwt}?teamId={teamId}`. Must also include the `x-sine-api-key` header. | | **Asset Management** | A Sine feature that allows site administrators to pre-register a pool of physical card numbers in Sine. When enabled, Sine assigns a card number from this pool at check-in and sends it as `badgeNumber` in the Provision request. | | **hostGroup** | An access group or department identifier for the visitor's host (the employee they are meeting). Present in the `host` object when a host is associated with the visit. | | **Sine-initiated checkout** | A checkout flow where the visitor or a Sine administrator triggers the end of a visit through the Sine platform. Triggers a Deprovision call to your endpoint. | | **ACS-initiated checkout** | An optional flow where your ACS calls Sine's `checkoutUrl` when a visitor badges out at an exit reader. Triggers Sine to mark the visit as checked out and subsequently call Deprovision. | | **PROVISIONED / ACTIVATED / DEPROVISIONED / SUCCESS** | The `code` values your endpoint must return on successful completion of each respective lifecycle operation. |