API-Referenz | Invitations

Methode	Pfad	Zusammenfassung
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

Die Pfade beginnen mit /workspaces/{workspaceId}. GET-Endpunkte brauchen invitations:read, die übrigen invitations:write.

Das Objekt Invitation

firestoreIdstringerforderlich

ID of the invitation.

workspaceIdstringerforderlich

ID of the workspace.

inviterIdstringerforderlich

ID of the user.

statusstringerforderlich

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.

rolestringerforderlich

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.

emailstringemailerforderlich

expirationDateTimestringdate-time

Das Objekt Invitation

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

Bereichinvitations:read

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

Abfrageparameter

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.

Standard20

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.

Rückgabe

200

List of items

dataInvitation[]erforderlich

Items of the page, in list order.

limitintegererforderlich

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

Bereichinvitations:write

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

Abfrageparameter

fieldsstring

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

Request-Body

emailstringerforderlich

rolestringerforderlich

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

Rückgabe

200

Successful response

dataInvitationerforderlich

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

Bereichinvitations:write

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

invitationIdstringerforderlich

ID of the invitation.

Rückgabe

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

Bereichinvitations:read

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

invitationIdstringerforderlich

ID of the invitation.

Abfrageparameter

fieldsstring

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

emailstringerforderlich

Rückgabe

200

Successful response

dataDetailedInvitationerforderlich

8 untergeordnete Felder anzeigen

firestoreIdstringerforderlich

ID of the invitation.

workspaceIdstringerforderlich

ID of the workspace.

inviterIdstringerforderlich

ID of the user.

statusstringerforderlich

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.

rolestringerforderlich

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.

emailstringemailerforderlich

expirationDateTimestringdate-time

detailsobjecterforderlich

3 untergeordnete Felder anzeigen

inviterNamestringerforderlich

workspaceNamestringerforderlich

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

Bereichinvitations:write

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

invitationIdstringerforderlich

ID of the invitation.

Rückgabe

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

Bereichinvitations:write

Pfadparameter

workspaceIdstringerforderlich

ID of the workspace.

invitationIdstringerforderlich

ID of the invitation.

Abfrageparameter

fieldsstring

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

Rückgabe

200

Successful response

dataMembershiperforderlich

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, mit Ihrer Einwilligung

Invitations

Das Objekt Invitation

List workspace invitations

Pfadparameter

Abfrageparameter

Rückgabe

Create and send a workspace invitation

Pfadparameter

Abfrageparameter

Request-Body

Rückgabe

Delete (cancel) a pending invitation

Pfadparameter

Rückgabe

Get detailed information about an invitation

Pfadparameter

Abfrageparameter

Rückgabe

Resend a pending invitation email

Pfadparameter

Rückgabe

Consume an invitation to join the workspace

Pfadparameter

Abfrageparameter

Rückgabe

Bauen Sie auf Ihren eigenen Daten.