Workspace SettingsUser Invitations

User Invitations

Retrieve a Single Open Workspace Invitation by ID #

Method
GET
Endpoint
Sample Object

Retrieves a single open workspace invitation by its ID.

Parameters
Name Type Required? Description Details
id Number Yes
The invitation ID from the open invitation list, Info response or creation receipt.
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
$include_record_revision Boolean No
Set to true to include record_revision. Use that value as expected_revision when revoking or re-sending this invitation.
Default: false.
$ignore_params_with_empty_values Boolean No
Set to true to ignore optional blank values and JSON nulls. Required values still must be supplied; the text null is not ignored.

Good to know

Retrieves one open invitation, including its intended role, permissions and content restrictions. These are the invitation's saved settings; they do not change an existing workspace member's permissions.

Saved invitation settings

Admin invitations have no effective permission denials or content restrictions.

send_invitation_email shows the choice made when the invitation was created through the API. It is null for invitations sent from the web app (true after the API re-sent one whose inviter had left the workspace). It doesn't confirm that the email was delivered.

A revoked, used, missing or other workspace's invitation returns HTTP 404. invited_by is the person who sent the invitation, as a User Lite object. For invitations created through the API it is the ExhibitDay API object (no id or email), as it is for a web app invitation the API re-sent after its inviter left the workspace. It is null when the person who sent the invitation is no longer an active member of this workspace. Email links, verification codes and proof tokens are never returned.

Checking before revocation or Resend

Include $include_record_revision=true, then send the returned record_revision as expected_revision to DELETE on the invitation list path, or to POST /v1/workspace_settings/users/invitations/resend. The check covers the recipient, intended access, status and saved notification preference. It grants no permission and is not an email verification link.

Code Samples
curl -X GET "https://api.exhibitday.com/v1/workspace_settings/users/invitations/info?id=12345" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 12345,
  "email": "events-admin@example.invalid",
  "status_id": 1,
  "status": "Pending",
  "workspace_role_id": 1,
  "workspace_role": "Admin",
  "invited_by": {
    "id": null,
    "first_name": "ExhibitDay",
    "last_name": "API",
    "display_name": "ExhibitDay API",
    "email": null,
    "type": null,
    "workspace_role": null,
    "is_active": true
  },
  "invitation_created_timestamp": "2030-01-15T12:00:00",
  "invitation_accepted_timestamp": null,
  "permission_denials": [],
  "content_restrictions": {
    "only_my_events": false,
    "only_my_travel": false,
    "only_my_playbook": false,
    "only_my_activity": false,
    "only_accessible_related_items": false
  },
  "send_invitation_email": false
}
Note: IDs are illustrative; use IDs from your workspace.

Retrieve Open Workspace Invitations #

Method
GET
Endpoint

Retrieves open invitations to your workspace.

Parameters
Name Type Required? Description Details
filter_by_status String No
Select one open status. Leave it out for both. Accepted means the person accepted the invitation but has not yet joined.
Allowed values: pending | accepted
$limit Number No
The most invitations to return, as a positive whole number. Omit it for all remaining matching invitations.
$offset Number No
How many matching invitations to skip: 0 or more. The default is 0.
$result_sort String No
Order invitations by their IDs. Omit for oldest first; request descending order for newest first. Unsupported choices are refused.
Allowed values: id_asc | id_desc
$result_format String No
By default, the response is an object containing list_data and the paging totals (records_found, total_records, has_more). Send array to get just a JSON array of the records, or wrapped_in_array to get the default object inside a one-item array.
Allowed values: array | wrapped_in_array
$ignore_params_with_empty_values Boolean No
Set to true to ignore optional blank values and JSON nulls. Required values still must be supplied; the text null is not ignored.

Good to know

Retrieves pending invitations and invitations accepted by people who have not yet joined your workspace. Invitations already used to join are excluded.

Invitation status

Retrieving invitations sends no email and creates no account or workspace membership. Use Invitation Info to inspect an invitation's intended access.

invited_by is the person who sent the invitation, as a User Lite object. For invitations created through the API it is the ExhibitDay API object (no id or email), as it is for a web app invitation the API re-sent after its inviter left the workspace. It is null when the person who sent the invitation is no longer an active member of this workspace. Verification codes, email links and proof tokens are never returned.

