Invitations API

Endpoints

• POST /invitations—send an invitation to a user to join your team
• GET /invitations—list pending invitations
• GET /invitations/{invitationId}—get details of a pending invitation by invitation id
• DELETE /invitations/{invitationId}—delete a pending invitation by invitation id

Invitation Objects

• id (string) - the unique identifier of the invitation
• email (string) - the invitee's email address
• role (string) - the invitee's role (one of learner, author, reporter, or admin)
• firstName (string) - the invitee's first name
• lastName (string) - the invitee's last name
• groups (list of strings) - a list of group names the invitee should be assigned to

Create Invitation

POST /invitations

Parameters

• email (string, required) - email of user to invite
• role (string, required) - role of user to invite (one of learner, author, reporter , or admin)
• firstName (string, optional) - first name of user to invite
• lastName (string, optional) - last name of user to invite
• groups (list of strings, optional) - list of group names to assign invited user to. Any groups that don't exist are created when the user accepts the invitation.

Example Response

{ 
 "invitation": { 
   "id": "example-invitation-id", 
   "email": "foo@example.com", 
   "role": "learner", 
   "firstName": "Example First Name", 
   "lastName": "Example Last Name", 
   "groups": ["example group a", "exaple group b"] 
 } 
}

Endpoint-specific Error Codes

• code: 'user_exists' - cannot create invitation because the specified email address already has an account
• code: 'invite_pending' - cannot create invitation because the specified email address already has an invite pending

List Invitations

GET /invitations

Parameters

• limit (integer, optional) - the maximum number of results to return in a single response (defaults to 50)
• email (string, optional) - if provided, only return invitations for this email address

Example Response

{ 
 "invitations": [ 
   { 
    "id": "example-invitation-id-1", 
    "email": "foo@example.com", 
    "role": "learner", 
    "firstName": "Example First Name 1", 
    "lastName": "Example Last Name 1", 
    "groups": ["example group a", "exaple group b"] 
   }, ... 
 ], 
 "nextUrl": "https://url-for-next-page-of-results" 
}

Retrieve Invitation by ID

GET /invitations/{invitationId}

Example Response

{ 
  "id": "example-invitation-id", 
  "email": "foo@example.com", 
  "role": "learner", 
  "firstName": "Example First Name", 
  "lastName": "Example Last Name", 
  "groups": ["example group a", "exaple group b"] 
}

Endpoint-specific Error Codes

• invitation_not_found - cannot retrieve invitation because the invitation does not exist

Delete Invitations

DELETE /invitations/{invitationId}

Success Response

204 "No Content"

Endpoint-specific Error Codes

• invitation_not_found - cannot retrieve invitation because the invitation does not exist