Gatekeeping Status API Reference

Get Tenant Gatekeeping Status

Returns the current gatekeeping status for a tenant, including their mandate state, last collection outcome, and whether access should be permitted.

Endpoint

GET /v1/gatekeeping/status

Authentication

API key required. Pass the key in the Authorization header:

Authorization: Bearer <api_key>

Query Parameters

Parameter	Type	Required	Description
email	string	Conditional	The tenant's email address. Required if external_ref is not provided.
external_ref	string	Conditional	The tenant's external reference as set by the consuming application. Required if email is not provided.

At least one of email or external_ref must be supplied.

Response

{
  "tenant_id": "tnt_01hx...",
  "email": "tenant@example.com",
  "external_ref": "agentOS-tenant-456",
  "mandate_status": "active",
  "last_collection_status": "collected",
  "access_allowed": true,
  "updated_at": "2025-01-15T09:32:00Z"
}

Response Fields

Field	Type	Description
tenant_id	string	The tenant's internal ID within the DD service
email	string	The tenant's email address
external_ref	string | null	The tenant's external reference, if set
mandate_status	enum	Current mandate status: active, suspended, cancelled, or failed
last_collection_status	string | null	Outcome of the most recent collection attempt, or null if no collection has been attempted
access_allowed	boolean	Whether the consuming application should grant this tenant access
updated_at	ISO 8601 datetime	Timestamp of the last status change

Error Responses

HTTP Status	Code	Description
400	MISSING_IDENTIFIER	Neither email nor external_ref was provided
401	UNAUTHORIZED	Missing or invalid API key
404	TENANT_NOT_FOUND	No tenant matching the supplied identifier was found for this customer

---

Webhook: Gatekeeping Status Changed

Fired whenever a tenant's gatekeeping status changes — including transitions in mandate_status, last_collection_status, or access_allowed.

Event Name

gatekeeping.status_changed

Payload

{
  "event": "gatekeeping.status_changed",
  "occurred_at": "2025-01-15T09:32:00Z",
  "customer_id": "cus_01hx...",
  "data": {
    "tenant_id": "tnt_01hx...",
    "email": "tenant@example.com",
    "external_ref": "agentOS-tenant-456",
    "mandate_status": "cancelled",
    "last_collection_status": "collected",
    "access_allowed": false,
    "previous_access_allowed": true
  }
}

Payload Fields

Field	Type	Description
event	string	Always gatekeeping.status_changed
occurred_at	ISO 8601 datetime	When the status change occurred
customer_id	string	The letting agent's customer ID
data.tenant_id	string	The tenant's internal ID
data.email	string	The tenant's email address
data.external_ref	string | null	The tenant's external reference, if set
data.mandate_status	enum	New mandate status
data.last_collection_status	string | null	Most recent collection outcome
data.access_allowed	boolean	New value of the access flag
data.previous_access_allowed	boolean	Previous value of the access flag, to help detect transitions

---