What This API Endpoint Does

With the Invitations API, you create and delete invites to your Rise account. Admins see this reflected as users on the Pending tab. Users receive emails when invited. If their pending invitation is deleted prior to them accepting, the email link won't work.

You can also use this API to retrieve a list of all pending invitations or invitation details for a specific user.

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