RSVP

The RSVP API provides a simplified registration flow for free events that do not use tickets. Unlike the checkout flow, RSVP creates a registration directly without a cart or payment step.

The authenticated endpoint (/api/v1/events/:id/rsvp) requires your secret key. A public widget version (/api/v1/public/events/:id/rsvp) is also available for guest registrations via embedded widgets — see Public RSVP below.

When to use RSVP vs Checkout

Name
RSVP
Type
Free events
Description
Use for free events without ticket types. Events where has_tickets is false.
Name
Checkout
Type
Ticketed events
Description
Use for paid events or events with ticket types. Events where has_tickets is true.

Check the event has_tickets property to determine which flow to use. If has_tickets is true, use the Checkout flow even for free tickets.

POST/api/v1/events/:id/rsvp

Register RSVP

Required attributes

Name
name
Type
string
Description
Full name of the attendee.
Name
email
Type
string
Description
Email address for confirmation.

Conditional attributes

Name
phone
Type
string
Description
Phone number of the attendee. Availability depends on the event's phone field setting: required (must be provided), optional (nullable), or off (not accepted). Max 20 characters.
Name
occurrence_id
Type
string
Description
ULID of the specific occurrence date. Required for recurring events. Must be a scheduled occurrence with a future date and available capacity.

Optional attributes

Name
custom_answers
Type
object
Description
Answers to custom questions keyed by question ULID. See custom questions for validation rules per question type.

Response attributes

Name
registration
Type
object
Description
The created registration record.
Name
registration.id
Type
string
Description
Registration ULID (this is an Order ULID internally).
Name
registration.status
Type
string
Description
confirmed for immediate registrations, pending_approval when the event requires organizer approval.
Name
registration.name
Type
string
Description
Attendee name as submitted.
Name
registration.email
Type
string
Description
Attendee email as submitted.
Name
registration.requires_approval
Type
boolean
Description
Whether the organizer must approve this registration before it is confirmed.

Request

POST

/api/v1/events/:id/rsvp

curl -X POST https://api.qariyb.com/api/v1/events/01HWX9KPQR/rsvp \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Fatima Ahmed",
    "email": "fatima@example.com",
    "phone": "+1234567890"
  }'

Response (Confirmed)

{
  "success": true,
  "code": 101,
  "locale": "en",
  "message": "OK",
  "data": {
    "registration": {
      "id": "01HWX9REG1234567890ABCD",
      "status": "confirmed",
      "name": "Fatima Ahmed",
      "email": "fatima@example.com",
      "requires_approval": false
    }
  }
}

Response (Pending Approval)

{
  "success": true,
  "code": 101,
  "locale": "en",
  "message": "OK",
  "data": {
    "registration": {
      "id": "01HWX9REG1234567890ABCD",
      "status": "pending_approval",
      "name": "Fatima Ahmed",
      "email": "fatima@example.com",
      "requires_approval": true
    }
  }
}

Recurring events

For recurring events, you must specify which occurrence the attendee is registering for.

First, retrieve the event to get available occurrences, then include the occurrence_id in your RSVP request.

The API validates that the occurrence belongs to the event, is scheduled, has a future date, and has available capacity.

RSVP for recurring event

curl -X POST https://api.qariyb.com/api/v1/events/01HWX9KPQR/rsvp \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fatima Ahmed",
    "email": "fatima@example.com",
    "occurrence_id": "01HWX9OCC1234567890ABCD"
  }'

Error: Missing occurrence

{
  "success": false,
  "code": 200,
  "locale": "en",
  "message": "Please choose which date you are attending.",
  "data": {
    "messages": {
      "occurrence_id": ["Please choose which date you are attending."]
    }
  }
}

Custom questions

Events may have custom questions that attendees need to answer during registration.

Question types

Name
text
Type
Free text
Description
Free-form text answer.
Name
select
Type
Single choice
Description
Single selection from dropdown options.
Name
radio
Type
Single choice
Description
Single selection from radio button options.
Name
checkbox
Type
Multiple choice
Description
Multiple selections from options.

Submitting answers

{
  "name": "Fatima Ahmed",
  "email": "fatima@example.com",
  "custom_answers": {
    "01HWX9Q001": "Halal only",
    "01HWX9Q002": "M",
    "01HWX9Q003": ["Networking", "Workshops"]
  }
}

Error handling

HTTP	ApiCode	Scenario	Action
401	606	No secret key sent	Send your secret key as `Authorization: Bearer sk_live_…`
401	607	Key not valid for this surface	Use the secret key, not the `pk_live_` publishable one
403	500	Event is draft or not available	Event must be published
403	—	Registration access denied	User cannot register for this event (FormRequest authorization)
422	200	Event is paid (not free)	Use the checkout flow instead
422	200	Event has tickets	Use the checkout flow instead
422	200	Validation error (missing/invalid fields)	Check name, email, phone, occurrence_id, custom_answers
422	507	Registration is closed	Organizer has closed registration for this event

Validation error messages

Required fields:

"Full name is required."
"Email address is required."
"Please enter a valid email address."
"Phone number is required for this event." (when phone is required)

Occurrence validation (recurring events):

"Please select a date for this recurring event."
"Invalid or unavailable date selected."
"This date is at full capacity."

Custom question validation:

"{question} is required." (when required question is unanswered)
"Please select a valid option for {question}." (invalid select/radio choice)
"Please select at least one option for {question}." (empty required checkbox)

View all error codes

POST/api/v1/public/events/:id/rsvp

Public RSVP

Register a guest attendee for a free event via the public widget API. This endpoint does not require user authentication — it uses widget key authentication instead.

The request body, response format, and validation rules are identical to the authenticated RSVP endpoint above. The only differences are:

Uses X-Widget-Key header (publishable key) instead of Authorization: Bearer secret key
No user_id is attached to the registration (guest registration)
Subject to widget rate limiting (60/min per key)

Request

POST

/api/v1/public/events/:id/rsvp

curl -X POST https://api.qariyb.com/api/v1/public/events/01HWX9KPQR/rsvp \
  -H "X-Widget-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Fatima Ahmed",
    "email": "fatima@example.com",
    "phone": "+1234567890"
  }'

Response

{
  "success": true,
  "code": 101,
  "locale": "en",
  "message": "OK",
  "data": {
    "registration": {
      "id": "01HWX9REG1234567890ABCD",
      "status": "confirmed",
      "name": "Fatima Ahmed",
      "email": "fatima@example.com",
      "requires_approval": false
    }
  }
}