Universal Connector — Presence Events

Send presence events from a third-party system (badge readers, smart locks, turnstiles, occupancy sensors, etc.) into Robin via the universal connector.

POST https://badge-presence-collector.services.robinpowered.com/v1.0/connectors/{uuid}/presence

The {uuid} path parameter is your connector's unique identifier, provisioned by Robin during onboarding — see Prerequisites.

Prerequisites

Before you can send events, two things need to be in place. First, you need a connector UUID and an access token. Both are issued by Robin and are not self-served — contact your Robin representative to have a connector provisioned. You'll use the UUID in the endpoint path and the access token in the Authorization header. Second, if your integration will send events using source, you also need a source mapping configured for the connector. This tells Robin which Robin entity each source.id value corresponds to. See Source mapping below. Integrations that only ever send target can skip this step.

Identifying where the event happened

Every event carries a single locator that tells Robin where the presence happened. There are two kinds of locator, and you provide exactly one of them per event:

Exactly one of source or target must be supplied per event. Violations are rejected with MALFORMED_EVENTS and INVALID_REQUEST on the offending event. Each event in a batch is validated and routed independently, so a single request can mix source and target events.

Source mapping

When you send events using source, Robin needs to know which Robin entity (a location or a level) each source.id value corresponds to. This mapping is configured per connector by the Robin team and is not something the caller provides at request time.

Onboarding requirement: If your integration will send events using source, you must coordinate with the Robin team to configure the source mapping for your connector before events will resolve. Without a configured mapping, valid-looking source events have nothing to resolve to and will be rejected. Reach out to your Robin contact during integration onboarding to provision this.

Request payload

The request body is JSON conforming to the type definitions below.

Type definitions

export type ConnectorPayload = {
  events: ConnectorEvent[];
};

// Identifies the user the event is for.
// Currently only `email` is supported; additional identifier fields
// (e.g., employee_id, badge_id, sso_id) may be added over time.
export type Subject = {
  email: string;
};

// Reference to an entity in the caller's system. Resolved to a Robin
// entity via the connector's source mapping.
export type Source = {
  id: string;
};

// Direct reference to a Robin entity. Both fields are required.
export type Target = {
  id: number;                  // Integer Robin entity ID.
  type: "LOCATION" | "LEVEL";  // Which kind of entity `id` refers to.
};

// Each event must include `subject` and `timestamp`, plus
// exactly one of `source` or `target`.
export type ConnectorEvent = {
  subject: Subject;
  timestamp: string;

  source?: Source;
  target?: Target;

  /**
   * @deprecated Use `subject.email` instead. Continues to be accepted for
   * backward compatibility — a bare top-level `email` is treated as
   * `subject.email`. If both are supplied, `subject.email` wins. Will be
   * removed in a future major version.
   */
  email?: string;

  /**
   * @deprecated Use `source.id` instead. Continues to be accepted for backward
   * compatibility — a bare `lockId` is treated as `source.id`. If both `lockId`
   * and `source` are supplied, `source` wins. Will be removed in a future
   * major version.
   */
  lockId?: string;
};

Field reference

Request headers

Send Content-Type: application/json and Authorization: Access-Token YOUR_ACCESS_TOKEN.

Examples

Source event

{
  "events": [
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-05-18T15:30:00Z",
      "source": { "id": "lock-1234" }
    }
  ]
}

Target events

target.type selects whether the id refers to a Robin location or level.

{
  "events": [
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-06-01T09:15:00Z",
      "target": { "id": 999, "type": "LOCATION" }
    },
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-06-01T09:16:00Z",
      "target": { "id": 555, "type": "LEVEL" }
    }
  ]
}

Mixed batch

A single request can mix source and target events; each event is validated and routed independently.

{
  "events": [
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-06-01T09:15:00Z",
      "source": { "id": "lock-1234" }
    },
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-06-01T09:16:00Z",
      "target": { "id": 999, "type": "LOCATION" }
    },
    {
      "subject": { "email": "[email protected]" },
      "timestamp": "2026-06-01T09:17:00Z",
      "target": { "id": 555, "type": "LEVEL" }
    }
  ]
}

cURL

curl -X POST "https://badge-presence-collector.services.robinpowered.com/v1.0/connectors/YOUR_CONNECTOR_UUID/presence" \
     -H "Content-Type: application/json" \
     -H "Authorization: Access-Token YOUR_ACCESS_TOKEN" \
     -d '{
           "events": [
             {
               "subject": { "email": "[email protected]" },
               "timestamp": "2026-05-18T15:30:00Z",
               "source": { "id": "lock-1234" }
             }
           ]
         }'

Responses

Success

A successful response returns HTTP 200 with one of two codes:

{
  "status": 200,
  "body": {
    "code": "OK" | "PAYLOAD_ALREADY_PROCESSED"
  }
}

PAYLOAD_ALREADY_PROCESSED is returned when the same payload has already been ingested (idempotency hit). Treat it as success — no retry needed.

Error responses

400 Bad Request — returned with one of the following codes:

{
  "status": 400,
  "body": {
    "code": "INVALID_UUID_FORMAT" | "INVALID_PAYLOAD" | "MALFORMED_EVENTS"
  }
}

When the code is MALFORMED_EVENTS, the body additionally includes a failedEvents array detailing which events were rejected and why:

{
  "code": "MALFORMED_EVENTS",
  "failedEvents": [
    {
      "row": 0,
      "eventUuid": "f1c2a3...",
      "reason": ["INVALID_SUBJECT", "INVALID_TIMESTAMP"]
    }
  ]
}

Each entry has the event's zero-based row in the submitted batch, a server-assigned eventUuid for log correlation, and a reason array listing every per-event error code that applies (so a single event can surface multiple failures in one response). Events not present in failedEvents were accepted. Note that there is currently no way for callers to supply their own per-event identifier on the way in — use row to correlate failures back to the submitted batch.

403 Forbidden — returned if the access token is missing or invalid, or the organization integration is missing permissions.

{
  "status": 403,
  "body": {
    "code": "MISSING_ACCESS_TOKEN" | "INVALID_ACCESS_TOKEN" | "NOT_PERMITTED"
  }
}

404 Not Found — returned if the organization integration status is invalid.

{
  "status": 404,
  "body": {
    "code": "INVALID_INTEGRATION_STATUS"
  }
}

Malformed event codes

Migrations

Two fields have been renamed in this revision. Existing integrations continue to work — both legacy fields are accepted as aliases on every request. Both legacy fields will be removed in a future major version, so migrate when convenient.

email → subject.email

If your integration currently sends a top-level email:

• No urgent action required. Existing payloads continue to work; a bare top-level email is treated as subject.email.
• When you next touch the integration, move the value into a subject object as the email field. The value itself is unchanged.

lockId → source.id

If your integration currently sends lockId:

• No urgent action required. Existing payloads continue to work; a bare top-level lockId is treated as source.id.
• When you next touch the integration, move the value into a source object as the id field. The value itself is unchanged.

Additional notes

• Timestamp format: ISO 8601 (YYYY-MM-DDTHH:mm:ssZ).
• Per-event validation: every event in a batch is validated independently. A single malformed event does not invalidate the rest of the batch — see the MALFORMED_EVENTS response for which events were rejected.
• Source mapping is per-connector: the mapping that resolves source.id values to Robin entities is configured on the connector itself by the Robin team. There is no caller-side way to inspect or modify it through this endpoint.
• Rate limiting: check your API rate limits to avoid hitting the maximum number of requests per minute.