Universal Connector

This API endpoint allows you to send badge events to a specific connector identified by its unique UUID. Each event contains user-related data including email, timestamp, and a lock identifier.

  • HTTP Method: POST
  • Endpoint Path Parameter:
    • uuid (string): The unique identifier of the connector.

Request Payload

The request payload must be sent in JSON format and conform to the following type definitions:

Type Definitions

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

export type ConnectorEvent = {
  email: string;
  timestamp: string;
  lockId: string;
}; 

Payload Description

  • events: An array of objects, where each object represents a badge event. Each event object must include the following fields:
    • email (string): The email address of the user associated with the event.
    • timestamp (string): The timestamp for when the event occurred. This needs to be in ISO8601 format.
    • lockId (string): A unique identifier representing the lock (or session) associated with the event.

Example Request Payload

{
  "events": [
    {
      "email": "[email protected]",
      "timestamp": "2025-02-05T15:30:00Z",
      "lockId": "lock-1234"
    },
    {
      "email": "[email protected]",
      "timestamp": "2025-02-05T15:32:00Z",
      "lockId": "lock-5678"
    }
  ]
}

Request Headers

Include the following headers in your request:

  • Content-Type: application/json
  • Authorization: Access-Token YOUR_ACCESS_TOKEN

Response

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

Error Responses

  • HTTP Status Code: 400 Bad Request.
    Description: Returned if:
    • The specified connector uuid is misformatted.
    • Payload is already processed.
    • Payload has malformed events.
{
  "status": 400,
  "body": {
    "code": "INVALID_UUID_FORMAT" | "PAYLOAD_ALREADY_PROCESSED" | "MALFORMED_EVENTS"
  }
}
  • HTTP Status Code: 403 Forbidden
    Description: Returned if:
    • Access Token is missing.
    • Access Token is invalid.
    • Organization integration is missing necessary permissions.
{
  "status": 403,
  "body": {
    "code": "MISSING_ACCESS_TOKEN" | "INVALID_ACCESS_TOKEN" | "NOT_PERMITTED"
  }
}
  • HTTP Status Code: 404 Not Found
    Description: Returned if organization integration status is invalid.
{
  "status": 404,
  "body": {
    "code": "INVALID_INTEGRATION_STATUS"
  }
}

Malformed event types

  • INVALID_OBJECT_PROPERTY: Payload is missing required keys or has unsupported keys.
  • INVALID_EMAIL: Payload contains malformed e-mail.
  • INVALID_LOCK_ID: Payload contains lockId that is not of type string.
  • INVALID_LOCK_ID: Payload contains unsupported timestamp.

Code Sample

cURL Example

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": [
             {
               "email": "[email protected]",
               "timestamp": "2025-02-05T15:30:00Z",
               "lockId": "lock-1234"
             }
           ]
         }'

Additional Notes

  • Timestamp Format: Ensure that the timestamp is provided in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).
  • Validation: The server will validate the structure of the payload. Make sure all required fields (email, timestamp, lockId) are present for each event.
  • Rate Limiting: Check your API rate limits to avoid hitting the maximum number of requests per minute.