> For the complete documentation index, see [llms.txt](https://movemint.gitbook.io/movemint-developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://movemint.gitbook.io/movemint-developer-docs/open-api-specification/core-resources/invited-participants.md).

# Invited Participants

Invite people to a sub-event by email. Each invite creates a pending record and emails the recipient a personal registration link. Requires the `edit_participant` scope on the event.

## Invite participants to a sub-event

> Creates a pending invitation for each email and sends the recipient a\
> personal registration link. Emails already invited to the sub-event are\
> returned under \`skipped\` (not re-emailed); invalid addresses are returned\
> under \`errors\` (not invited). Returns \`201\` when at least one invitation\
> is created, \`200\` when nothing new was created but at least one email was\
> already invited, and \`422\` when nothing was created or skipped (empty\
> list, over the size cap, or every address invalid).<br>

````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Invited Participants","description":"Invite people to a sub-event by email. Each invite creates a pending\nrecord and emails the recipient a personal registration link. Requires\nthe `edit_participant` scope on the event.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"EventHandle":{"name":"handle","in":"path","required":true,"description":"The unique handle (slug) of the event","schema":{"type":"string"}}},"schemas":{"CreateInvitedParticipantsRequest":{"type":"object","required":["event_variant_id","emails"],"properties":{"event_variant_id":{"type":"integer","format":"int64","description":"The sub-event (event variant) to invite people to."},"emails":{"type":"array","minItems":1,"items":{"type":"string","format":"email"},"description":"Email addresses to invite. Duplicates and blanks are ignored, and\nanyone already invited to the sub-event is skipped rather than\nre-emailed.\n"},"custom_message":{"type":"string","description":"Optional personal note included in the invitation email."}}},"InvitedParticipantsResult":{"type":"object","required":["created","skipped","errors"],"properties":{"created":{"type":"array","description":"Invitations created and emailed this request.","items":{"$ref":"#/components/schemas/InvitedParticipant"}},"skipped":{"type":"array","description":"Emails already invited to this sub-event (not re-emailed).","items":{"type":"string","format":"email"}},"errors":{"type":"array","description":"Per-email failure messages, if any.","items":{"type":"string"}}}},"InvitedParticipant":{"type":"object","required":["confirmation_number","email","event_variant_id","status"],"properties":{"confirmation_number":{"type":"string"},"email":{"type":"string","format":"email"},"event_variant_id":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["pending","claimed","expired"],"description":"A freshly created invitation is always `pending`."}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubEventNotFound":{"description":"Event or sub-event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/events/{handle}/invited_participants":{"post":{"tags":["Invited Participants"],"summary":"Invite participants to a sub-event","operationId":"createInvitedParticipants","description":"Creates a pending invitation for each email and sends the recipient a\npersonal registration link. Emails already invited to the sub-event are\nreturned under `skipped` (not re-emailed); invalid addresses are returned\nunder `errors` (not invited). Returns `201` when at least one invitation\nis created, `200` when nothing new was created but at least one email was\nalready invited, and `422` when nothing was created or skipped (empty\nlist, over the size cap, or every address invalid).\n","parameters":[{"$ref":"#/components/parameters/EventHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitedParticipantsRequest"}}}},"responses":{"200":{"description":"Nothing new created — at least one email was already invited (any\ninvalid addresses appear in `errors`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitedParticipantsResult"}}}},"201":{"description":"At least one invitation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitedParticipantsResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/SubEventNotFound"},"422":{"description":"Nothing was created or skipped — the list was empty, exceeded the\nper-request cap, or every address was invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitedParticipantsResult"}}}}}}}}}
````