Create an organization

POST /organizations | Partner API key

Returns 201 with the organization resource.

{
  "name": "Acme Corp",
  "externalId": "acme-eu",
  "orgType": "lite",
  "industry": "Technology-Hardware-Software-Internet",
  "purchasedRegions": ["CA", "NY", "TX"],
  "enforceUniqueEmployees": false,
  "rehireSignatureWindowDays": 30,
  "ownerContact": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "phone": "+14155550123"
  }
}

Field	Required	Notes
`name`	yes	Display name
`externalId`	no	Your identifier, unique per account; up to 191 characters and may not itself start with `ext:`
`orgType`	yes	The organization's tier name: 1–50 characters, lowercase letters, digits, `_` or `-` (the first character a letter or digit). Trimmed and lowercased before it is stored, so `LITE` is stored as `lite`. See Organization tiers below for what the name does.
`industry`	no	Free-text industry label. It is mapped onto AirMason's industry list when it matches; otherwise it is stored as Other with your wording preserved.
`purchasedRegions`	no	Region codes the organization has purchased policy coverage for (see `GET /regions` in the Reference article). Omitting it does not mean "none": the organization is given all 56 US state and territory codes. Pass an explicit list to restrict coverage.
`ownerContact`	yes	The organization's first admin. They receive an activation email from AirMason to set their password.
`enforceUniqueEmployees`	no	Boolean (default `true`). Whether a returning employee gets their terminated record back. See Employee rehire settings.
`rehireSignatureWindowDays`	no	Integer from 0 to 3650, or `null` (default). Only used when `enforceUniqueEmployees` is `false`. See Employee rehire settings.

Creating an organization also attaches AirMason's default admin users and your partner user to it, and sends the owner invite.

List organizations

GET /organizations | Partner API key

Returns all organizations in your account, newest first, paginated.

Deactivate / reactivate an organization

POST /organizations/{orgId}/deactivate | Partner API key

and POST /organizations/{orgId}/reactivate | Partner API key

Both return 200 with the organization resource. A deactivated organization keeps all its data. While it is inactive:

no emails or webhooks are sent, and HRIS, SFTP and SCIM syncs and scheduled report emails are paused;
you can still mint access tokens and GET or PATCH the organization;
employee, group, handbook-assignment and SSO writes return 409 conflict (Organization is deactivated).

Get an organization

GET /organizations/{orgId} | Access token

{
  "id": "1f2a7b3c-9d4e-4f5a-8b6c-0d1e2f3a4b5c",
  "externalId": "acme-eu",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "orgType": "lite",
  "industry": "Technology-Hardware-Software-Internet",
  "isActive": true,
  "employeeCount": 412,
  "purchasedRegions": ["CA", "NY", "TX"],
  "portalUrl": "https://books.airmason.com/acme-corp",
  "enforceUniqueEmployees": true,
  "rehireSignatureWindowDays": null,
  "createdAt": "2026-09-15T13:42:10.000Z"
}

employeeCount counts active (non-terminated) employees. The icon set via iconUrl is not returned by this endpoint.

Update an organization

PATCH /organizations/{orgId} | Access token

All fields optional; only supplied fields change. At least one updatable field is required: an empty body, or portal: {} on its own, returns 400 validation_error.

{
  "name": "Acme Corporation",
  "externalId": "acme-eu-2",
  "orgType": "normal",
  "industry": "Consulting",
  "slug": "acme",
  "iconUrl": "https://cdn.acme.com/logo.png",
  "aiCompanionEnabled": true,
  "enforceUniqueEmployees": false,
  "rehireSignatureWindowDays": 30,
  "portal": {
    "headerTitle": "Acme Employee Hub",
    "loginButtonLabel": "Sign in with Acme",
    "welcomeMessage": "Welcome to the Acme handbook portal."
  }
}

Field	Notes
`orgType`	The organization's tier name, with the same rules as on create: 1–50 characters, lowercase letters, digits, `_` or `-`, trimmed and lowercased before it is stored. Anything else is rejected with `400 validation_error`. Send `null` to remove the tier (untiered). The response carries the stored value, as `GET` does. Changing the tier records an entry in the organization's activity log and sends an `organization.updated` webhook event (see Webhooks).
`slug`	Lowercase letters, digits, hyphens and underscores; max 50 characters; no leading or trailing hyphen; must be unique across AirMason
`iconUrl`	Publicly fetchable `https` URL of a PNG/JPG; we download and host it. The stored icon is write-only and not returned by `GET`.
`aiCompanionEnabled`	Enables the AI Companion editor tools for this org's admins
`portal`	Employee portal customization. Exactly three fields are supported: `headerTitle` (1–50 characters), `loginButtonLabel` (max 100) and `welcomeMessage` (max 100; an empty string clears it).
`enforceUniqueEmployees`	Boolean (default `true`). Whether a returning employee gets their terminated record back. See Employee rehire settings.
`rehireSignatureWindowDays`	Integer from 0 to 3650, or `null` to clear (default `null`). Only used when `enforceUniqueEmployees` is `false`. See Employee rehire settings.

Organization tiers

An organization's tier is a name (orgType) that AirMason resolves to a set of restrictions: document and collaborator caps, locked features, and so on. You set it on create and can change it at any time with PATCH /organizations/{orgId}, for example to move an organization from a self-serve plan to a managed one.

What you send	What happens
A name that is defined for your partner account (for example `lite`)	That tier's restrictions apply.
A name that is not defined for your partner account	No named-tier restrictions are added (fail open). The organization gets exactly what an untiered organization gets: your account's baseline, if one is configured, and nothing more. A typo therefore never locks anything beyond that baseline. If a tier you expect to restrict does not, check the spelling against the names agreed with AirMason.
`null`	The organization is untiered: only your account's baseline applies, if one is configured.

Names are matched exactly after lowercasing, so Lite, LITE and lite are the same tier.

Which names exist and what each one restricts is configured per partner account by AirMason; contact your AirMason representative to add or change a tier. The Partner API does not list them.

A tier change takes effect within a minute. Your own calls are never affected: Partner API credentials are exempt from tier restrictions, so you can always read and change an organization you manage, whatever its tier.

Employee rehire settings

When you create an employee whose employeeId or email belongs to a terminated employee, these two fields decide whether AirMason reuses the old record (same id, history and signatures) or creates a new one.

enforceUniqueEmployees	rehireSignatureWindowDays	Result
`true` (default)	ignored	Reuse the old record
`false`	`null` (default)	Create a new record
`false`	`N` days	Reuse if terminated in the last `N` days, otherwise create a new record

The match is on employeeId or email. Matching on employeeId alone is not supported.
Records that AirMason merged as duplicates are only reused when enforceUniqueEmployees is true.
An active employee with the same employeeId or email still returns 409 conflict.

Update purchased regions

PUT /organizations/{orgId}/purchased-regions | Access token

Replaces the full set of regions the organization has purchased policy coverage for.

{ "regions": ["CA", "NY", "ON"] }

Returns the updated list. Adding a region makes its policies available to the organization's Auto Policy Update engine; removing one stops future updates for that region (existing content is not deleted). Passing [] is accepted and clears every region. Codes must come from GET /regions; today that is US states and territories plus Canadian provinces.

Partner API documentation:

Overview & Getting Started
Organizations
Employees & Groups
Handbooks
Admin SSO & Provisioning
Webhooks
Reference (Errors, Rate Limits, Regions)

Partner API: Organizations