Endpoints
POST /invitations
—send an invitation to a user to join your teamGET /invitations
—list pending invitationsGET /invitations/{invitationId}
—get details of a pending invitation by invitation idDELETE /invitations/{invitationId}
—delete a pending invitation by invitation id
Invitation Objects
id
(string) - the unique identifier of the invitationemail
(string) - the invitee's email addressrole
(string) - the invitee's role (one oflearner
,author
,reporter
, oradmin
)firstName
(string) - the invitee's first namelastName
(string) - the invitee's last namegroups
(list of strings) - a list of group names the invitee should be assigned toreportingGroups
(list of strings) - a list of group names the invitee should be allowed to report on (only present whenrole
isreporter
)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 inviterole
(string, required) - role of user to invite (one oflearner
,author
,reporter
, oradmin
)firstName
(string, optional) - first name of user to invitelastName
(string, optional) - last name of user to invitegroups
(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 whenrole
is set toreporter
)
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 haverole
set toreporter
in order to setreportingGroups
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