Organizations

An organization is the firm or the business that holds an account. It owns the client companies, the documents, the billing, and the members. Every organization-scoped route acts inside exactly one of them. See Authentication.

The route prefix is singular for everything inside your own organization, /v1/organization, and plural only for the two routes that work across organizations, /v1/organizations. That is not a naming accident. There is no /v1/organizations/{id}, because which organization a request acts in is decided by the credential and the X-Organization-Id header before a handler runs, never by an id in the path.

For client companies, see Profiles. For members, see Team, roles, and invitations.

Routes

GET /v1/organizations

The organizations this person can act in, with the role they hold in each. Answers a plain array, not a paged envelope.

This is the route a web client calls first, to fill the organization switcher. An API key answers with the one organization it belongs to.

package:

GET /v1/organizations HTTP/1.1
Host: api.syllevo.com
Authorization: Bearer <session token>

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example Contabil SRL",
    "kind": 0,
    "locale": "ro",
    "role": 2,
    "joinedAt": "2026-01-15T09:00:00Z",
    "memberCount": 4,
    "visibleProfileCount": 25,
    "hasConnectedSource": true,
    "package": {
      "state": 1,
      "lookupKey": "firm_25_monthly",
      "includedProfiles": 25,
      "productAccess": true
    },
    "avatarUrl": null,
    "avatarThumbnailUrl": null
  }
]

POST /v1/organizations

Creates an organization and makes the caller its owner. Session tokens only in practice: an API key already belongs to an organization, and a new one would have no key.

Answers 201 with the same shape GET /v1/organizations returns for one row.

If the caller already has an organization sitting unpaid, this answers 409 with provisioning_unpaid_organization_exists. Pay for that one or delete it first.

kind decides the wording of every email Syllevo sends on the organization's behalf, so a business that files its own documents does not get copy written for an accounting firm. It is not a permission boundary.

GET /v1/organization

The organization the request resolved to: id, name, locale, avatarUrl, and avatarThumbnailUrl. Nothing else. The counts are on /v1/organization/stats and the package is on /v1/organizations.

PUT /v1/organization

Renames the organization and sets the language it works in. Admin.

This is a full replace, not a patch. Answers the updated organization.

The locale decides the language of reminder emails, digests, and invitations sent from this organization, so changing it changes what clients receive.

POST and DELETE /v1/organization/avatar

Sets or removes the organization's logo. Admin.

The upload is multipart/form-data with one part named file.

• At most 5 MB. Over that is 413.
• The stored image is converted to WebP at 256 px, with a 64 px thumbnail.
• The links in the response are short lived and are regenerated on every read, so store the route, not the URL.

POST /v1/organization/avatar HTTP/1.1
Host: api.syllevo.com
X-Api-Key: syl_live_examplekeynotreal000000000000
Content-Type: multipart/form-data; boundary=----example

------example
Content-Disposition: form-data; name="file"; filename="logo.png"
Content-Type: image/png

<bytes>
------example--

Both answer 200 with the organization. The delete is idempotent: removing a logo that is already gone answers 200, not 404.

GET and PUT /v1/organization/settings

The organization's two security toggles. Admin reads and writes, but only an Owner can change enforceTwoFactor.

The PUT takes enforceTwoFactor and mcpEnabled and replaces both. Sending only one field sets the other to false.

mcpEnabled is one of four conditions the MCP surface needs. Turning it on here does not open MCP on its own.

GET /v1/organization/stats

Five counts for the organization, across every client the caller can see.

GET /v1/organization/trend

Invoices and documents that arrived per day, one point per day with no gaps. A day with nothing still appears, with zeros, so you can chart it without filling holes yourself.

• Omit both for the last 30 days.
• Omit from for the 30 days ending at to.
• Omit to for everything from from up to today.
• A backwards range is 400. A range longer than 366 days is 400.

GET /v1/organization/trend?from=2026-09-01&to=2026-09-03 HTTP/1.1
Host: api.syllevo.com
X-Api-Key: syl_live_examplekeynotreal000000000000

{
  "from": "2026-09-01",
  "to": "2026-09-03",
  "points": [
    { "date": "2026-09-01", "documents": 12, "invoices": 9 },
    { "date": "2026-09-02", "documents": 0, "invoices": 0 },
    { "date": "2026-09-03", "documents": 4, "invoices": 4 }
  ]
}

GET and PUT /v1/setup-checklist-preferences

Which setup suggestions the caller has dismissed in this organization, so a card waved away on a laptop stays away on a phone. Per person, not per organization: two members of the same firm each have their own list.

The PUT replaces the whole list. Sending {"skippedItems": []} brings every suggestion back. An unknown key is refused with 400, and the response names it by its position in the array.

This is a convenience for a user interface. If you are writing a server integration, you can ignore it.