API reference

Method	Path	Summary
GET	…/me	Get the authenticated user profile
PATCH	…/me	Update the authenticated user profile
GET	…/me/permissions	Get the permissions granted to the authenticated user

Paths start with /users. GET endpoints need users:read, the others users:write.

The User object

firestoreIdstringrequired

ID of the user.

firstNamestring

lastNamestring

displayNamestring

emailstringemailrequired

statusstringrequired

Status of the user account.

registered
The user has signed up.

phonestring

Show all 15 fields

birthdatestring

positionstring

Position of the user in the company.

ceo
Chief executive officer.
cfo
Chief financial officer.
otherCLevel
Another C-level executive.
businessAdministrative
Business or administrative staff.
accountant
Accountant.
other
Another position.

photoUrlstringuri

localestring

creationobjectrequired

When and by whom the resource was created.

Show 2 child fields

creationDateTimestringdate-timerequired

Date and time when the resource was created.

createdBystring

ID of the user who created the resource, when recorded.

activationobjectrequired

Whether the resource is enabled, and when and by whom it was last enabled or disabled.

Show 3 child fields

enabledbooleanrequired

Whether the resource is enabled.

updateDateTimestringdate-timerequired

Date and time when enabled was last set.

updatedBystring

ID of the user who last set enabled, when recorded.

notificationsobject

Show 2 child fields

defaultsRecord<string, object>

Show 2 child fields

emailbooleanrequired

pushbooleanrequired

workspacesRecord<string, object>

Show 2 child fields

modestringrequired

How the user receives the notifications of the workspace.

default
The workspace follows the default notification settings of the user.
custom
The workspace follows its own notification settings, in custom.
muted
The user receives no notification for the workspace.

customRecord<string, object>

Show 2 child fields

emailbooleanrequired

pushbooleanrequired

relationshipsobjectrequired

Show 1 child field

lastAcceptedAgreementsRecord<string, object>required

Show 5 child fields

firestoreIdstringrequired

ID of the agreement.

userIdstringrequired

ID of the user.

acceptanceDateTimestringdate-timerequired

revisionnumberrequired

typestringrequired

Legal document of Sway that the user accepts.

termsAndConditions
Terms and conditions of Sway.
privacyPolicy
Privacy policy of Sway.
cookiePolicy
Cookie policy of Sway.

The User object

{
  "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
  "firstName": "string",
  "lastName": "string",
  "displayName": "string",
  "email": "anna.meier@example.com",
  "status": "registered",
  "phone": "+41791234567",
  "birthdate": "1990-05-14",
  "position": "ceo",
  "photoUrl": "https://example.com",
  "locale": "string",
  "creation": {
    "creationDateTime": "2026-03-02T09:15:00.000Z",
    "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
  },
  "activation": {
    "enabled": true,
    "updateDateTime": "2026-03-02T09:15:00.000Z",
    "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
  },
  "notifications": {
    "defaults": {
      "key": {
        "email": true,
        "push": true
      }
    },
    "workspaces": {
      "Wk7fQ2xR9bLm4tZp8sNv": {
        "mode": "default",
        "custom": {
          "key": {
            "email": true,
            "push": true
          }
        }
      }
    }
  },
  "relationships": {
    "lastAcceptedAgreements": {
      "key": {
        "firestoreId": "Ag4kR8tN2wQx6zLp3vMb",
        "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
        "acceptanceDateTime": "2026-03-02T09:30:00.000Z",
        "revision": 0,
        "type": "termsAndConditions"
      }
    }
  }
}

GET/users/me

Get the authenticated user profile

Scopeusers:read

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

dataUserrequired

curl 'https://api.business.swayapp.io/v1/users/me' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/users/me', {
  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/users/me",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "firstName": "string",
    "lastName": "string",
    "displayName": "string",
    "email": "anna.meier@example.com",
    "status": "registered",
    "phone": "+41791234567",
    "birthdate": "1990-05-14",
    "position": "ceo",
    "photoUrl": "https://example.com",
    "locale": "string",
    "creation": {
      "creationDateTime": "2026-03-02T09:15:00.000Z",
      "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "activation": {
      "enabled": true,
      "updateDateTime": "2026-03-02T09:15:00.000Z",
      "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "notifications": {…},
    "relationships": {…}
  }
}

{
  "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": "internal",
    "message": "An internal error occurred"
  }
}

PATCH/users/me

Update the authenticated user profile

Scopeusers:write

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

firstNamestring

lastNamestring

positionstring

Position of the user in the company.

ceo
Chief executive officer.
cfo
Chief financial officer.
otherCLevel
Another C-level executive.
businessAdministrative
Business or administrative staff.
accountant
Accountant.
other
Another position.

birthdatestring

phonestring

localestring

Returns

200

Successful response

dataUserrequired

curl -X PATCH 'https://api.business.swayapp.io/v1/users/me' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "position": "ceo",
  "birthdate": "1990-05-14",
  "phone": "+41791234567"
}'

const response = await fetch('https://api.business.swayapp.io/v1/users/me', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "position": "ceo",
    "birthdate": "1990-05-14",
    "phone": "+41791234567"
  }),
});
console.log(await response.json());

import os

import requests

response = requests.patch(
    "https://api.business.swayapp.io/v1/users/me",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
    json={
        "position": "ceo",
        "birthdate": "1990-05-14",
        "phone": "+41791234567",
    },
)
print(response.json())

{
  "data": {
    "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "firstName": "string",
    "lastName": "string",
    "displayName": "string",
    "email": "anna.meier@example.com",
    "status": "registered",
    "phone": "+41791234567",
    "birthdate": "1990-05-14",
    "position": "ceo",
    "photoUrl": "https://example.com",
    "locale": "string",
    "creation": {
      "creationDateTime": "2026-03-02T09:15:00.000Z",
      "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "activation": {
      "enabled": true,
      "updateDateTime": "2026-03-02T09:15:00.000Z",
      "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "notifications": {…},
    "relationships": {…}
  }
}

{
  "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": "internal",
    "message": "An internal error occurred"
  }
}

GET/users/me/permissions

Get the permissions granted to the authenticated user

Scopeusers:read

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

dataUserPermissionsrequired

Show 3 child fields

vintegerrequired

wsRecord<string, string[]>required

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.

baRecord<string, string[]>required

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.

curl 'https://api.business.swayapp.io/v1/users/me/permissions' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/users/me/permissions', {
  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/users/me/permissions",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "v": 0,
    "ws": {
      "key": [
        "ws.owner"
      ]
    },
    "ba": {
      "key": [
        "ws.owner"
      ]
    }
  }
}

{
  "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": "internal",
    "message": "An internal error occurred"
  }
}

Users

The User object

Get the authenticated user profile

Query parameters

Returns

Update the authenticated user profile

Query parameters

Request body

Returns

Get the permissions granted to the authenticated user

Query parameters

Returns

Start building on your own data.

Cookies, with your consent

Users

The User object

Get the authenticated user profile

Query parameters

Returns

Update the authenticated user profile

Query parameters

Request body

Returns

Get the permissions granted to the authenticated user

Query parameters

Returns

Start building on your own data.