Documentation
search

API Integrations

How to use the Event Vault API to manage guests and tickets.

Event Vault offers a REST API so you can automate guest and ticket management, or connect your event data to external systems. All requests are sent to the base URL below and require authentication headers on every call.

Base URL: https://api.event-vault.com

What you can do with the API:

  • Add or remove guests from an event
  • Add or remove tickets for a guest
  • Query guests, tickets, and event guest metrics

Authentication

Every request must include the following HTTP headers:

Header Required Description
x-api-key ✓ Your API key, keep this secret
x-client-id ✓ Your client ID as shown in the Event Vault console
x-event-id ✓ The ID of the event you want to manage
x-timestamp ✓ Current Unix timestamp in milliseconds (e.g. Date.now()). Must be within 5 minutes of server time.

Response Codes

Write endpoints (addGuest, removeGuest, addTicket, removeTicket) return plain-text bodies. Read endpoints (getGuests, getGuestCount, etc.) return JSON. Always check the HTTP status code first.

Status Meaning Typical Cause
200 OK Success Operation completed successfully
400 Bad Request Missing required fields A required header, body field, or query parameter was omitted
403 Forbidden Invalid API key The x-api-key does not match the client’s registered key
404 Not Found Resource not found Client, event, user, or ticket does not exist
408 Request Timeout Timestamp out of range x-timestamp is more than 5 minutes from server time
409 Conflict Conflict with existing state Guest already registered
500 Internal Server Error Unexpected server error An unhandled error occurred on the server

POST /addGuest

Adds a guest to an event. The guest must not already be registered.

Request body fields

Field Type Required Description
userEmail string ✓ Guest’s email address, used as the unique identifier
name string Guest’s full name
role string Guest’s job title or role (e.g. "Speaker", "Attendee")
company string Guest’s company or organisation
phone string Guest’s phone number (e.g. "+1234567890")
url string Guest’s website or profile URL
country string Guest’s country
Response codes
Status Response body Description
200 OK User added successfully. Guest was added to the event
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include userEmail in the body. userEmail field is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. The x-client-id does not match any known client
404 Not Found Event not found. The x-event-id does not match any event for this client
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
409 Conflict User is already registered for the event. A guest with this email is already registered
500 Internal Server Error Error adding user to the event. Unexpected server error

Example request

curl "https://api.event-vault.com/addGuest" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)" \
  -d '{
    "userEmail": "[email protected]",
    "name": "Jane Doe",
    "role": "Attendee",
    "company": "Acme Corp",
    "phone": "+1234567890",
    "url": "https://linkedin.com/in/janedoe",
    "country": "USA"
  }'

POST /removeGuest

Removes a guest from an event. The guest must currently be registered.

Request body fields

Field Type Required Description
userEmail string ✓ Email address of the guest to remove
Response codes
Status Response body Description
200 OK User removed successfully. Guest was removed
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include userEmail in the body. userEmail field is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. The x-client-id does not match any known client
404 Not Found Event not found. The x-event-id does not match any event for this client
404 Not Found User is not registered for the event. No guest with this email exists in the event
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error removing user from the event. Unexpected server error

Example request

curl "https://api.event-vault.com/removeGuest" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)" \
  -d '{"userEmail": "[email protected]"}'

POST /addTicket

Creates a ticket for a guest. If a ticket of the same type already exists for this guest it will be overwritten (upsert behaviour).

Request body fields

Field Type Required Description
userEmail string ✓ Email address of the guest to assign the ticket to
ticketType string ✓ Ticket type identifier (e.g. "ENTRY", "VIP", "WORKSHOP")
sessionId string ID of a specific session this ticket grants access to. Omit or pass "" for general-admission
Response codes
Status Response body Description
200 OK Ticket created successfully. Ticket was created or updated
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include userEmail and ticketType in the body. userEmail or ticketType is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. The x-client-id does not match any known client
404 Not Found Event not found. The x-event-id does not match any event for this client
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error creating ticket for the guest. Unexpected server error

Example request

curl "https://api.event-vault.com/addTicket" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)" \
  -d '{
    "userEmail": "[email protected]",
    "ticketType": "ENTRY",
    "sessionId": ""
  }'

POST /removeTicket

Deletes a specific ticket from a guest. Both the email address and ticket type must match an existing ticket.

Request body fields

