Requirements

title: “Requirements & Constraints” description: “Authentication, environments, webhook security, pagination, rate limits and conditional fields for the Channel Manager API.” ---## Authentication All requests must include your API key in the X-Api-Key HTTP header:

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/auth' \
  --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 marketplace/channel name and company details - The venues (hosts) you have or plan to have partnerships with - The integration you are building (e.g. “ticket marketplace”, “event aggregator”) - The endpoints you need access to

API keys are channel-scoped: they grant access only to venues that have explicitly added your channel as a partner. If a venue removes you as a partner, events from that venue will no longer appear in your API responses.

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 a specific channel and its partner venues.

---## Environments

Environment	Base URL	Purpose
Alpha	`https://channels-service-alpha.fourvenues.com`	Development & testing — isolated data, no real payments
Production	`https://channels-service.fourvenues.com`	Live data — use only when fully tested

The alpha environment contains test data only. Always validate your integration end-to-end (including the webhook flow) in alpha before switching to production keys.

To verify connectivity:

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/auth' \
  --header 'X-Api-Key: YOUR_API_KEY_HERE'

A valid response includes your channel identity and all authorized host venues. ---## Conditional required fields

List creation (`POST /lists`)

The fields required when creating a guest list entry depend on the list rate configuration. Always fetch the list rate first and check:

Flag on list rate	Meaning
`requires_full_name: true`	`name` is required in the request body
`requires_email: true`	`email` is required in the request body
`requires_phone: true`	`phone` is required in the request body

Example — list rate with email + name required (phone optional):

{
  "rate_id": "lr_888",
  "event_id": "ev_abc123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "for": 2
}

Submitting without a required field returns 422 Unprocessable Entity.

Ticket checkout (`POST /tickets/checkout`)

Field	Required?	Notes
`redirect_url`	Required	URL the user lands on after successful payment
`error_url`	Required	URL the user lands on after failed payment
`ticket_rate_id`	Required	The rate the user is purchasing
`tickets`	Required	Array with at least one ticket object
`tickets[].email`	Depends on `fields` config of the rate	—
`tickets[].full_name`	Depends on `fields` config of the rate	—
`tickets[].price_id`	Optional	ID of the price you displayed; returns `conditions_changed` flag
`tickets[].supplements`	Optional	Array of supplement IDs
`tickets[].warranty`	Required only if rate has warranty enabled	Boolean
`discount_code`	Optional	Applied to all tickets in the session
`send_resources`	Optional	If `true`, Fourvenues sends ticket by email/SMS/WhatsApp
`metadata`	Optional	Free-form JSON object, max 1 KB — useful for your internal IDs

---## Webhooks Webhooks allow you to receive real-time notifications when payments complete or refunds are requested. See the full guide at Webhook Introduction.

Setting up a webhook endpoint

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/webhooks' \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://myapp.com/webhooks/fourvenues",
    "events": ["payment.success", "ticket.refund_request"]
  }'

Verifying webhook signatures

Each webhook delivery includes a signature header so you can confirm the request is genuinely from Fourvenues. See Webhook Authentication for the verification algorithm.

Never process a webhook without verifying its signature. Always validate the signature before updating your database or fulfilling orders.

Available webhook events

Event	Triggered when
`payment.success`	A buyer completes payment for a checkout session
`ticket.refund_request`	A buyer requests a refund for their ticket

---## Pagination

Parameter	Type	Description
`page`	integer	Page number starting at `1`
`limit`	integer	Results per page (default varies per endpoint)
`start_date`	string (`YYYY-MM-DD` or ISO 8601)	Start of date range filter
`end_date`	string (`YYYY-MM-DD` or ISO 8601)	End of date range filter
`organization_id`	string	Filter events by a specific host organization
`location_id`	string	Filter events by venue location

---## Rate limits - Burst requests: Avoid more than 10 requests per second from a single API key. - 429 responses: If you receive 429 Too Many Requests, implement exponential backoff before retrying. - Webhook retries: If your endpoint returns a non-2xx status, Fourvenues will retry the delivery with backoff. Ensure your endpoint responds quickly (< 5 seconds) and processes asynchronously. ---## Common errors

HTTP Status	Cause	Fix
`401 Unauthorized`	Missing or invalid `X-Api-Key`	Check the header name and key value
`403 Forbidden`	Key doesn’t have access to this endpoint or venue	Contact the Fourvenues team to update your key scope, or verify the venue has added your channel
`404 Not Found`	Resource doesn’t exist or is not accessible to your channel	Verify the `_id` or `slug`; confirm the venue is a partner
`422 Unprocessable Entity`	Missing required field or invalid value	Check the request body against the list rate’s `requires_*` flags and the API reference
`429 Too Many Requests`	Rate limit exceeded	Implement exponential backoff
`500 Internal Server Error`	Unexpected server error	Retry once; if persistent, contact support

---## Security considerations - Never expose your API key client-side — all requests must go through your backend. - Validate webhook signatures before acting on any webhook payload. - Rotate keys regularly — contact the Fourvenues team to issue a new key. - Use HTTPS only — HTTP requests are rejected at the infrastructure level. - Store metadata wisely — the metadata field is not encrypted; do not store sensitive PII there.

Introduction

API Reference

Webhooks

Recipes

Getting an API key

Key lifecycle

List creation (`POST /lists`)

Ticket checkout (`POST /tickets/checkout`)

Setting up a webhook endpoint

Verifying webhook signatures

Available webhook events

​Getting an API key

​Key lifecycle

​List creation (POST /lists)

​Ticket checkout (POST /tickets/checkout)

​Setting up a webhook endpoint

​Verifying webhook signatures

​Available webhook events

Getting an API key

Key lifecycle

List creation (`POST /lists`)

Ticket checkout (`POST /tickets/checkout`)

Setting up a webhook endpoint

Verifying webhook signatures

Available webhook events