> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up an organization

> Get your employer ready for payroll.

Everything in Intermezzo starts with an organization: the employer that runs payroll and files with HMRC under one PAYE reference. Employees and wage types sit under it. Like an employee, an organization is a hub with satellites (see [Hubs, satellites and editions](https://docs.intermezzo.ai/preview/concepts/editions.md)).

| Satellite | Holds |
| - | - |
| `core` | Legal name as filed to HMRC, trading name, incorporation date, logo, shutdown date, website |
| `tax` | PAYE reference, Accounts Office reference, Corporation Tax reference |
| `insurance` | Whether the employer claims the Employment Allowance |
| `address` | Registered address and correspondence address |
| `contact` | Contacts, and the email HMRC writes to about filings |
| `bank` | Accounts the employer pays from, and the BACS Service User Number |

## Create the organization

Send `core` and the satellites you have data for in one call to [Create Organization](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-organization.md). Only `core` is required; `valid_from` is the date the first edition of every satellite starts.

```http Request theme={null}
POST /gb/organizations
```

```json Request body theme={null}
{
  "external_ref": "ACME-UK",
  "valid_from": "2026-04-06",
  "core": {
    "legal_name": "Acme Trading Ltd",
    "dba_name": null,
    "incorporation_date": "2015-03-02",
    "logo_id": null,
    "shutdown_date": null,
    "website": null
  },
  "tax": {
    "paye_reference_number": "123/AB456",
    "accounts_office_reference": "123PA00012345",
    "corporation_tax_reference": null
  },
  "insurance": {
    "employment_allowance_eligible": false
  },
  "address": {
    "address": "1 Main Street, London, EC1A 1BB",
    "correspondence_address": null
  },
  "contact": {
    "contacts": [],
    "hmrc_sender_email": "payroll@acme.example"
  }
}
```

The response is `201` with the organization's `id` (`org_…`). Use it, or `ext:ACME-UK`, in every path under `/gb/organizations/{organization_id}` (see [Conventions](https://docs.intermezzo.ai/preview/conventions.md#address-a-record-by-your-own-key)). [Create Organizations](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-organizations.md) creates several in one call, with the same per-item results as [bulk employee create](https://docs.intermezzo.ai/preview/gb/employees/create.md#create-several-employees).

`legal_name` is what HMRC sees on every filing: at most 35 characters. The PAYE and Accounts Office references are checked against HMRC's formats when you send them.

## Set the HMRC login

Intermezzo files the FPS, EPS and expenses and benefits returns with the employer's Government Gateway login. Set it with [Set HMRC Credentials](https://docs.intermezzo.ai/api-reference/preview/great-britain/set-hmrc-credentials.md):

```http Request theme={null}
PUT /gb/organizations/{organization_id}/hmrc-credentials
```

```json Request body theme={null}
{
  "sender_id": "ISV635",
  "sender_pass": "…"
}
```

The response is `204`. The login is write-only: no response returns it, and there is no `GET`. It has no editions, so the `PUT` takes no `If-Match`. A new `PUT` replaces the previous login.

Set the login before the first FPS is due.

> [!WARNING]
>
> Send the login again whenever the employer changes the Government Gateway password. Until you do, filings to HMRC fail.

## Change the organization later

Each satellite is changed with a `PUT` for a date range, as described in [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md). For example, a move of the registered office from 1 January:

```http Request theme={null}
PUT /gb/organizations/{organization_id}/address
If-Match: "<edition>"
```

```json Request body highlight={2,4} theme={null}
{
  "valid_from": "2027-01-01",
  "valid_to": "9999-12-31",
  "address": "20 King Street, Manchester, M2 4LQ",
  "correspondence_address": null
}
```

The `PUT` returns `200` with the new edition. Reads before 1 January still return the old address; reads from 1 January return the new one.

To add a satellite you didn't send at creation, for example `bank`, send `If-None-Match: *` instead of `If-Match`.

## Check what is missing

[Get Organization Status](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-organization-status.md) will report what still stands between the organization's data and a completed payroll. It comes in a future release; until then it returns no findings.

## Before you add employees

For now, once the organization exists, Intermezzo sets up how it is paid and its workplace pension scheme, and gives you the `pay_group_id` to put on each employee. Then add [wage types](https://docs.intermezzo.ai/preview/gb/organization/wage-types.md) if the catalog doesn't cover your pay elements, and [create employees](https://docs.intermezzo.ai/preview/gb/employees/create.md).

## Close an organization

Close an organization when the employer stops running payroll under this PAYE reference: it stopped trading, the PAYE scheme ends, or the payroll moves away from Intermezzo. Close it straight away if it was created by mistake.

> [!WARNING]
>
> Closing can't be undone. A closed organization stays readable and accepts no further changes (`409 HUB_CLOSED`).

Closing doesn't tell HMRC anything. Ending the PAYE scheme is a final EPS that you send yourself. Work in this order:

**1. Approve the last pay run**

**2. Set the shutdown date**

Set `core.shutdown_date` if the employer stopped trading.

**3. Send the final EPS**

Send it with the date the scheme ceased ([Submit EPS](https://docs.intermezzo.ai/api-reference/preview/great-britain/submit-eps.md)).

**4. Close everything under the organization**

Close the employees, the organization's wage types and its absence schemes. While any of them is open, closing the organization returns `409 OPEN_CHILDREN`.

**5. Close the organization**

Call [Close Organization](https://docs.intermezzo.ai/api-reference/preview/great-britain/close-organization.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.