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

# Bureaux and many organisations

> For bureaux: set webhooks up once for every organisation on your account, give any one organisation its own settings, and list, search and replay across the whole account.

An endpoint normally belongs to one organisation and hears only its events. A bureau running payroll for hundreds of clients should not need an endpoint per client. Set webhooks up once for the whole account, and change the setup for any one organisation when it needs something different.

## One endpoint for every organisation

Add `scope=customer` to the query when you create the endpoint:

```http theme={null}
POST /endpoints?scope=customer
```

```json theme={null}
{
  "url": "https://example.com/webhooks/flow-payroll",
  "eventTypes": ["payslip.finalised", "p60.issued"]
}
```

The endpoint you get back shows `"scope": "Customer"` and your account in `ownerId`. You cannot change the scope afterwards.

It hears every organisation on your account, including organisations added later: nothing to do when a client joins. You need account-wide access: the account owner, or a user given access to the whole account rather than to individual organisations. Anyone else is refused with `403`.

## Set alert contacts once

Set the account's default alert contacts once, and every endpoint on every organisation uses them unless it has its own:

```
PUT /alert-contacts?scope=customer
{"emails": ["payroll-support@example.com"]}
```

Every alert-contacts response shows who is actually emailed and why, in `effective.source`. See [Alert emails](/api-reference/webhooks/manage-endpoints#alert-emails).

## Give one organisation its own settings

To send one client's events somewhere else, or with different event types or payload style:

1. Exclude it from the account-wide endpoint: `POST /endpoints/{endpointId}/excluded-organisations` with `{"organisationIds": ["org-123"]}`.
2. Create an endpoint for that organisation, signed in to it, with the settings it needs.

Every other organisation, including ones added later, still goes to the account-wide endpoint. To include the organisation again, `DELETE /endpoints/{endpointId}/excluded-organisations/org-123`.

| To | Call |
| - | - |
| See the excluded organisations | `GET /endpoints/{endpointId}/excluded-organisations` |
| Replace the list | `PUT /endpoints/{endpointId}/excluded-organisations` with `{"organisationIds": [...]}` |
| Exclude some | `POST /endpoints/{endpointId}/excluded-organisations` with `{"organisationIds": [...]}` |
| Include some again | `DELETE /endpoints/{endpointId}/excluded-organisations?organisationId=a&organisationId=b` |
| Include one again | `DELETE /endpoints/{endpointId}/excluded-organisations/{organisationId}` |

You can also send `excludedOrganisationIds` when you create the endpoint or with `PATCH /endpoints/{endpointId}`.

### Or hear only some organisations

The opposite: `PUT /endpoints/{endpointId}/organisations` with `{"organisationIds": [...]}` limits the endpoint to those organisations. An endpoint either includes chosen organisations or excludes some, never both: sending both is refused with `organisation_include_and_exclude`.

## See every endpoint on the account

`GET /endpoints?scope=all` lists the account-wide endpoints and every organisation's own endpoints in one list, in the order they were created. Each carries `scope` and `ownerId`, so you can tell an account-wide endpoint from an organisation's. `GET /endpoints?scope=customer` lists the account-wide ones only. Keep following `paginationToken` until it is absent.

## See events across the account

`GET /events?scope=customer` lists the last 90 days of events for every organisation on the account, newest first, with the same `eventType`, `startDate` and `endDate` filters as for one organisation. Each event carries `organisationId`. Events of an organisation that has since left your account are not listed.

`GET /events/{eventId}?scope=customer` reads one event from any organisation on the account. To read one from a single other organisation, send `organisationId` instead; sending both is a `400` with `organisation_and_account_scope`.

## Replay across the account

`POST /replays?scope=customer` resends failed deliveries, or anything you choose, for every endpoint on the account: account-wide and each organisation's own. Name up to 100 `endpointIds` to narrow it. It runs in the background; follow it with `GET /replays/{replayId}?scope=customer`. The replay carries `scope` and `ownerId`, as an endpoint does.

## Limits

| Limit | Value |
| - | - |
| Endpoints per account, and per organisation | 20 |
| Organisations in an include or exclusion list | 500 |
| Named endpoints in one replay | 100 |
| Replays running at once per account | 3 |
| Replay window | 90 days |
| Deliveries one replay creates | 10,000 by default, up to 100,000 |
| Default alert contacts per level | 10 |

## Tell organisations apart

Every delivery names who it belongs to, in the headers and in the body:

* `X-Flow-Organisation-Id` and `organisationId`: the client organisation.
* `X-Flow-Customer-Id` and `customerId`: your account.

Route on the header if you want to avoid parsing the body before you have verified it.


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