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.
Updated about 1 month ago