Invitations API

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