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

Did this answer your question?