Skip to content

Invite people

An invitation adds someone to your organisation, with the roles, groups and attributes you want to give them at once. This page is for administrators: those who hold the administrator or people-administrator rights in the organisation. How the invited person accepts is in Accept an invitation.

Invite someone

  1. Choose the person's e-mail address.
  2. Choose the roles, groups and attribute values the person gets. You can only give what you hold yourself; otherwise OS refuses the invitation (why).
  3. Send the invitation. The invited person gets a link.

The e-mail tells the invitee what comes next: choose a password (for an address with no account yet), sign in, or sign in with the company account. Which one it is, you as an administrator do not see: an invitation always looks the same to you.

The link is valid until the invitation expires (seven days by default). Only the invited person can use it, signed in with exactly that address. A forwarded link gives nobody else access. When the invitation is accepted, OS checks again that you may still give the chosen roles, groups and values; if you lost those rights in the meantime, the invitation is void and you invite again.

Invite many people at once

On the Members page, Import members opens two ways to invite many people in one go. Everyone gets their own invitation by email, and fills in their own name when they accept.

  • Paste a list. Paste one email address per line, plain or after a name the way a mail program copies them ("John Doe" <john@example.com>); the name is not used. Above the list, choose the groups, roles and reach everyone gets. One line without a valid address refuses the whole list.
  • CSV file. A file with an email column and, optionally, groups and roles columns holding the names as shown under Groups and Roles (several separated by a comma), so each person gets their own. Download the example file to see how; save an Excel file as CSV first. The file stays in your browser and is not sent to OS. Up to 500 people per file, 1 MB at most. Lines with a problem (no valid address, an address already on an earlier line, a group or role that does not exist) are skipped; you can download them with the reason, fix them and import them again.

The page sends the invitations 25 at a time. Keep it open until it is done: closing it stops the sending, and anyone who already has an invitation keeps it. Afterwards you see for each person whether the invitation went out and, if not, why: the same reasons as for one invitation, below. Retry the failed ones with one button, and download the result as a CSV.

See and revoke pending invitations

You see the invitations that have not been accepted yet. You revoke a pending invitation, after which its link no longer works. You cannot revoke an accepted invitation: the person is then a member, and you deactivate or remove the member.

Inviting someone again after a removal makes a new membership that starts with nothing.

When OS refuses

  • 403: you are giving a role, group or value you do not hold yourself; the message names it.
  • 409: the invitation would make your organisation, or one below, use more than 32 attributes and labels, or a role with reach descendants would give an organisation below more than 500 rules in the AI features. This can happen when it is sent and when it is accepted. Give less, give the role with reach organisation, or ask your operator.
  • 422: a role, group or attribute that does not exist, or a value the attribute does not allow.

Via the API

  • POST /api/v1/organisations/{id}/invitations with email and, optionally, roles (each {"role": ..., "reach": ...}, see Manage roles), groups (group ids) and attributes (each {"attribute": ..., "value": ...}, see Manage attributes).
  • POST /api/v1/organisations/{id}/invitations/batch with invitations, a list of 1 to 100 invitations of the same shape. The answer gives one result per invitation, in the same order: sent with the invitation, or refused with the reason; a refused one does not hold up the rest. A malformed row (an address longer than 320 characters, more than 32 groups or roles) refuses the whole request with 422 before anything is sent. After a 500 the rows before the one that failed may already be invited; sending them again answers 409, already invited.
  • GET /api/v1/organisations/{id}/invitations lists pending invitations.
  • DELETE /api/v1/organisations/{id}/invitations/{invitation_id} revokes one.