> ## 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. # Add several organisations at once > State the shared details once in `defaults`; any entry may override any of them. Leave a field out of an entry to inherit the default, or set it to override — an address set on an entry replaces the default address as a whole rather than merging field by field. Every organisation is created exactly as `POST /organisations` creates one. One `Idempotency-Key` covers the whole batch and each entry claims under it by position, so retrying a partly successful batch finds the organisations it already made instead of making them again. Resend the batch unchanged: entries added, removed or reordered make it a different request, which answers 409 `idempotency_key_reused`. 201 when every entry went through, 207 when some did, 400 when none did. In all three the body lists what happened to each entry. An organisation in `created` can still be incomplete — its own `complete` and `outstandingSteps` say so. 403 `billing_not_set_up` when billing is not set up for the account yet — email hello@flowpayroll.ai to agree pricing and set it up. Accounts onboarded by Flow Payroll are already set up. ## OpenAPI ````yaml /api-reference/specs/administration.json post /organisations/bulk openapi: 3.0.1 info: title: Administration API description: >- Manage your Flow Payroll account: the organisations it owns, the people who can sign in to it, the API tokens it holds, its brand, and a feed of recent administration activity. Every resource is scoped to the account your credentials belong to, so no request ever names a customer and the `X-Org-Id` header is not used. version: v1 servers: - url: https://api.sandbox.flowpayroll.ai/v1/administration security: - X-Auth-Token: [] tags: - name: Customer description: >- Your account: the customer every other resource on this API belongs to. Read it and rename it. - name: Organisations description: >- The organisations your account owns: list them with headcounts and your access to each, get one in full, and add one or several at a time. - name: Users description: >- The people who can sign in to your account: list, invite (one or many), resend invitations, and manage each person's direct grants and account-wide access. - name: API tokens description: >- The client credentials your integrations authenticate with: create (the secret is shown once), rename, rotate, revoke, and manage which organisations each token reaches. - name: Activity description: Recent administration actions in your account, newest first. paths: /organisations/bulk: post: tags: - Organisations summary: Add several organisations at once description: >- State the shared details once in `defaults`; any entry may override any of them. Leave a field out of an entry to inherit the default, or set it to override — an address set on an entry replaces the default address as a whole rather than merging field by field. Every organisation is created exactly as `POST /organisations` creates one. One `Idempotency-Key` covers the whole batch and each entry claims under it by position, so retrying a partly successful batch finds the organisations it already made instead of making them again. Resend the batch unchanged: entries added, removed or reordered make it a different request, which answers 409 `idempotency_key_reused`. 201 when every entry went through, 207 when some did, 400 when none did. In all three the body lists what happened to each entry. An organisation in `created` can still be incomplete — its own `complete` and `outstandingSteps` say so. 403 `billing_not_set_up` when billing is not set up for the account yet — email hello@flowpayroll.ai to agree pricing and set it up. Accounts onboarded by Flow Payroll are already set up. operationId: BulkCreateOrganisations parameters: - name: Idempotency-Key in: header description: >- Your own key for this create, so a retry after a lost response finds what the first attempt made instead of making a second one. Any unique string up to 255 characters; a UUID is the usual choice. Send the same value on every retry of the same request, and a new value for a new one — reusing a key for a different body answers 409 `idempotency_key_reused`. Keys are remembered for 24 hours. Optional, and a request without one simply has no replay protection. schema: maxLength: 255 type: string example: 8b1f4c1e-0000-4000-8000-000000000000 requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkCreateOrganisationsRequest' responses: '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/BulkCreateOrganisationsResponseResponseBody '207': description: Multi-Status content: application/json: schema: $ref: >- #/components/schemas/BulkCreateOrganisationsResponseResponseBody '400': description: Bad Request content: application/json: schema: $ref: >- #/components/schemas/BulkCreateOrganisationsResponseResponseBody '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ObjectResponseBody' components: schemas: BulkCreateOrganisationsRequest: type: object properties: defaults: $ref: '#/components/schemas/BulkOrganisationDefaultsRequest' entries: type: array items: $ref: '#/components/schemas/BulkOrganisationEntryRequest' description: >- The organisations to create, each processed exactly as `POST /organisations` would process it. One `Idempotency-Key` covers the whole batch, and each entry claims under it by position. nullable: true additionalProperties: false description: >- Adds several organisations to your account in one request: shared defaults plus per-entry overrides. BulkCreateOrganisationsResponseResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/BulkCreateOrganisationsResponseContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false ObjectResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: $ref: '#/components/schemas/ObjectContentResponse' validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true additionalProperties: false BulkOrganisationDefaultsRequest: type: object properties: organisationType: enum: - Branch - Franchise - Independent - Parent - Subsidiary type: string description: >- One of `Branch`, `Franchise`, `Independent`, `Parent` or `Subsidiary`. nullable: true businessType: enum: - Charity - LimitedCompany - LimitedLiabilityPartnership - Partnership - PublicSector - SoleTrader type: string description: >- One of `Charity`, `LimitedCompany`, `LimitedLiabilityPartnership`, `Partnership`, `PublicSector` or `SoleTrader`. nullable: true registeredOfficeAddress: $ref: '#/components/schemas/AddressRequest' correspondenceAddress: $ref: '#/components/schemas/AddressRequest' primaryContactDetails: $ref: '#/components/schemas/ContactDetailsRequest' companyContactDetails: $ref: '#/components/schemas/ContactDetailsRequest' additionalProperties: false description: >- What every organisation in the request gets unless its own entry says otherwise. BulkOrganisationEntryRequest: type: object properties: legalName: type: string description: Required. The registered legal name. nullable: true tradingName: type: string description: The trading name, if it differs from the legal name. nullable: true organisationType: enum: - Branch - Franchise - Independent - Parent - Subsidiary type: string description: >- One of `Branch`, `Franchise`, `Independent`, `Parent` or `Subsidiary`. nullable: true businessType: enum: - Charity - LimitedCompany - LimitedLiabilityPartnership - Partnership - PublicSector - SoleTrader type: string description: >- One of `Charity`, `LimitedCompany`, `LimitedLiabilityPartnership`, `Partnership`, `PublicSector` or `SoleTrader`. nullable: true companyRegistrationNumber: type: string description: The Companies House registration number. nullable: true registeredOfficeAddress: $ref: '#/components/schemas/AddressRequest' correspondenceAddress: $ref: '#/components/schemas/AddressRequest' primaryContactDetails: $ref: '#/components/schemas/ContactDetailsRequest' companyContactDetails: $ref: '#/components/schemas/ContactDetailsRequest' additionalProperties: false description: >- One organisation in a bulk create. Only `legalName` is required; everything else inherits from the defaults unless set here. MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false BulkCreateOrganisationsResponseContentResponse: type: object properties: data: $ref: '#/components/schemas/BulkCreateOrganisationsResponse' metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false ValidationIssue: type: object properties: field: type: string reason: type: string reasonToken: type: string reasonTokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true additionalProperties: false ObjectContentResponse: type: object properties: data: nullable: true metadata: $ref: '#/components/schemas/ContentMetadataResponse' additionalProperties: false AddressRequest: type: object properties: line1: type: string description: The first line of the address. nullable: true line2: type: string description: The second line of the address. nullable: true city: type: string description: The town or city. nullable: true county: type: string description: The county. nullable: true postcode: type: string description: The postcode. nullable: true countryCode: type: string description: The country code, for example `GB`. nullable: true additionalProperties: false description: A postal address. ContactDetailsRequest: type: object properties: name: type: string description: The contact's name. nullable: true email: type: string description: The contact's email address. nullable: true phone: type: string description: The contact's phone number. nullable: true additionalProperties: false description: A named contact. ValidationIssueArgument: type: object properties: name: type: string value: nullable: true additionalProperties: false BulkCreateOrganisationsResponse: type: object properties: created: type: array items: $ref: '#/components/schemas/OrganisationCreatedResponse' description: The entries that were created, each with its setup outcome. failed: type: array items: $ref: '#/components/schemas/BulkFailureResponse' description: The entries that were refused, each with the reason. additionalProperties: false description: >- What a bulk create did, organisation by organisation. An organisation in `created` can still be incomplete: its own `complete` and `outstandingSteps` say so. ContentMetadataResponse: type: object properties: dateFormat: type: string dateTimeFormat: type: string paginationToken: type: string nullable: true additionalProperties: false OrganisationCreatedResponse: type: object properties: organisationId: type: string description: >- The new organisation's identifier. Stable across every replay of the same `Idempotency-Key`. complete: type: boolean description: True when every setup step finished. completedSteps: type: array items: type: string description: The setup steps that finished. outstandingSteps: type: array items: type: string description: >- The setup steps that did not finish. Empty when `complete` is true; otherwise the organisation exists but needs attention from Flow Payroll support. additionalProperties: false description: The outcome of adding an organisation. BulkFailureResponse: type: object properties: reference: type: string description: >- The entry as you sent it, so you can find it in your own request: the email address for a person, the legal name for an organisation. reason: type: string description: >- The same stable snake_case token the single-item endpoint would answer with in `message.token`, so there is one set of reasons to handle. message: type: string description: A sentence explaining the refusal. additionalProperties: false description: One entry of a bulk request that was refused. securitySchemes: X-Auth-Token: type: apiKey description: FlowPayroll JWT (raw token, no Bearer prefix) name: X-Auth-Token in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.