Code Samples
curl -X GET "https://api.exhibitday.com/v1/workspace_settings/users/invitations" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "records_found": 2,
  "total_records": 2,
  "has_more": false,
  "list_type": "workspace_invitation",
  "list_data": [
    {
      "id": 12345,
      "email": "events-admin@example.invalid",
      "status_id": 1,
      "status": "Pending",
      "workspace_role_id": 1,
      "workspace_role": "Admin",
      "invited_by": {
        "id": null,
        "first_name": "ExhibitDay",
        "last_name": "API",
        "display_name": "ExhibitDay API",
        "email": null,
        "type": null,
        "workspace_role": null,
        "is_active": true
      },
      "invitation_created_timestamp": "2030-01-15T12:00:00",
      "invitation_accepted_timestamp": null
    },
    {
      "id": 12346,
      "email": "events-team@example.invalid",
      "status_id": 2,
      "status": "Accepted, not yet joined",
      "workspace_role_id": 2,
      "workspace_role": "Team Member",
      "invited_by": {
        "id": null,
        "first_name": "ExhibitDay",
        "last_name": "API",
        "display_name": "ExhibitDay API",
        "email": null,
        "type": null,
        "workspace_role": null,
        "is_active": true
      },
      "invitation_created_timestamp": "2030-01-15T12:00:00",
      "invitation_accepted_timestamp": "2030-01-16T13:00:00"
    }
  ]
}
Note: IDs are illustrative; use IDs from your workspace.

Invite a User to Your Workspace #

Method
POST
Endpoint

Invites a person to your workspace with the access you choose.

Parameters
Name Type Required? Description Details
email String Yes
The email address of the person to invite.
max length: 254
workspace_role_id Number Yes
Choose the intended workspace role. This choice is required.
Allowed values: 1 (Admin) | 2 (Team Member) | 3 (Guest)
send_invitation_email Boolean No
Whether to email the invitation right away and send the automatic reminder. Default: true. Set it to false to save the invitation without those emails. You can still send it whenever you choose with Resend, through the API or in the web app; that sends the email without changing this preference.
Default: true.
permission_denial_ids JSON object/list No
Team Member or Guest only. A JSON array of the permission IDs to deny. Get the IDs, each role's defaults and the rules from GET /v1/references/permissions_and_content_restrictions. Omit it to use the role's defaults. [] denies nothing the role can choose; a Guest still never gets permissions that the Guest role doesn't offer.
View value format and limits

File uploads use multipart form data. Other structured values use a JSON object or array; form/query values use JSON text.

{
  "type": "array",
  "items": {
    "type": "integer",
    "format": "int32"
  },
  "maxItems": 2147483647,
  "nullable": false,
  "x-maximum-depth": 1,
  "x-empty-create-means-omitted": false,
  "example": [
    1,
    2,
    3
  ]
}
content_restrictions JSON object/list No
Team Member or Guest only. An object with any of only_my_events, only_my_travel, only_my_playbook, only_my_activity and only_accessible_related_items, each true or false. Leave a setting out for false. only_my_events, only_my_travel and only_my_playbook also turn on only_my_activity. only_my_travel and only_my_playbook need view access to Travel or Playbook. GET /v1/references/permissions_and_content_restrictions lists them with their rules.
View value format and limits

File uploads use multipart form data. Other structured values use a JSON object or array; form/query values use JSON text.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "only_my_events": {
      "type": "boolean"
    },
    "only_my_travel": {
      "type": "boolean"
    },
    "only_my_playbook": {
      "type": "boolean"
    },
    "only_my_activity": {
      "type": "boolean"
    },
    "only_accessible_related_items": {
      "type": "boolean"
    }
  },
  "x-member-name-comparison": "ordinal-ignore-case; duplicate case variants are rejected",
  "nullable": false,
  "x-maximum-depth": 1,
  "x-empty-create-means-omitted": false,
  "example": {
    "only_my_events": true
  }
}
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
$ignore_params_with_empty_values Boolean No
Set to true to ignore optional blank values and JSON nulls. Required values still must be supplied; the text null is not ignored.
$request_principal_name String No
Optional attribution label for API history, up to 122 characters. It does not impersonate a user or change the inviter.
Idempotency-Key String No
Optional request header. Reuse the same key and request to replay the original creation result instead of creating another invitation.

Good to know

Invites one person to your workspace and emails them the invitation right away. Set send_invitation_email to false to save the invitation without emailing it. The person joins after they accept the invitation and sign in or create an account; this request doesn't create an account or add them to the workspace.

Choosing access

Choose a role with workspace_role_id. Admins get every permission, so an Admin invitation can't include permission denials or content restrictions; [] and {} (or every setting false) are accepted because they restrict nothing.

For a Team Member or Guest, get the choices from GET /v1/references/permissions_and_content_restrictions. It follows the same rules as the invitation dialog in ExhibitDay for your workspace.

