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"],
"ownerContact": {
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@acme.com",
"phone": "+14155550123"
}
}Field | Required | Notes |
| yes | Display name |
| no | Your identifier, unique per account; up to 191 characters and may not itself start with |
| yes |
|
| 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. |
| no | Region codes the organization has purchased policy coverage for (see |
| yes | The organization's first admin. They receive an activation email from AirMason to set their password. |
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
GETorPATCHthe 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",
"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",
"industry": "Consulting",
"slug": "acme",
"iconUrl": "https://cdn.acme.com/logo.png",
"aiCompanionEnabled": true,
"portal": {
"headerTitle": "Acme Employee Hub",
"loginButtonLabel": "Sign in with Acme",
"welcomeMessage": "Welcome to the Acme handbook portal."
}
}Field | Notes |
| Lowercase letters, digits, hyphens and underscores; max 50 characters; no leading or trailing hyphen; must be unique across AirMason |
| Publicly fetchable |
| Enables the AI Companion editor tools for this org's admins |
| Employee portal customization. Exactly three fields are supported: |
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: