Skip to content
Space Invoices Documentation

Entity Invitations

Entity Invitations

Manage entity user invitations - list, accept, cancel, resend.

Endpoints
IntroductionPOST/invitations/acceptGET/entities/invitationsGET/entities/invitations/{id}DELETE/entities/invitations/{id}GET/invitations/previewPOST/entities/invitations/{id}/resend

The Entity Invitation object

object

Attributes

idstring

Invitation ID

emailstring

Invitee email

rolestring

User role on the entity. viewer reads, editor also writes, admin also manages users and settings, staff issues invoices and works only with the invoices they created, and accountant works like editor and also uses the accounting module.

Possible values: "viewer", "editor", "admin", "staff", "accountant"

statusstring

Current status of the invitation

Possible values: "pending", "accepted", "expired"

expires_atstring<date-time>

When the invitation expires

Other attributes
Examplejson
{
  "id": "einv_abc123def456789012345678",
  "entity_id": "ent_abc123def456",
  "email": "newuser@example.com",
  "name": "Alex Carter",
  "role": "editor",
  "status": "pending",
  "invited_by": "user_xyz789",
  "expires_at": "2024-01-08T00:00:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

Accept invitation

POST/invitations/accept

Accept an entity invitation by providing user details. Creates or links a white-label user for the invited entity account and grants entity access. Returns an interactive access token, or a restricted two-factor challenge when the user is enrolled or a direct membership policy requires setup. A session_2fa_setup_ token must complete required enrollment; any other session_2fa_ token must complete verification before authenticated requests.

Request

Query parameters

tokenstringrequired

Invitation token from the invitation email

Body parameters

passwordstringrequired

Password for the new user account, or current password for an existing invited user

Other parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityInvitations.acceptEntityInvitation({
  name: "John Doe",
  password: "Securepassword123!"
}, {
  token: "einvt_abc123xyz789"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

messagestring
user_idstring
entity_idstring
json
{
  "user_id": "user_abc123",
  "entity_id": "ent_xyz789",
  "access_token": "token_live_abc123"
}

List entity invitations

GET/entities/invitations

Retrieve all invitations for the current entity, including pending, accepted, and expired.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityInvitations.listEntityInvitations({
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

dataarray of objects
json
{
  "data": [
    {
      "id": "einv_abc123def456789012345678",
      "entity_id": "ent_abc123def456",
      "email": "newuser@example.com",
      "name": "Alex Carter",
      "role": "editor",
      "status": "pending",
      "invited_by": "user_xyz789",
      "expires_at": "2024-01-08T00:00:00.000Z",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Get entity invitation

GET/entities/invitations/{id}

Retrieve details of a specific invitation.

Request

Header parameters

entity_idstringoptional

Optional entity ID specifying which entity context to use for this operation.

Path parameters

idstring<resource-id>required

Space Invoices resource identifier (format: {prefix}_{hex24})

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityInvitations.getEntityInvitation("inv_6595a27b5d35015c3ef0c3fd", {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

idstring

Invitation ID

emailstring

Invitee email

Other parameters
json
{
  "id": "einv_abc123def456789012345678",
  "entity_id": "ent_abc123def456",
  "email": "newuser@example.com",
  "name": "Alex Carter",
  "role": "editor",
  "status": "pending",
  "invited_by": "user_xyz789",
  "expires_at": "2024-01-08T00:00:00.000Z",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

Cancel invitation

DELETE/entities/invitations/{id}

Cancel a pending invitation. Cannot cancel already accepted invitations.

Request

Header parameters

entity_idstringoptional

Optional entity ID specifying which entity context to use for this operation.

Path parameters

idstring<resource-id>required

Space Invoices resource identifier (format: {prefix}_{hex24})

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.entityInvitations.cancelEntityInvitation("inv_6595a27b5d35015c3ef0c3fd", {
  entity_id: "YOUR_ENTITY_ID"
});

console.log('Deleted successfully');
Response

Returns

messagestring
json
{
  "message": "Invitation cancelled"
}

Preview invitation

GET/invitations/preview

Preview an entity invitation by token before accepting it.

Request

Query parameters

tokenstringrequired

Invitation token from the invitation email

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityInvitations.preview({
  token: "einvt_abc123xyz789"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

emailstring<email>
entity_namestring
existing_userboolean
expires_atstring<date-time>
json
{
  "email": "user@example.com",
  "entity_name": "entity-name",
  "existing_user": true,
  "role": "editor",
  "status": "pending",
  "expires_at": "2025-01-15T10:30:00.000Z"
}

Resend invitation

POST/entities/invitations/{id}/resend

Resend an invitation email with a new token and extended expiry.

Request

Header parameters

entity_idstringoptional

Optional entity ID specifying which entity context to use for this operation.

Path parameters

idstring<resource-id>required

Space Invoices resource identifier (format: {prefix}_{hex24})

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.entityInvitations.resendEntityInvitation("inv_6595a27b5d35015c3ef0c3fd", {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

messagestring
expires_atstring<date-time>
json
{
  "message": "Invitation resent"
}