Skip to main content

Partner API: Organizations

Create, list, update, deactivate and manage the purchased regions of organizations.

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

name

yes

Display name

externalId

no

Your identifier, unique per account

orgType

yes

lite (limited feature set) or normal (full)

industry

no

Free-text industry label

purchasedRegions

no

Region codes the organization has purchased policy coverage for (see appendix)

ownerContact

yes

The organization's first admin. They receive an activation email from AirMason to set their password.

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

A deactivated organization keeps all its data, but employees and admins can no longer sign in and no emails or webhooks are sent.

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.

Update an organization

PATCH /organizations/{orgId} | Access token

All fields optional; only supplied fields change.

{
  "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

slug

Lowercase letters, digits and hyphens; must be unique across AirMason

iconUrl

Publicly fetchable PNG/JPG; we download and host it

aiCompanionEnabled

Enables the AI Companion editor tools for this org's admins

portal

Employee portal customization (header title, login button label, welcome message, fonts)

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", "CA_SF", "NY", "NY_NYC", "FEDERAL"] }

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).

Partner API documentation:

Related Articles
Did this answer your question?