permission_denial_ids: omit it to use the role's defaults, send [] to deny nothing the role can choose, or send a list to deny exactly those permissions. A blank value or null is refused, unless $ignore_params_with_empty_values=true, which treats it as omitted. Leave content_restrictions out for no restrictions.

Some choices depend on others, as in ExhibitDay: denying a permission also denies the permissions that need it, permission 11 (tasks assigned only to self) is allowed whenever permission 10 (tasks for any user) is allowed, and only_my_events, only_my_travel or only_my_playbook also turn on only_my_activity. When this changes your request, the invitation is still created and the X-API-Warnings response header lists each change. A request ExhibitDay wouldn't allow, such as denying a permission your workspace doesn't use, is refused with HTTP 400 and nothing is saved.

Example: a Team Member with the role's defaults who also can't view Event Logs or the Activity Feed: {"email":"jordan@example.invalid","workspace_role_id":2,"permission_denial_ids":[1,2,3,12,19,31,32,35]}. Example: a Guest who sees only their own Travel Reservations: {"email":"jordan@example.invalid","workspace_role_id":3,"content_restrictions":{"only_my_travel":true,"only_my_activity":true}}.

The current workspace plan, available invitation slots, existing active members, open invitations, blocked email rules and workspace email-domain rules are checked before the invitation is saved. If a check fails, no invitation is created.

Email delivery

send_invitation_email defaults to true. false saves the invitation without the invitation email or automatic reminders. You can send the email later with Resend, through the API (POST /v1/workspace_settings/users/invitations/resend) or in the web app. That doesn't change the saved automatic-email preference.

The email is sent right away, as soon as the invitation is saved. If the invitation is saved but its email can't be sent, the request still succeeds and the X-API-Warnings response header says so; use Resend to send it again. A successful response doesn't confirm that the email was delivered. The response never includes the invitation link.

Retrying a request

If you can't tell whether the request succeeded, check the invitation list before you retry. Sending the same Idempotency-Key with the same request returns the original result instead of creating a second invitation.

Code Samples
curl -X POST "https://api.exhibitday.com/v1/workspace_settings/users/invitations" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"email\":\"jordan@example.invalid\",\"workspace_role_id\":2,\"send_invitation_email\":false}"

Example response

{
  "id": 12345,
  "email": "jordan@example.invalid",
  "status_id": 1,
  "status": "Pending",
  "workspace_role_id": 2,
  "workspace_role": "Team Member",
  "invited_by": {
    "id": null,
    "first_name": "ExhibitDay",
    "last_name": "API",
    "display_name": "ExhibitDay API",
    "email": null,
    "type": null,
    "workspace_role": null,
    "is_active": true
  },
  "invitation_created_timestamp": "2030-01-15T12:00:00",
  "invitation_accepted_timestamp": null,
  "permission_denials": [
    {
      "id": 1,
      "name": "Illustrative permission definition"
    },
    {
      "id": 2,
      "name": "Illustrative permission definition"
    },
    {
      "id": 3,
      "name": "Illustrative permission definition"
    },
    {
      "id": 12,
      "name": "Illustrative permission definition"
    },
    {
      "id": 19,
      "name": "Illustrative permission definition"
    },
    {
      "id": 31,
      "name": "Illustrative permission definition"
    },
    {
      "id": 32,
      "name": "Illustrative permission definition"
    }
  ],
  "content_restrictions": {
    "only_my_events": false,
    "only_my_travel": false,
    "only_my_playbook": false,
    "only_my_activity": false,
    "only_accessible_related_items": false
  },
  "send_invitation_email": false,
  "record_revision": "r1:BLrTwWH3s2O3xSAKrlOoZLntkSOm1lCdxXTBpYiSg0g"
}
Note: IDs are illustrative; use IDs from your workspace.

Revoke a Pending Workspace Invitation #

Method
DELETE
Endpoint

Revokes a pending workspace invitation.

Note: Inputs that do not apply to this operation, including the ignore-empty option, are ignored and reported in the X-API-Warnings response header.

Parameters
Name Type Required? Description Details
id Number Yes
The invitation ID from the open invitation list, Info response or creation receipt.
expected_revision String No
The record_revision from this invitation's Info response. Include it to revoke only if its recipient, intended access, status and notification preference still match that read. Omit it to skip this check.
Blank, null, malformed or conflicting copies return HTTP 400. A stale revision returns HTTP 409 and changes nothing. Successful removal returns no new revision because the invitation no longer exists.
$request_principal_name String No
Optional attribution label for API history, up to 122 characters. It does not impersonate a user or change the inviter.

Good to know

