Record an access attempt or denial

Records an access attempt or denial that your system has already decided. The Door/Gate Controller is not contacted, and the door does not unlock.

Use this when your system refuses entry, or when an attempt should appear in Door & Gate Access Logs without an unlock. Performance Hub does not evaluate membership status, access hours, or other access rules.

A denied event appears in Door & Gate Access Logs with a Denied outcome, your partner name, the door, the member identifier when you send one, and the reason code in a readable form. For example, membership_expired is shown as "Membership Expired". reason_display_text and user_email are stored with the event.

Parameters

• door_id string required

  Door/Gate Controller ID returned by the list endpoint.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Performance Hub facility ID. Required for direct-link integrations.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Partner facility identifier. Required for linking-identifier integrations.

• outcome string required

  denied or attempted.

• reason string optional

  Lowercase snake_case reason code, up to 64 characters. Required when outcome is denied. Example: membership_expired.

• reason_display_text string optional

  Human-readable reason, up to 256 characters. Example: Membership expired on 2026-04-01.

• member_id string optional

  Partner member ID. Omit it when the credential did not match a member, such as an unknown card.

• user_email string optional

  Email of the person who attempted access.

• timestamp string optional

  When the attempt happened, as ISO 8601 with a timezone. Example: 2026-05-18T10:15:30Z. Defaults to the time the request is received. Must not be more than 5 minutes in the future or older than 30 days.

• idempotency_key string optional

  Replay-protection key, up to 128 characters. Reusing the same key for the same partner, facility, and door returns the original result.

Returns

Returns 201 when the event is recorded. Replaying the same idempotency_key returns 200 with idempotent set to true and does not create another event.

A dry-run key returns 200 with dry_run set to true. Nothing is recorded.

Common failures:

• 400 - the body is invalid, a denial has no reason, the timestamp is out of range, or facility_id / linking_identifier does not match a linked facility.
• 403 - the key is read-only.
• 403 integration_not_enabled - your integration is not enabled for the facility. message gives the reason.
• 404 - the Door/Gate Controller was not found for the linked facility.

Request

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/access-events \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "outcome": "denied",
    "reason": "membership_expired",
    "reason_display_text": "Membership expired on 2026-04-01",
    "member_id": "mem_12345",
    "user_email": "member@example.com",
    "timestamp": "2026-05-18T10:15:30Z",
    "idempotency_key": "evt_abc12345"
  }'

Response

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z"
}

Idempotent replay

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z",
  "idempotent": true
}