Match a carer to an order
/v1/events/{slug}/carer-applications/matchStep one of the carer form. The order number is the T-XXXXXX code on the attendee's ticket email; with it the carer gives the attendee's email or surname, and the answer is the attendees on that order who can have a carer, each with an opaque attendeeKey for the application step. Most orders hold one attendee; on a group order show the names and let the carer pick.
Every miss is the same no_match, whether the order does not exist, belongs to another event, was cancelled, or the email or surname did not agree. A form that told them apart would let a stranger enumerate order numbers, so do not try to be more specific than the message.
carerSlotsLeft is zero when the order already has a carer ticket or an application waiting; say so rather than sending an application that will be refused.
404 not_found for no visible reason.Request
curl -sS \
-X POST \
-H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
-H 'Content-Type: application/json' \
-d '{"orderNumber":"T-4K7Q2M","attendeeEmail":"jane@example.com","attendeeSurname":""}' \
'https://api.grofomo.com/v1/events/summer-fest/carer-applications/match?surface=web'Request body
orderNumberstringrequiredattendeeEmailstring | nullattendeeSurnamestring | null
Path parameters
slugstringrequired- The event's URL slug. Globally unique. It can change if the organiser renames the event, but an old slug keeps reaching the same event, so a stored one never breaks. Example: `summer-fest`.
Query parameters
surface'web'required- Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.
Response
{
"apiVersion": 1,
"data": {
"attendees": [
{
"attendeeKey": "ZXZlbnQtaWR8dGlja2V0LWlkOjE3ODk2NDM2MDAwMDA6Y2FyZXItYXR0ZW5kZWU.ZXhhbXBsZS1zaWduYXR1cmU",
"firstName": "Jane",
"ticketTypeName": "Weekend Camping",
"carerSlotsLeft": 1
}
]
}
}attendeesobject[]- The attendees on that order who can have a carer, in the order they were bought. One entry on most orders.
attendees[].attendeeKeystring- An opaque key for this ticket, valid for an hour. Send it as `attendeeKey` on the application.
attendees[].firstNamestring | null- The attendee's first name, so the carer can pick the right person on a group order.
attendees[].ticketTypeNamestring- The tier the attendee holds, e.g. "Weekend Camping".
attendees[].carerSlotsLeftnumber- How many more carer tickets this order can take. Zero means one is already issued or waiting.
Errors
unauthorizedHTTP 401- No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
origin_not_allowedHTTP 403- Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
not_foundHTTP 404- No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.
bad_requestHTTP 400- The body did not match the schema: an order number and the attendee's email or surname are required.
no_matchHTTP 404- The order number, email or surname did not agree with an order for this event with a tier that can have a carer.
applications_closedHTTP 409- The organiser is not taking carer applications for this event.
rate_limitedHTTP 429- Too many lookups from this address, or for this event. Try again later.
Notes
- Rate limited to roughly 10 requests per minute per caller. Guidance, not a contract — see caching and rate limits.
Cache-Control: no-store