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
• reportingGroups (list of strings) - a list of group names the invitee should be allowed to report on (only present when role is reporter)
• url (string) - URL to fetch invitation's details from the API

Create Invitation

POST /invitations

Request Parameters (JSON)

• 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.
• reportingGroups (list of strings, optional) - list of group names to assign invited reporter to report on. Any groups that don't exist will get created when the user accepts the invitation. (note: only allowed when role is set to reporter)

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"] 
   "reportingGroups": null
 } 
}

Endpoint-specific Error Codes

• 'user_exists' - cannot create an invitation because the specified email address already has an account
• 'invite_pending' - cannot create an invitation because the specified email address already has an invite pending
• 'max_invites_reached' - cannot create an invitation because you’ve hit your limit for your trial account. Please upgrade your plan or contact support to have this limit increased.
• 'invalid_reporting_groups' - cannot create an invitation because the reporter invitee cannot be assigned to report on the "Everyone" group along with additional groups
• 'invalid_user_role' - cannot create an invitation because the invitee must have role set to reporter in order to set reportingGroups

List Invitations

GET /invitations

Request Parameters (Query String)

• limit (integer, optional) - the maximum number of results to return in a single response (see Pagination); must be between 1 and 100 (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