Documentation Index Fetch the complete documentation index at: https://docs.zyeta.io/llms.txt
Use this file to discover all available pages before exploring further.
The Invitations Service provides endpoints for creating, managing, and responding to organization invitations. It enables organization administrators to invite users to join their organization with specific roles.
Authentication All endpoints require a valid Bearer token in the Authorization header.
Base URL Endpoints Create Invitation Create a new invitation to join an organization.
Request
Python
JavaScript
Response
curl -X POST {{baseUrl}}/api/invitations/create?org_id=your-org-id \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "newuser@example.com", "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l", "message": "Please join our organization!" }'
Endpoint: POST /api/invitations/createQuery Parameters:
Parameter Required Description org_idYes Organization ID
Request Body:
Field Type Required Description emailstring Yes Email address of the person to invite role_idstring Yes Role ID to assign to the user upon acceptance messagestring No Optional personal message to include in the invitation email
Response:
Field Type Description idstring (UUID) Invitation ID emailstring Recipient’s email address statusstring Invitation status (“pending”, “accepted”, “expired”, “revoked”) roleobject Role information organizationobject Organization information tokenstring Invitation token (used in acceptance links) created_atstring (datetime) Creation timestamp expires_atstring (datetime) Expiration timestamp
List Invitations Retrieve all invitations for an organization.
Request
Python
JavaScript
Response
curl -X GET {{baseUrl}}/api/invitations/list?org_id=your-org-id & status = pending \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/invitations/listQuery Parameters:
Parameter Required Description org_idYes Organization ID statusNo Filter by invitation status (pending, accepted, expired, revoked)
Get Invitation Get details about a specific invitation.
Request
Python
JavaScript
Response
curl -X GET {{baseUrl}}/api/invitations/get?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/invitations/getQuery Parameters:
Parameter Required Description invitation_idYes Invitation ID
Validate Invitation Validate an invitation token (used before accepting an invitation).
Request
Python
JavaScript
Response
curl -X GET {{baseUrl}}/api/invitations/validate?token=inv_Ax92jKsLp8YzR4TbMn5VcWq3
Endpoint: GET /api/invitations/validateQuery Parameters:
Parameter Required Description tokenYes Invitation token
Resend Invitation Resend an invitation email.
Request
Python
JavaScript
Response
curl -X POST {{baseUrl}}/api/invitations/resend?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: POST /api/invitations/resendQuery Parameters:
Parameter Required Description invitation_idYes Invitation ID
Revoke Invitation Revoke a pending invitation.
Request
Python
JavaScript
Response
curl -X DELETE {{baseUrl}}/api/invitations/revoke?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/invitations/revokeQuery Parameters:
Parameter Required Description invitation_idYes Invitation ID
Bulk Create Invitations Create multiple invitations at once.
Request
Python
JavaScript
Response
curl -X POST {{baseUrl}}/api/invitations/bulk_create?org_id=your-org-id \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "invitations": [ { "email": "user1@example.com", "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l" }, { "email": "user2@example.com", "role_id": "9d0e1f2g-3h4i-5j6k-7l8m-9n0o1p2q3r4s" } ], "message": "We would like to invite you to join our organization." }'
Endpoint: POST /api/invitations/bulk_createQuery Parameters:
Parameter Required Description org_idYes Organization ID
Request Body:
Field Type Required Description invitationsarray Yes Array of invitation objects (email, role_id) messagestring No Optional message to include in all invitation emails
Accept Invitation (Backend Process) Note: This endpoint is not directly exposed, as invitation acceptance is handled through the authentication service using a token.
The flow for accepting an invitation is:
User receives an invitation email with a link containing the invitation token
User clicks the link, which takes them to a signup page
User completes the signup form and submits it to the /api/auth/signup_invite endpoint
Upon successful account creation, the user is automatically added to the organization with the designated role
Error Responses
Status Code Description 400 Bad Request - Invalid input or validation error 401 Unauthorized - Invalid or missing token 403 Forbidden - Insufficient permissions (only admins can manage invitations) 404 Not Found - Invitation doesn’t exist 409 Conflict - User already exists or is already a member of the organization 410 Gone - Invitation has expired or been revoked 500 Internal Server Error - Server-side error
Implementation Notes
Invitations expire after 7 days by default
When an invitation is resent, its expiration date is extended
Users can only be invited to join an organization if they don’t already have an account or are not already members
Only users with appropriate permissions (Admins and Owners) can create and manage invitations
Invitation tokens are secure, one-time-use tokens that become invalid after acceptance
Email notifications are sent automatically when invitations are created or resent