Field Type Required Description
userEmail string ✓ Email address of the guest whose ticket should be removed
ticketType string ✓ Type of the ticket to remove, must match the ticketType used when created
Response codes
Status Response body Description
200 OK Ticket removed successfully. Ticket was deleted
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include userEmail and ticketType in the body. userEmail or ticketType is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. The x-client-id does not match any known client
404 Not Found Event not found. The x-event-id does not match any event for this client
404 Not Found Ticket not found for the user. No matching ticket exists for this guest and type
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error removing ticket for the guest. Unexpected server error

Example request

curl "https://api.event-vault.com/removeTicket" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)" \
  -d '{
    "userEmail": "[email protected]",
    "ticketType": "ENTRY"
  }'

GET /getGuestCount

Returns the current guest metrics for the event. No request body required.

Response body (JSON)

{
  "guestCount": 42,
  "maxAssignedUsers": 57
}

Response codes

Status Response Description
200 OK JSON object Guest metrics returned (guestCount and maxAssignedUsers)
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. / Event not found. Client or event does not exist
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error getting guest count. Unexpected server error

Example request

curl "https://api.event-vault.com/getGuestCount" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)"

GET /getGuests

Returns an array of all guest objects registered for the event. No request body required.

Response body (JSON array)

[
  {
    "email": "[email protected]",
    "country": "USA",
    "registered": false,
    "vCardData": {
      "FN": "Jane Doe",
      "ROLE": "Attendee",
      "ORG": "Acme Corp",
      "TEL": "+1234567890",
      "URL": "https://linkedin.com/in/janedoe"
    }
  }
]

Response codes

Status Response Description
200 OK JSON array Array of guest objects (empty array if no guests)
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. / Event not found. Client or event does not exist
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error getting guests. Unexpected server error

Example request

curl "https://api.event-vault.com/getGuests" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)"

GET /getGuestTickets

Returns all tickets assigned to a specific guest. The guest email is passed as a query parameter.

Query parameters

Parameter Type Required Description
userEmail string ✓ Email address of the guest whose tickets to retrieve

Response body (JSON array)

[
  {
    "EMAIL": "[email protected]",
    "TIER": "ENTRY",
    "sessionId": ""
  }
]

Response codes

Status Response Description
200 OK JSON array Array of ticket objects (empty array if none found)
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include userEmail as a query parameter. userEmail query parameter is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. / Event not found. Client or event does not exist
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error getting guest tickets. Unexpected server error

Example request

curl "https://api.event-vault.com/getGuestTickets?userEmail=jane.doe%40example.com" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)"

GET /getTicketsByType

Returns all tickets of a specific type for the event. Useful for checking how many guests hold a particular tier. The ticket type is passed as a query parameter.

Query parameters

Parameter Type Required Description
ticketType string ✓ Ticket type to filter by (e.g. "ENTRY", "VIP")

Response body (JSON array)

[
  {
    "EMAIL": "[email protected]",
    "TIER": "VIP",
    "sessionId": ""
  }
]

Response codes

Status Response Description
200 OK JSON array Array of matching ticket objects (empty array if none found)
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
400 Bad Request The request must include ticketType as a query parameter. ticketType query parameter is missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. / Event not found. Client or event does not exist
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error getting tickets by type. Unexpected server error

Example request

curl "https://api.event-vault.com/getTicketsByType?ticketType=VIP" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)"

GET /getAllTickets

Returns all tickets for the event across all guests and ticket types. No request body or query parameters required.

Response body (JSON array)

[
  {
    "EMAIL": "[email protected]",
    "TIER": "ENTRY",
    "sessionId": ""
  }
]

Response codes

Status Response Description
200 OK JSON array Array of all ticket objects (empty array if none found)
400 Bad Request The request must include x-api-key, x-client-id, x-event-id, and x-timestamp headers. One or more required auth headers are missing
403 Forbidden Invalid API key. The x-api-key does not match
404 Not Found Client not found. / Event not found. Client or event does not exist
408 Request Timeout Request timestamp is outside the allowed 5-minute window. x-timestamp is stale or too far in the future
500 Internal Server Error Error getting all tickets. Unexpected server error

Example request

curl "https://api.event-vault.com/getAllTickets" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "x-event-id: <your-event-id>" \
  -H "x-timestamp: $(date +%s%3N)"
← Publishing Analytics →