API reference | Invitations

Method	Path	Summary
GET	…/invitations	List workspace invitations
POST	…/invitations	Create and send a workspace invitation
DELETE	…/invitations/{invitationId}	Delete (cancel) a pending invitation
GET	…/invitations/{invitationId}	Get detailed information about an invitation
POST	…/invitations/{invitationId}/resend	Resend a pending invitation email
POST	…/invitations/{invitationId}/consume	Consume an invitation to join the workspace

Paths start with /workspaces/{workspaceId}. GET endpoints need invitations:read, the others invitations:write.

The Invitation object

firestoreIdstringrequired

ID of the invitation.

workspaceIdstringrequired

ID of the workspace.

inviterIdstringrequired

ID of the user.

statusstringrequired

Status of the invitation.

pending
The invitation waits for the invited person to accept it.
consumed
The invited person accepted the invitation and became a member of the workspace.

rolestringrequired

Role of the user, which sets its permissions in a workspace (ws.) or a billing account (ba.).

ws.owner
Owner of the workspace, with every permission, including deleting the workspace and managing owners.
ws.admin
Administrator of the workspace, with every permission except managing owners and deleting the workspace or its files.
ws.member
Member of the workspace, who works on its transactions, invoices, payments and accounting but manages neither its bank accounts nor its members.
ws.viewer
Viewer of the workspace, a role that grants no permission.
ws.support
Sway support access, granted when you invite the Sway bot.
ba.owner
Owner of the billing account, with every permission, including deleting it.
ba.admin
Administrator of the billing account, who reads and updates it but cannot delete it.
ba.member
Member of the billing account, who can only read it.

emailstringemailrequired

expirationDateTimestringdate-time

The Invitation object

{
  "firestoreId": "In8rD4sF7jPw2yKm6tQb",
  "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
  "inviterId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
  "status": "pending",
  "role": "ws.owner",
  "email": "anna.meier@example.com",
  "expirationDateTime": "2026-03-02T09:30:00.000Z"
}

GET/workspaces/{workspaceId}/invitations

List workspace invitations

Scopeinvitations:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

limitinteger

Maximum number of items to return, from 1 to 100. A missing, invalid or non-positive value falls back to 20, and a larger value to 100.

Default20

startAfterstring

Cursor of the page to return: the nextCursor of the previous page.

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

idsstring[]

Comma-separated IDs of the items to return, up to 30. When set, limit, startAfter and the filters are ignored.

Returns

200

List of items

dataInvitation[]required

Items of the page, in list order.

limitintegerrequired

Page size of the request, or the number of requested ids.

nextCursorstring

Cursor of the next page, to pass as startAfter. Absent when the page holds fewer items than limit; a full last page still has one, and the page it points to is empty.

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": [
    {
      "firestoreId": "In8rD4sF7jPw2yKm6tQb",
      "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
      "inviterId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
      "status": "pending",
      "role": "ws.owner",
      "email": "anna.meier@example.com",
      "expirationDateTime": "2026-03-02T09:30:00.000Z"
    }
  ],
  "limit": 20
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

POST/workspaces/{workspaceId}/invitations

Create and send a workspace invitation

Scopeinvitations:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

emailstringrequired

rolestringrequired

Valuesws.ownerws.adminws.memberws.viewerba.ownerba.adminba.member

Returns

200

Successful response

dataInvitationrequired

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "anna.meier@example.com",
  "role": "ws.owner"
}'

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "anna.meier@example.com",
    "role": "ws.owner"
  }),
});
console.log(await response.json());

import os

import requests

response = requests.post(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
    json={
        "email": "anna.meier@example.com",
        "role": "ws.owner",
    },
)
print(response.json())

{
  "data": {
    "firestoreId": "In8rD4sF7jPw2yKm6tQb",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "inviterId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "status": "pending",
    "role": "ws.owner",
    "email": "anna.meier@example.com",
    "expirationDateTime": "2026-03-02T09:30:00.000Z"
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

DELETE/workspaces/{workspaceId}/invitations/{invitationId}

Delete (cancel) a pending invitation

Scopeinvitations:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invitationIdstringrequired

ID of the invitation.

Returns

204

No content

curl -X DELETE 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(response.status);

import os

import requests

response = requests.delete(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.status_code)

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

GET/workspaces/{workspaceId}/invitations/{invitationId}

Get detailed information about an invitation

Scopeinvitations:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

invitationIdstringrequired

ID of the invitation.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

emailstringrequired

Returns

200

Successful response

dataDetailedInvitationrequired

Show 8 child fields

firestoreIdstringrequired

ID of the invitation.

workspaceIdstringrequired

ID of the workspace.

inviterIdstringrequired

ID of the user.

statusstringrequired

Status of the invitation.

pending
The invitation waits for the invited person to accept it.
consumed
The invited person accepted the invitation and became a member of the workspace.

rolestringrequired

Role of the user, which sets its permissions in a workspace (ws.) or a billing account (ba.).

ws.owner
Owner of the workspace, with every permission, including deleting the workspace and managing owners.
ws.admin
Administrator of the workspace, with every permission except managing owners and deleting the workspace or its files.
ws.member
Member of the workspace, who works on its transactions, invoices, payments and accounting but manages neither its bank accounts nor its members.
ws.viewer
Viewer of the workspace, a role that grants no permission.
ws.support
Sway support access, granted when you invite the Sway bot.
ba.owner
Owner of the billing account, with every permission, including deleting it.
ba.admin
Administrator of the billing account, who reads and updates it but cannot delete it.
ba.member
Member of the billing account, who can only read it.

emailstringemailrequired

expirationDateTimestringdate-time

detailsobjectrequired

Show 3 child fields

inviterNamestringrequired

workspaceNamestringrequired

workspacePhotoUrlstringuri

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb?email=anna.meier%40example.com' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb?email=anna.meier%40example.com', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb?email=anna.meier%40example.com",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "firestoreId": "In8rD4sF7jPw2yKm6tQb",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "inviterId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "status": "pending",
    "role": "ws.owner",
    "email": "anna.meier@example.com",
    "expirationDateTime": "2026-03-02T09:30:00.000Z",
    "details": {
      "inviterName": "string",
      "workspaceName": "string",
      "workspacePhotoUrl": "https://example.com"
    }
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

POST/workspaces/{workspaceId}/invitations/{invitationId}/resend

Resend a pending invitation email

Scopeinvitations:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invitationIdstringrequired

ID of the invitation.

Returns

204

No content

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/resend' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/resend', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(response.status);

import os

import requests

response = requests.post(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/resend",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.status_code)

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

POST/workspaces/{workspaceId}/invitations/{invitationId}/consume

Consume an invitation to join the workspace

Scopeinvitations:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invitationIdstringrequired

ID of the invitation.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Returns

200

Successful response

dataMembershiprequired

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/consume' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/consume', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.post(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invitations/In8rD4sF7jPw2yKm6tQb/consume",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "displayName": "string",
    "email": "anna.meier@example.com",
    "photoUrl": "https://example.com",
    "role": "ws.owner",
    "activation": {
      "enabled": true,
      "updateDateTime": "2026-03-02T09:15:00.000Z",
      "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    }
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

Cookies, with your consent

Invitations

The Invitation object

List workspace invitations

Path parameters

Query parameters

Returns

Create and send a workspace invitation

Path parameters

Query parameters

Request body

Returns

Delete (cancel) a pending invitation

Path parameters

Returns

Get detailed information about an invitation

Path parameters

Query parameters

Returns

Resend a pending invitation email

Path parameters

Returns

Consume an invitation to join the workspace

Path parameters

Query parameters

Returns

Start building on your own data.