Developers

API reference

Create and look up parties from your own booking form or CRM. Available to Owners with the API access module (Pro plan) - create a key under Settings → API keys.

Base URL

https://mypartyhub.com/api/v1 - served on the platform host only, not on Owner subdomains or custom domains.

Authentication

Send your key as a bearer token:

Authorization: Bearer 12|mph_...

Each key acts as the Owner who created it and only sees that Owner's parties. Keys don't expire. Revoking a key deletes it immediately.

A key stops working (403) while the Owner is suspended or no longer has the API module, for example after dropping to Starter. It works again if access returns.

Scopes

ScopeAllows
party:readGET /parties, GET /parties/{id}
party:createPOST /parties
rsvp:readGET /parties/{id}/rsvps
document:readGET /parties/{id}/documents
checklist:readGET /parties/{id}/checklists

POST /parties

Creates a draft party. By default the host (booker) is not emailed, and their link doesn't work until the owner sends it or marks the party ready for the host from the party page, which moves it to pending_confirmation. Pass email_host: true to email the host their link straight away instead; the party is then created as pending_confirmation. Requires party:create.

Getting the host their link

Emailing the host is optional: nothing is sent unless you ask for it. There are two ways:

  • Email the host straight away. Send "email_host": true with the request. The host is emailed their link as soon as the party is created, and the party starts as pending_confirmation (waiting on the host). There's no chance to check the party first, so only do this if your form or CRM sends reliable details.
  • Check first, then send (the default). Leave email_host out and the party is created as a draft; the host's link shows a "not ready yet" page. Open the party in your control panel and check the date, start and end times, venue, each child's name and age, and the host's name, email and phone. Fix anything that's wrong with Edit party, then press Mark ready for host. The dialog has an optional Email the host their link box: leave it ticked to email them, or untick it if you've already given them the link yourself (for example the booker_link_url from your own system). Either way the link starts working.

We recommend checking first. A party made through the API holds exactly what your form or CRM sent, so a typo or a field in the wrong place goes straight onto it, and the host is asked to confirm these details. The invite their guests see is built from them.

FieldTypeRules
childrenarrayrequired, at least one
children[].namestringrequired, max 255
children[].ageintegerrequired, 0–25
party_datestringrequired, YYYY-MM-DD, today or later
start_timestringrequired, HH:MM
end_timestringrequired, HH:MM, after start_time
venue_addressstringoptional, max 255
venue_namestringoptional, max 255
venue_line1stringoptional, max 255
venue_citystringoptional, max 255
venue_postcodestringoptional, max 32
venue_countrystringoptional, max 255
venue_latnumberoptional, -90 to 90
venue_lngnumberoptional, -180 to 180
venue_place_idstringoptional, max 255
special_notesstringoptional, max 2000
booker_namestringrequired, max 255
booker_emailstringrequired, email
booker_phonestringrequired, max 40
rsvp_contact_namestringoptional, defaults to booker_name
rsvp_contact_phonestringoptional, defaults to booker_phone
email_hostbooleanoptional, default false; true emails the host their link now
curl -X POST https://mypartyhub.com/api/v1/parties \
  -H "Authorization: Bearer 12|mph_..." \
  -H "Content-Type: application/json" \
  -d '{
"children": [{"name": "Mia", "age": 5}, {"name": "Theo", "age": 7}],
"party_date": "2026-11-14",
"start_time": "14:00",
"end_time": "16:00",
"venue_address": "Old Vic Hall, Bristol",
"booker_name": "Sarah Jones",
"booker_email": "[email protected]",
"booker_phone": "07700 900123"
  }'

Returns 201 Created with the party:

{
  "data": {
"id": "9d2f6c1e-5b0a-4f7e-9d1c-2a3b4c5d6e7f",
"status": "draft",
"party_date": "2026-11-14",
"start_time": "14:00",
"end_time": "16:00",
"venue_address": "Old Vic Hall, Bristol",
"venue": {
  "name": null, "line1": null, "city": null, "postcode": null,
  "country": null, "lat": null, "lng": null, "place_id": null
},
"special_notes": null,
"children": [{"name": "Mia", "age": 5}, {"name": "Theo", "age": 7}],
"booker": {"name": "Sarah Jones", "email": "[email protected]", "phone": "07700 900123"},
"rsvp_contact": {"name": "Sarah Jones", "phone": "07700 900123"},
"guest_count": 0,
"booker_link_url": "https://acme.mypartyhub.com/my/auth/…",
"invite_url": null,
"confirmed_at": null,
"created_at": "2026-09-21T10:15:00+00:00",
"updated_at": "2026-09-21T10:15:00+00:00"
  },
  "host_emailed": false
}

host_emailed says whether the host was emailed their link. It is false unless you sent email_host: true and the email went. If you asked and the email failed, the party is still created (as a draft), host_emailed is false, and the response carries a warning:

