title: “Requirements & Constraints”
description: “Authentication, environments, pagination, rate limits and conditional fields for the Integrations API.”
---## Authentication
All requests must include your API key in the X-Api-Key HTTP header:
curl --request GET \
--url 'https://api-alpha.fourvenues.com/integrations/events/' \
--header 'X-Api-Key: YOUR_API_KEY_HERE'
Getting an API key
API keys are provisioned by the Fourvenues team. To request one, contact integrations@fourvenues.com and include:
- Your venue name(s) and Fourvenues account email
- The integration you are building (e.g. “custom check-in scanner”, “BI dashboard”)
- The endpoints you need access to
API keys are scoped: they only grant access to the specific endpoints requested. If you need additional access later, contact the team to update your key’s permissions.
Key lifecycle
| Property | Detail |
|---|
| Expiry | Keys have a limited lifespan and must be rotated before expiry. |
| Revocation | Keys can be revoked immediately if misused. |
| Scope | Each key is tied to specific endpoints and your account’s venues only. |
| Environment | Base URL | Purpose |
|---|
| Alpha | https://api-alpha.fourvenues.com/integrations | Development & testing — uses isolated data, no real payments |
| Production | https://api.fourvenues.com/integrations | Live data — use only when your integration is fully tested |
The alpha environment contains test data only. Events, tickets and payments created there do not appear in production and vice versa. Always validate your integration against alpha before switching to production.
curl --request GET \
--url 'https://api-alpha.fourvenues.com/integrations/channels/' \
--header 'X-Api-Key: YOUR_API_KEY_HERE'
{
"success": true,
"data": [
{
"_id": "pw2gra4r20xlu02js0ybj42s6vYpAzeX",
"name": "My team",
"slug": "my-team"
}
]
}
| Parameter | Type | Description |
|---|
page | integer | Page number, starting at 1 |
limit | integer | Number of results per page (default varies per endpoint) |
start_date | string (YYYY-MM-DD) | Filter records created/updated after this date |
end_date | string (YYYY-MM-DD) | Filter records created/updated before this date |
date_field | string | Which date field to filter on: created_at or updated_at |
For incremental syncs, always use date_field=updated_at together with a narrow start_date/end_date window to avoid re-fetching unchanged records.
Check-in endpoint (PUT /integrations/tickets/{id}/checkin)
| Field | Required? | Notes |
|---|
enter | Always required | 1 to mark as entered, 0 to revert |
entry_date | Required when enter: 1 | ISO 8601 datetime string (e.g. 2024-09-28T23:00:00.000Z) |
Bookings (GET /integrations/bookings/)
| Field | Required? | Notes |
|---|
event_id | Required | The event to query bookings for |
date | Required | The event date in YYYY-MM-DD format |
429 Too Many Requests, implement exponential backoff before retrying.
---## Common errors
| HTTP Status | success | Cause | Fix |
|---|
401 Unauthorized | false | Missing or invalid X-Api-Key | Check the header name and key value |
403 Forbidden | false | Key does not have access to this endpoint | Contact the Fourvenues team to update key scope |
404 Not Found | false | Resource does not exist or belongs to another account | Verify the _id or code |
422 Unprocessable Entity | false | Missing required field or invalid value | Check the request body against the API reference |
429 Too Many Requests | false | Rate limit exceeded | Implement exponential backoff |
500 Internal Server Error | false | Unexpected server error | Retry once; if persistent, contact support |
