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

# Organisations API

> List, create and update organisations in your Zapnito community through the API, with pagination and example requests.

List, create and update the organisations in your community. To manage the users in an organisation, see [Organisation users](/api/v1/organisation-users).

Before you start, read the [API overview](/api/v1/overview) for how authentication, headers, pagination and errors work.

## List organisations

Return the organisations in your community.

<ParamField query="page" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of results to return per page.
</ParamField>

<ParamField query="query" type="string">
  A search term to reduce the number of results.
</ParamField>

```bash title="List organisations" theme={null}
curl "https://your-community.zapnito.com/api/v1/organisations?page=1&per_page=20" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`GET https://your-community.zapnito.com/api/v1/organisations`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "organisations": [
      {
        "id": 1,
        "name": "Harbour Capital",
        "email": "info@example.com",
        "profile": "Investment manager serving UK clients.",
        "address": "1 Harbour Street",
        "country": "GB",
        "website_url": "https://example.com"
      },
      {
        "id": 2,
        "name": "Fernhill Institute",
        "email": "contact@example.com",
        "profile": "Professional body for compliance teams.",
        "address": "2 Fernhill Road",
        "country": "GB",
        "website_url": "https://example.com"
      }
    ]
  }
  ```
</ResponseExample>

## Create an organisation

Create a new organisation.

<ParamField body="organisation.name" type="string" required>
  The name of the organisation.
</ParamField>

<ParamField body="organisation.email" type="string" required>
  The email address of the organisation.
</ParamField>

<ParamField body="organisation.public_email" type="string">
  The public-facing email address of the organisation.
</ParamField>

<ParamField body="organisation.profile" type="string">
  The profile content of the organisation.
</ParamField>

<ParamField body="organisation.address" type="string">
  The address of the organisation.
</ParamField>

<ParamField body="organisation.country" type="string">
  The country of the organisation.
</ParamField>

<ParamField body="organisation.website_url" type="string">
  The URL of the organisation's website.
</ParamField>

<ParamField body="organisation.public_phone_number" type="string">
  The public-facing phone number of the organisation.
</ParamField>

<ParamField body="organisation.remote_avatar_url" type="string">
  The URL of the organisation's profile image, usually a logo.
</ParamField>

```bash title="Create an organisation" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/organisations" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "organisation": {
      "name": "Brightwell Advisory",
      "email": "info@example.com",
      "public_email": "hello@example.com",
      "profile": "Independent compliance and risk advisory.",
      "address": "123 Your Street, AB1 2CD",
      "country": "GB",
      "website_url": "https://example.com",
      "public_phone_number": "07123 456 789",
      "remote_avatar_url": "https://example.com/image/123"
    }
  }'
```

`POST https://your-community.zapnito.com/api/v1/organisations`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "organisation": {
      "id": 123,
      "name": "Brightwell Advisory",
      "email": "info@example.com",
      "public_email": "hello@example.com",
      "profile": "Independent compliance and risk advisory.",
      "address": "123 Your Street, AB1 2CD",
      "country": "GB",
      "website_url": "https://example.com",
      "public_phone_number": "07123 456 789",
      "remote_avatar_url": "https://example.com/image/123"
    }
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "errors": "Organisation with this email address already exists",
    "id": 123
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "name": ["can't be blank"],
      "email": ["can't be blank"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the organisation was created.
* `409 Conflict`: an organisation with that email address already exists. The `id` in the response is the ID of the existing organisation.
* `422 Unprocessable Entity`: a required parameter is missing.

## Update an organisation

Update an organisation's details. Send only the attributes you want to change.

<ParamField path="id" type="string" required>
  The ID of the organisation.
</ParamField>

<ParamField body="organisation.name" type="string">
  The name of the organisation.
</ParamField>

<ParamField body="organisation.email" type="string">
  The email address of the organisation.
</ParamField>

<ParamField body="organisation.public_email" type="string">
  The public-facing email address of the organisation.
</ParamField>

<ParamField body="organisation.profile" type="string">
  The profile content of the organisation.
</ParamField>

<ParamField body="organisation.address" type="string">
  The address of the organisation.
</ParamField>

<ParamField body="organisation.country" type="string">
  The country of the organisation.
</ParamField>

<ParamField body="organisation.public_phone_number" type="string">
  The public-facing phone number of the organisation.
</ParamField>

<ParamField body="organisation.website_url" type="string">
  The URL of the organisation's website.
</ParamField>

```bash title="Update an organisation" theme={null}
curl -X PUT "https://your-community.zapnito.com/api/v1/organisations/123" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"organisation": {"name": "Brightwell Advisory Group", "public_phone_number": "+44 20 7946 0000"}}'
```

`PUT https://your-community.zapnito.com/api/v1/organisations/:id`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "organisation": {
      "id": 123,
      "name": "Brightwell Advisory Group",
      "email": "info@example.com",
      "public_email": "hello@example.com",
      "profile": "<p>Independent compliance and risk advisory.</p>",
      "address": "123 Your Street, AB1 2CD",
      "country": "GB",
      "website_url": "https://example.com",
      "public_phone_number": "+44 20 7946 0000"
    }
  }
  ```
</ResponseExample>

* `200 OK`: the organisation was updated. The response confirms the saved attributes.


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