"warning": {
  "code": "host_email_failed",
  "message": "The party was created, but the host's link couldn't be emailed, so it is still a draft. Check the party and send the link from the party page."
}

Don't retry the create, which would make a second party. Open the party and send the link from there.

booker_link_url is the host's private sign-in link; treat it like a password. It only works once the party leaves draft; until then the host sees a "not ready yet" page. Only this create response includes it. invite_url stays null until the host confirms the party. status is one of draft, pending_confirmation, confirmed. guest_count is the total guests across "yes" RSVPs only - a decline never adds to it.

Requests are not idempotent: retrying a create that timed out can create a second party.

GET /parties

Lists your parties, newest party date first. Requires party:read.

QueryNotes
statusdraft, pending_confirmation or confirmed
date_fromYYYY-MM-DD, party date on or after
date_toYYYY-MM-DD, party date on or before
per_page1–100, default 25
pagepage number, default 1

Returns {"data": [...], "links": {...}, "meta": {...}}, where each item has the shape above (without booker_link_url) and meta carries current_page, last_page, per_page and total.

GET /parties/{id}

One party, same shape as above without booker_link_url. Requires party:read. Another Owner's party returns 404.

GET /parties/{id}/rsvps

Lists guest RSVPs on a party, newest first. Requires rsvp:read. Another Owner's party returns 404.

QueryNotes
statusyes or no
per_page1–100, default 25
pagepage number, default 1
{
  "data": [
{
  "id": 42,
  "status": "yes",
  "guest_name": "Sarah Jones",
  "guest_count": 2,
  "attendees": ["Sarah Jones", "Tom Jones"],
  "notes": "Dairy-free please.",
  "created_at": "2026-09-21T10:15:00+00:00",
  "updated_at": "2026-09-21T10:15:00+00:00"
}
  ],
  "links": { "...": "..." },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

The guest's email is never included, on any plan or scope - an Owner (and by extension their API key) never sees a guest's plaintext email address.

GET /parties/{id}/documents

Lists documents attached to a party, in display order. Requires document:read. Another Owner's party returns 404.

QueryNotes
per_page1–100, default 25
pagepage number, default 1
{
  "data": [
{
  "id": "3f2a1b4c-...",
  "title": "Party pack",
  "description": "Everything you need to know.",
  "instruction_text": "Print two copies.",
  "display_order": 0,
  "file": {
    "filename": "party-pack.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 412000
  },
  "release_rule": "immediate",
  "released_at": null,
  "visible_to_host": true,
  "created_at": "2026-09-21T10:15:00+00:00",
  "updated_at": "2026-09-21T10:15:00+00:00"
}
  ],
  "links": { "...": "..." },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

No file download URL is included - the app never exposes direct file URLs, even to the Owner's own account; files are only ever streamed through an authenticated download route. visible_to_host tells you whether the Host can currently see this attachment given its release_rule (immediate, after_confirmation, or checklist_triggered), so you can replicate that gating without re-implementing the rule yourself.

GET /parties/{id}/checklists

Lists checklists assigned to a party, each with its items in section/sort order. Requires checklist:read. Another Owner's party returns 404.

QueryNotes
per_page1–100, default 25
pagepage number, default 1
{
  "data": [
{
  "id": "7c1e...",
  "name": "Essentials",
  "allow_host_items": true,
  "allow_host_notes": true,
  "allow_host_complete_owner_items": false,
  "items": [
    {
      "id": "9a2f...",
      "section_title": "Two weeks before",
      "title": "Order the cake",
      "description": null,
      "responsibility": "booker",
      "visibility": "booker",
      "due": { "offset": 14, "unit": "days", "direction": "before" },
      "link_url": null,
      "completed": false,
      "completed_at": null,
      "completed_by": null,
      "notes": null,
      "is_booker_added": false
    }
  ],
  "assigned_at": "2026-09-21T10:15:00+00:00",
  "created_at": "2026-09-21T10:15:00+00:00",
  "updated_at": "2026-09-21T10:15:00+00:00"
}
  ],
  "links": { "...": "..." },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

responsibility is the raw value (owner, booker or either), not a display name - the app UI shows the owner's business name or the Host's real name instead of these words, but that's a presentation choice; resolve it yourself against the party's own booker_name if you need a display label. completed_by is owner, booker, or null if not yet completed. Read-only - items can't be created or ticked via the API yet.

Errors

Every error is JSON, whatever Accept header you send.

StatusWhen
401Missing, invalid or revoked key
403Key lacks the scope, API module not enabled, or account suspended
404Party not found, or request sent to a non-platform host
422Validation failed
429Rate limit exceeded
{
  "message": "The party date cannot be in the past.",
  "errors": {
"party_date": ["The party date cannot be in the past."]
  }
}

Rate limits

60 requests a minute per key. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 adds Retry-After (seconds).