Quick Reference

14 min

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.