Endpoints for managing a team's client organisations

Client Organisations

The ability when creating a new client to attach an organisation to that client via the v1 Create a client endpoint has been replaced with the following new endpoints:

• To show all organisations for a client see List all organisations for a client (previously managed in v1 by Show a single client using a query parameter);
• To add an existing organisation to a client’s organisations memberships see Update organisations for a client (previously managed in v1 by Update existing client);
• To replace a client’s organisations memberships with an existing organisation see Replace organisations for a client (previously managed in v1 by Update existing client);
• To delete all of a client’s organisations memberships see Delete organisations for a client (previously managed in v1 by Update existing client);
• To delete a single organisation from a client’s organisations memberships see Delete organisation for a client (previously managed in v1 by Update existing client); and
• To create a new organisation and attach it to a client see Create an organisation and Update organisations for a client (previously managed in v1 by Create a client).

Organisation Endpoints

If your application use any endpoints that related to organisations, you will need to make some changes. Please refer to the documentation for further information on updates to requests, responses and response codes.

List all organisations

This endpoint now returns a paginated list object (see the Pagination Guide for more information). Some properties have been added, changed, removed or restructured.

Added

• “object": "paginated_list"
• “object”: “organisation”
• New updated jurisdiction enums. Additions include : by, bz, bo, br, bg, kh, cw, gf, de,gr, gp, ir, mq, yt, re, bl, mf, pm, ua

Removed

• The following query string properties are no longer available: visibility, status, assignee and q
• archived, clients_count, links

Note:

• Without filtering, v1 returned only active organisations. v2 returns both active and archived organisations.

Below are examples of responses:

v1

