Browse Articles

Browse Articles

Reach 360: Invitations API

Article Last Updated

This article applies to:

Reach 360

What This API Endpoint Does

With the Invitations API, you create and delete invites to Reach 360. 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
  • 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
  • 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
  • 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.

Example Response

{ 
 "invitation": { 
   "id": "example-invitation-id", 
   "email": "foo@example.com", 
   "firstName": "Example First Name", 
   "lastName": "Example Last Name", 
   "groups": ["example group a", "exaple group b"] 
 } 
}

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.

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", 
    "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", 
  "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