Revokes a pending workspace invitation. To revoke an accepted invitation, use Users & Permissions in the web app. This operation does not remove an existing member or change their permissions.

Avoiding a stale revocation

Optionally send the record_revision from the invitation's Info response or creation receipt as expected_revision. If the saved recipient, intended access or notification preference changed, the request returns HTTP 409 and changes nothing. If the invitation has since been accepted, the request returns HTTP 400; if it was used or revoked, it returns HTTP 404.

An invitation that is missing, revoked, already used or belongs to another workspace is unavailable. Successful revocation returns no new revision because the invitation no longer exists. Revocation sends no invitation email.

Retrying a request

If you cannot confirm whether revocation succeeded, retrieve the open invitation list or Invitation Info before retrying. This endpoint does not accept an Idempotency-Key header; a request that sends one is refused with HTTP 400.

Code Samples
curl -X DELETE "https://api.exhibitday.com/v1/workspace_settings/users/invitations?id=12345" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status_code": 200,
  "status": "OK",
  "message": "Invitation revoked.",
  "errors": []
}

Re-send a Workspace Invitation #

Method
POST
Endpoint

Emails an open workspace invitation again.

Parameters
Name Type Required? Description Details
id Number Yes
The invitation ID from the open invitation list, Info response or creation receipt.
expected_revision String No
The record_revision from this invitation's Info response. Include it to re-send the invitation only if its recipient, intended access, status and notification preference still match that read. Omit it to skip this check.
Blank, null, malformed or conflicting copies return HTTP 400. A stale revision returns HTTP 409, and nothing is changed or sent.
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
$ignore_params_with_empty_values Boolean No
Set to true to ignore optional blank values and JSON nulls. Required values still must be supplied; the text null is not ignored.
$request_principal_name String No
Optional attribution label for API history, up to 122 characters. It does not impersonate a user or change the inviter.

Good to know

Emails an open workspace invitation again, the same way Resend works in the web app. Returns the invitation as Invitation Info does, with its record_revision.

Which invitations can be re-sent

As in the web app, you can re-send a pending invitation or one the person accepted but hasn't yet used to join, whether it was created in the web app or through the API. If the invitation is missing, revoked, already used to join or belongs to another workspace, the request returns HTTP 404.

Optionally send the record_revision from the invitation's Info response as expected_revision. If the saved recipient, intended access or notification preference changed since then, the request returns HTTP 409 and nothing is changed or sent.

Email delivery

The email is sent right away. It is the same kind of email the person first got: an invitation sent from the web app gets the web app's invitation email, which names the person who invited them; an invitation created through the API gets the API's invitation email, which names no one.

Like Resend in the web app, it restarts the timing of the automatic reminder. It doesn't change the saved send_invitation_email preference (except as described below); when that is false, no automatic reminder follows.

In the web app, when the person who sent an invitation is no longer an active member of the workspace, whoever re-sends it becomes its inviter. The API follows the same rule: the invitation becomes one sent by the ExhibitDay API, like an invitation created through the API. invited_by then returns the ExhibitDay API object, send_invitation_email returns true and the email names no one.

If the email can't be sent, the request returns HTTP 500, the invitation is put back as it was (unless it changed again in the meantime) and nothing is added to the workspace history; try again later. A successful response doesn't confirm that the email was delivered. The response never includes the invitation link.

Retrying a request

Each successful request sends another email. If you can't tell whether a request succeeded, check the invitation's Info response before you retry. This endpoint does not accept an Idempotency-Key header; a request that sends one is refused with HTTP 400.

Code Samples
curl -X POST "https://api.exhibitday.com/v1/workspace_settings/users/invitations/resend" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"id\":12345}"

Example response

{
  "id": 12345,
  "email": "events-admin@example.invalid",
  "status_id": 1,
  "status": "Pending",
  "workspace_role_id": 1,
  "workspace_role": "Admin",
  "invited_by": {
    "id": null,
    "first_name": "ExhibitDay",
    "last_name": "API",
    "display_name": "ExhibitDay API",
    "email": null,
    "type": null,
    "workspace_role": null,
    "is_active": true
  },
  "invitation_created_timestamp": "2030-01-15T12:00:00",
  "invitation_accepted_timestamp": null,
  "permission_denials": [],
  "content_restrictions": {
    "only_my_events": false,
    "only_my_travel": false,
    "only_my_playbook": false,
    "only_my_activity": false,
    "only_accessible_related_items": false
  },
  "send_invitation_email": false,
  "record_revision": "r1:quAOUxQcrhS5HLeFZNDbOWCfDMNiZWoy8joJJuzxCqE"
}
Note: IDs are illustrative; use IDs from your workspace.