{
    "data": [
        {
            "id": 4,
            "name": "Graham Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2022-11-01T03:15:03+00:00",
            "updated_at": "2022-11-01T03:15:03+00:00",
            "clients_count": 0,
            "links": {
                "show": "/organisations/4",
                "api": {
                    "update": "/api/organisations/4"
                }
            }
        },
        {
            "id": 1,
            "name": "Gray Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2022-09-14T19:29:49+00:00",
            "updated_at": "2022-09-14T19:29:49+00:00",
            "clients_count": 0,
            "links": {
                "show": "/organisations/1",
                "api": {
                    "update": "/api/organisations/1"
                }
            }
        },
        {
            "id": 5,
            "name": "Hunter Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2022-05-05T20:11:04+00:00",
            "updated_at": "2022-05-05T20:11:04+00:00",
            "clients_count": 0,
            "links": {
                "show": "/organisations/5",
                "api": {
                    "update": "/api/organisations/5"
                }
            }
        },
        {
            "id": 2,
            "name": "Knight Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2023-01-17T21:45:54+00:00",
            "updated_at": "2023-01-17T21:45:54+00:00",
            "clients_count": 0,
            "links": {
                "show": "/organisations/2",
                "api": {
                    "update": "/api/organisations/2"
                }
            }
        },
        {
            "id": 3,
            "name": "Mitchell Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2022-12-17T09:01:31+00:00",
            "updated_at": "2022-12-17T09:01:31+00:00",
            "clients_count": 1,
            "links": {
                "show": "/organisations/3",
                "api": {
                    "update": "/api/organisations/3"
                }
            }
        },
        {
            "id": 6,
            "name": "Rogers Ltd",
            "company_number": null,
            "jurisdiction": null,
            "archived": false,
            "created_at": "2022-10-01T01:47:08+00:00",
            "updated_at": "2022-10-01T01:47:08+00:00",
            "clients_count": 1,
            "links": {
                "show": "/organisations/6",
                "api": {
                    "update": "/api/organisations/6"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 6,
            "count": 6,
            "per_page": 25,
            "current_page": 1,
            "total_pages": 1,
            "links": {}
        }
    }
}

v2

{
    "object": "paginated_list",
    "data": [
        {
            "object": "organisation",
            "id": 4,
            "name": "Grace Flooring Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2022-11-01T03:15:03Z",
            "updated_at": "2022-11-01T03:15:03Z"
        },
        {
            "object": "organisation",
            "id": 1,
            "name": "Grocer Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2022-09-14T19:29:49Z",
            "updated_at": "2022-09-14T19:29:49Z"
        },
        {
            "object": "organisation",
            "id": 5,
            "name": "Harrington Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2022-05-05T20:11:04Z",
            "updated_at": "2022-05-05T20:11:04Z"
        },
        {
            "object": "organisation",
            "id": 2,
            "name": "Kerr Logistics Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2023-01-17T21:45:54Z",
            "updated_at": "2023-01-17T21:45:54Z"
        },
        {
            "object": "organisation",
            "id": 3,
            "name": "Michaels Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2022-12-17T09:01:31Z",
            "updated_at": "2022-12-17T09:01:31Z"
        },
        {
            "object": "organisation",
            "id": 6,
            "name": "Roe and Cadwell Ltd",
            "company_number": null,
            "jurisdiction": null,
            "created_at": "2022-10-01T01:47:08Z",
            "updated_at": "2022-10-01T01:47:08Z"
        }
    ],
    "total": 6,
    "count": 6,
    "limit": 25,
    "current_page": 1,
    "total_pages": 1,
    "links": null
}

INFO

📌 Please refer to List all organisations for more information.

Create an organisation

Request

The properties required to make a POST request to this endpoint remain the same, except for the additions below.

Added

• New updated jurisdiction enums. Additions include : by, bz, bo, br, bg, kh, cw, gf, de,gr, gp, ir, mq, yt, re, bl, mf, pm, ua

Response

The response payload will contain the newly created organisations’ information. Some of this information is different from v1 including.

Added

• “object”: “organisation”
• New updated jurisdiction enums. Additions include : by, bz, bo, br, bg, kh, cw, gf, de,gr, gp, ir, mq, yt, re, bl, mf, pm, ua

Removed

• archived, clients_count, links

Below are examples of responses:

v1

{
    "data": [
        {
            "id": 11,
            "name": "White PLC",
            "company_number": "12345",
            "jurisdiction": "gb",
            "created_at": "2018-08-29T17:08:04+00:00",
            "updated_at": "2018-08-29T17:08:04+00:00",
            "links": {
                "show": "/organisations/11",
                "api": {
                    "update": "/api/organisations/11"
                }
            }
        }
    ]
}

v2

{
    "object": "organisation",
    "data": [
        {
            {
                "id": 3970,
                "name": "Probert Publishing",
                "company_number": "SF12188",
                "jurisdiction": "gb",
                "created_at": "2022-03-15T21:43:16Z",
                "updated_at": "2022-03-15T21:43:16Z"
            }
        }
    ]
}

INFO

📌 Please refer to Create an organisation for more information.

Retrieve an Organisation

The information required to make a GET request to this endpoint will remain the same from v1. However, the response payload contains a number of changes referred to above in the response of Create an organisation.

Below are examples of responses:

v1

{
    "data": [
        {
            "id": 11,
            "name": "White PLC",
            "company_number": "12345",
            "jurisdiction": "gb",
            "created_at": "2018-08-29T17:08:04+00:00",
            "updated_at": "2018-08-29T17:08:04+00:00",
            "links": {
                "show": "/organisations/11",
                "api": {
                    "update": "/api/organisations/11"
                }
            }
        }
    ]
}

v2

{
    "object": "organisation",
    "data": [
        {
            {
                "id": 3970,
                "name": "Probert Publishing",
                "company_number": "SF12188",
                "jurisdiction": "gb",
                "created_at": "2022-03-15T21:43:16Z",
                "updated_at": "2022-03-15T21:43:16Z"
            }
        }
    ]
}

INFO

📌 Please refer to Retrieve an organisation for more information.

Update an Organisation

Please note that the HTTP method for this endpoint has been updated from PUT to PATCH.

The properties required to make a PATCH request to this endpoint remain the same, except for the additions.

Added

• New updated jurisdiction enums. Additions include : by, bz, bo, br, bg, kh, cw, gf, de,gr, gp, ir, mq, yt, re, bl, mf, pm, ua

The response payload contains a number of changes referred to above in the response of Create an organisation.

Below are examples of responses:

v1

{
    "data": [
        {
            "id": 11,
            "name": "White PLC",
            "company_number": "12345",
            "jurisdiction": "gb",
            "created_at": "2018-08-29T17:08:04+00:00",
            "updated_at": "2018-08-29T17:08:04+00:00",
            "links": {
                "show": "/organisations/11",
                "api": {
                    "update": "/api/organisations/11"
                }
            }
        }
    ]
}

v2

{
    "object": "organisation",
    "data": [
        {
            {
                "id": 3970,
                "name": "Probert Publishing",
                "company_number": "SF12188",
                "jurisdiction": "gb",
                "created_at": "2022-03-15T21:43:16Z",
                "updated_at": "2022-03-15T21:43:16Z"
            }
        }
    ]
}

INFO

📌 Please refer to Update an organisation for more information.