Organization Units - SANNOS Partner API

Every organization unit of a client company has a type, identified by its code. Each company has the built-in type business_entity, and the company can define its own types. A type code never changes; you pass it as type wherever these routes take a type. Endpoints (all Company Key):

GET /v2/organization-unit-types — list the unit types of the company
POST /v2/organization-units — create a unit of any type
GET /v2/organization-units — list units, optionally of one type
GET /v2/organization-units/{organizationUnitId} — get one unit
PATCH /v2/organization-units/{organizationUnitId} — rename a unit or move it to another type

List unit types:
  Partner ──GET /v2/organization-unit-types──> API
         <── 200 OK { types: [ { code, name, isBuiltIn, isArchived } ] }

Create unit:
  Partner ──POST /v2/organization-units { type, name }──> API
         <── 200 OK { id, name, type, companyId }

List units / get one unit:
  Partner ──GET /v2/organization-units?type={code}──> API
         <── 200 OK { organizationUnits: [ { id, name, type, ... } ] }
  Partner ──GET /v2/organization-units/{organizationUnitId}?type={code}──> API
         <── 200 OK { id, name, type, ..., updatedAt }   or   404

Rename or change type:
  Partner ──PATCH /v2/organization-units/{organizationUnitId} { name, type }──> API
         <── 200 OK { updated unit }

Submit documents to the unit:
  Partner ──POST /v2/documents/submit (organizationUnitId)──> API
         <── 200 OK { documentId, complianceReviewId, status: "Pending", ... }

Unit types

GET /v2/organization-unit-types lists every type of the company, archived types included: the built-in type first, then the other types by name.

{
  "types": [
    { "code": "business_entity", "name": "Business Entity", "isBuiltIn": true, "isArchived": false },
    { "code": "department", "name": "Department", "isBuiltIn": false, "isArchived": false }
  ]
}

Field	Description
`code`	Type code. Never changes; send it as `type`
`name`	Display name as the company set it. The API does not translate names. The built-in type is called `Business Entity` until the company renames it
`isBuiltIn`	`true` only for the built-in `business_entity` type
`isArchived`	An archived type can still be read and used as a list filter, but no unit can be created in it or moved to it

Create a unit

POST /v2/organization-units with a JSON body:

Field	Type	Required	Description
`type`	string	Yes	Code of a type that exists and is not archived
`name`	string	Yes	At most 255 characters; unique within the type in the company (case-insensitive)

The unit is created at the top of the organization (this route takes no parentId).
Units created through the Partner API are approved straight away.
Response: id, name, type, companyId.

List and read units

GET /v2/organization-units lists the units of the company, newest first. The optional type query parameter keeps only units of that type; an archived type is accepted as a filter.
GET /v2/organization-units/{organizationUnitId} returns one unit of any type, with updatedAt. The optional type query parameter is an assertion: if the unit has another type, the answer is 404.
Each unit carries id, name, type, companyId, parentId, isArchived, isApproved and createdAt.

Update a unit

PATCH /v2/organization-units/{organizationUnitId} with name, type, or both:

name — new display name, at most 255 characters, unique within the target type (case-insensitive). The name is stored exactly as sent, including characters such as $.
type — move the unit to another type that is not archived.
The optional type query parameter asserts the unit’s current type, as on the read route.
A unit that is archived cannot be updated.
The response is the updated unit, with updatedAt.

Unit attributes

The Partner API neither sets nor returns unit attributes. An attributes field in a create or update body is ignored, and no unit response carries attributes. Required attributes of a type are not checked on these routes: a unit created here has no attribute values, and an update leaves the stored values as they are.

Errors

The organization unit routes answer 404 when the unit is not found.

Status	When	Body
`400`	`organizationUnitId` is not a ULID	`"Invalid Organization Unit ID"`
`404`	No active unit with this ID in your company, a unit of another company, or a unit of another type than the `type` query parameter	`genericErrors`: `Organization unit not found or access denied`
`422`	Unknown `type` (body or query)	`validationErrors.type`: `Unknown organization unit type`
`422`	Archived `type` on create or on a move	`validationErrors.type`: `Organization unit type is archived`
`422`	Blank, too long or duplicate `name`	`validationErrors.name`: `Organization unit name is required`, `Organization unit name cannot exceed 255 characters`, or `Organization unit name already exists`
`422`	`PATCH` without `name` and without `type`	`genericErrors`: `At least one of name or type is required`
`422`	`PATCH` of an archived unit	`genericErrors`: `Organization unit is archived`

Business entities

A business entity is an organization unit of the built-in business_entity type:

List them with GET /v2/organization-units?type=business_entity.
Create one with POST /v2/organization-units and "type": "business_entity".
The organizationUnitId returned by onboarding is the company’s default business_entity unit.
A unit moved to another type no longer appears in the type=business_entity list.

The v1 business entity routes are deprecated and have no v2 twin; see Migrating to v2.

Submit documents to any unit

Use the /v2 document routes with organizationUnitId; they accept an active, unarchived unit of any type of your company:

POST /v2/documents/submit — see Document Submission. A unit that is not found, is archived or belongs to another company is answered with 422 and genericErrors: Organization unit not found or access denied (not 404).
POST /v2/documents/upload/start — see Chunked Upload. complianceFrameworkId and controlId are still required with organizationUnitId. The unit is not checked at start; it is resolved when the last chunk arrives. If it cannot be resolved then, the last chunk answers 404 and the session becomes Failed.

The v1 submit and upload start routes are deprecated; see Migrating to v2.

​Unit types

​Create a unit

​List and read units

​Update a unit

​Unit attributes

​Errors

​Business entities

​Submit documents to any unit