Overview The Member Invitations API allows users to:
View their pending company invitations
Accept invitations to join a company
Decline invitations they don’t want to accept
Company administrators can also create new member invitations through the Companies API.
Authentication All endpoints require authentication using a Bearer token in the Authorization header.
Get Pending Invitations curl -X GET https://api.example.com/api/invitations \ -H "Authorization: Bearer YOUR_TOKEN"
Retrieves all pending company invitations for the authenticated user.
Endpoint Response Indicates if the request was successful
Array of pending invitation objects Unique identifier for the membership invitation
Company unique identifier
Array of roles that will be assigned upon acceptance ISO 8601 timestamp of when the invitation was created
Response Example { "success" : true , "data" : [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "company" : { "id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Acme Corporation" , "slug" : "acme-corp" , "logo" : "https://example.com/logos/acme.png" }, "roles" : [ { "id" : "789e4567-e89b-12d3-a456-426614174000" , "name" : "Member" , "color" : "#6366F1" } ], "invitedAt" : "2024-01-15T10:30:00.000Z" } ] }
Accept Invitation curl -X POST https://api.example.com/api/invitations/{membershipId}/accept \ -H "Authorization: Bearer YOUR_TOKEN"
Accepts a pending company invitation and activates the membership.
Endpoint POST /api/invitations/{membershipId}/accept
Path Parameters The unique identifier of the membership invitation to accept
Response Indicates if the invitation was successfully accepted
Response Example Error Responses Invitation not found or does not belong to the authenticated user
{ "success" : false , "error" : "Invitation not found" }
Decline Invitation curl -X POST https://api.example.com/api/invitations/{membershipId}/decline \ -H "Authorization: Bearer YOUR_TOKEN"
Declines a pending company invitation and removes it.
Endpoint POST /api/invitations/{membershipId}/decline
Path Parameters The unique identifier of the membership invitation to decline
Response Indicates if the invitation was successfully declined
Response Example Error Responses Invitation not found or does not belong to the authenticated user
{ "success" : false , "error" : "Invitation not found" }
Create Member Invitation (Company Admins) curl -X POST https://api.example.com/api/companies/{companyId}/members/invite \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "userId": "550e8400-e29b-41d4-a716-446655440000", "position": "Software Engineer", "department": "Engineering" }'
Invites a user to join a company. Requires appropriate permissions within the company.
Endpoint POST /api/companies/{companyId}/members/invite
Path Parameters The unique identifier of the company
Request Body UUID of the user to invite. User must exist in the system.
Job position or title for the member (max 100 characters)
Department name (max 100 characters)
Response Indicates if the request was successful
The created membership invitation object Unique identifier for the membership
Company unique identifier
Current status: INVITED, ACTIVE, or SUSPENDED
ISO 8601 timestamp of invitation creation
ISO 8601 timestamp of when invitation was accepted
ISO 8601 timestamp of invitation expiration
Array of assigned roles (typically includes the default company role)
Response Example { "success" : true , "data" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "companyId" : "123e4567-e89b-12d3-a456-426614174000" , "userId" : "987e4567-e89b-12d3-a456-426614174000" , "status" : "INVITED" , "position" : "Software Engineer" , "department" : "Engineering" , "invitedAt" : "2024-01-15T10:30:00.000Z" , "activatedAt" : null , "expiresAt" : null , "user" : { "id" : "987e4567-e89b-12d3-a456-426614174000" , "email" : "[email protected] " , "firstName" : "John" , "lastName" : "Doe" , "avatarUrl" : "https://example.com/avatars/johndoe.png" }, "roles" : [ { "id" : "789e4567-e89b-12d3-a456-426614174000" , "companyId" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Member" , "description" : "Default member role" , "color" : "#6366F1" , "isSystem" : true , "isDefault" : true , "createdAt" : "2024-01-01T00:00:00.000Z" , "updatedAt" : "2024-01-01T00:00:00.000Z" } ] } }
Error Responses { "success" : false , "error" : "User not found" }
User is already a member of this company
{ "success" : false , "error" : "User is already a member of this company" }
Real-time Notifications When a user is invited to a company, they receive a real-time Server-Sent Event (SSE) notification on the invitation:new event channel with the following payload:
{ "id" : "550e8400-e29b-41d4-a716-446655440000" , "company" : { "id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Acme Corporation" , "slug" : "acme-corp" , "logo" : "https://example.com/logos/acme.png" }, "roles" : [ { "id" : "789e4567-e89b-12d3-a456-426614174000" , "name" : "Member" , "color" : "#6366F1" } ], "invitedAt" : "2024-01-15T10:30:00.000Z" }
