Amiqus Developers

Appearance

Endpoints for managing a team's clients ​

If your integration uses any endpoints that related to clients, you will need to make some changes.

The following properties have been removed from the client endpoints in v2 and replaced with their own distinct endpoints:

List all clients ​

v1GEThttps://id.amiqus.co/api/clients
v2GEThttps://id.amiqus.co/api/v2/clients

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

Request:

Changed

  • Accepted values for visibility have changed:
    • v1 accepted either archived or all as by default, v1 returned only active clients
    • v2 accepts either archived or active as by default, v2 returns both active and archived clients.

Response:

Added

  • data.*.object This is always client and refers to the object’s type
  • data.*.name.other_title
  • data.*.name.complete_name
  • data.*.national_insurance_number

Changed

  • data.*.name This is now a name object containing properties relating to the client’s name. See API v2 documentation for full list of properties.
  • status - data type has changed from int to enum with string values. See API v2 documentation for full list of possible values.
  • title/other_title - contains new validation: other_title is required if title is set as “other”

Removed

  • archived - this property is removed. Please see archived_at for an alternative.
  • links
  • When making a request using the v2 Retrieve a client the address is no longer an expandable property. Therefore the following properties have been removed: address.unit, address.house_name, address.house_number, address_street_name, address_second_street, address.district, address.district, address.city, address.provincee,address.postcode, address.country. Please see separate Client Address endpoints below.

Note:

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

Below are examples of responses:

json
{
    "data": [
        {
            "id": 6,
            "status": 1,
            "first_name": "Emily",
            "last_name": "Bard",
            "middle_name": "",
            "title": "mrs",
            "name": "Emily Bard",
            "full_name": "Emily Bard",
            "email": "emily@example.com",
            "landline": "+44209011111",
            "mobile": "+44771211111",
            "dob": "1977-02-01",
            "reference": "ref123",
            "archived": false,
            "archived_at": null,
            "is_deletable": false,
            "created_at": "2023-07-27T13:59:52+00:00",
            "updated_at": "2023-08-10T13:36:42+00:00",
            "links": {
                "show": "/clients/6",
                "edit": "/clients/6/edit"
            }
        },
        {
            "id": 4,
            "status": 1,
            "first_name": "Finley",
            "last_name": "Adams",
            "middle_name": "Lee",
            "title": "Ms.",
            "name": "Fiona Adams",
            "full_name": "Fiona Lee Adams",
            "email": "fiona@example.com",
            "landline": null,
            "mobile": "+441799191934",
            "dob": "1962-12-27",
            "reference": "JEJFFXQN72U",
            "archived": false,
            "archived_at": null,
            "is_deletable": false,
            "created_at": "2023-03-22T02:52:49+00:00",
            "updated_at": "2023-04-17T09:28:18+00:00",
            "links": {
                "show": "/clients/4",
                "edit": "/clients/4/edit"
            }
        },
        {
            "id": 5,
            "status": null,
            "first_name": "test",
            "last_name": "test",
            "middle_name": "",
            "title": "",
            "name": "test test",
            "full_name": "test test",
            "email": "test@example.com",
            "landline": null,
            "mobile": null,
            "dob": null,
            "reference": null,
            "archived": false,
            "archived_at": null,
            "is_deletable": true,
            "created_at": "2023-05-24T08:31:13+00:00",
            "updated_at": "2023-05-24T08:31:13+00:00",
            "links": {
                "show": "/clients/5",
                "edit": "/clients/5/edit"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 25,
            "current_page": 1,
            "total_pages": 1,
            "links": {}
        }
    }
}
json
{
    "object": "paginated_list",
    "data": [
        {
            "object": "client",
            "id": 6,
            "status": "pending",
            "name": {
                "object": "name",
                "title": "mrs",
                "other_title": null,
                "first_name": "Emily",
                "middle_name": null,
                "last_name": "Bard",
                "name": "Emily Bard",
                "full_name": "Emily Bard",
                "complete_name": "Mrs Emily Bard"
            },
            "email": "emily@example.com",
            "landline": "+44209011111",
            "mobile": "+441799191934",
            "dob": "1977-02-01",
            "reference": "ref123",
            "national_insurance_number": null,
            "is_deletable": false,
            "created_at": "2023-07-27T13:59:52Z",
            "updated_at": "2023-08-10T13:36:42Z",
            "archived_at": null
        },
        {
            "object": "client",
            "id": 4,
            "status": "pending",
            "name": {
                "object": "name",
                "title": "ms",
                "other_title": null,
                "first_name": "Fiona",
                "middle_name": "Lee",
                "last_name": "Adams",
                "name": "Fiona Adams",
                "full_name": "Fiona Lee Adams",
                "complete_name": "Ms. Fiona Lee Adams"
            },
            "email": "fiona@example.com",
            "landline": null,
            "mobile": "+441799191934",
            "dob": "1962-12-27",
            "reference": "JEJFFXQN72U",
            "national_insurance_number": null,
            "is_deletable": false,
            "created_at": "2023-03-22T02:52:49Z",
            "updated_at": "2023-04-17T09:28:18Z",
            "archived_at": null
        },
        {
            "object": "client",
            "id": 5,
            "status": null,
            "name": {
                "object": "name",
                "title": null,
                "other_title": null,
                "first_name": "test",
                "middle_name": null,
                "last_name": "test",
                "name": "test test",
                "full_name": "Test Test",
                "complete_name": "Test Test"
            },
            "email": "test@example.com",
            "landline": null,
            "mobile": null,
            "dob": null,
            "reference": null,
            "national_insurance_number": null,
            "is_deletable": true,
            "created_at": "2023-05-24T08:31:13Z",
            "updated_at": "2023-05-24T08:31:13Z",
            "archived_at": null
        }
    ],
    "total": 3,
    "count": 3,
    "limit": 25,
    "current_page": 1,
    "total_pages": 1,
    "links": null
}

INFO

📌 Please refer to List all clients for more information.

Create a Client ​

v1POSThttps://id.amiqus.co/api/clients
v2POSThttps://id.amiqus.co/api/v2/clients

Request:

Some properties have been added, changed, removed or restructured when making a POST request to this endpoint.

Added

  • name is an object containing all the name related properties from API v1.
    • first_name
    • middle_name
    • last_name
    • title
    • other_title required if title is set as “other”
  • status

Removed

  • title has been replaced with name.title
  • first_name has been replaced with name.first_name
  • middle_name has been replaced with name.middle_name
  • last_name has been replaced with name.last_name
  • client_id
  • organisation
  • organisation_name
  • address
  • jurisdiction
  • company_number

Response:

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

Added

  • is_deletable
  • national_insurance_number

Changed

  • name is an object containing all the name related properties from API v1
    • object the value of this property is always “name” indicating this is a name object
    • title
    • other_title
    • first_name
    • middle_name
    • last_name
    • name
    • full_name
    • complete_name
  • status data type has changed from int to enum or null. Check API v2 documentation for possible enum values.

Removed

  • archived has been removed. Please see archived_at for an alternative
  • links
  • title has been replaced with name.title
  • first_name has been replaced with name.first_name
  • middle_name has been replaced with name.middle_name
  • last_name has been replaced with name.last_name
  • full_name has been replaced with name.full_name
  • deletable has been replaced with is_deletable

Below are examples of responses:

json
{
    "id": 1,
    "status": null,
    "first_name": "Arthur",
    "last_name": "Gray",
    "middle_name": "Elliot",
    "title": "Dr.",
    "full_name": "Arthur Gray",
    "email": "arthur@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "archived": false,
    "archived_at": null,
    "deletable": true,
    "created_at": "2018-08-29T14:19:05+00:00",
    "updated_at": "2018-08-29T14:19:05+00:00",
    "links": {
        "show": "/clients/1",
        "edit": "/clients/1/edit"
    }
}
json
{
    "object": "client",
    "id": 73845,
    "status": "pending",
    "name": {
        "object": "name",
        "title": "mr",
        "other_title": null,
        "first_name": "Martin",
        "middle_name": "Seamus",
        "last_name": "McFly",
        "name": "Martin McFly",
        "full_name": "Martin Seamus McFly",
        "complete_name": "Mr Martin Seamus McFly"
    },
    "email": "marty@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "national_insurance_number": null,
    "is_deletable": true,
    "created_at": "2022-05-21T14:15:22Z",
    "updated_at": "2022-05-21T14:15:22Z",
    "archived_at": null
}

INFO

📌 Please refer to Create a client for more information.

Retrieve a client ​

v1GEThttps://id.amiqus.co/api/clients/{id}
v2GEThttps://id.amiqus.co/api/v2/clients/{id}

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 a client.

Added

Changed

Removed

Below are examples of responses:

json
{
    "id": 1,
    "status": null,
    "first_name": "Arthur",
    "last_name": "Gray",
		"middle_name": "Elliot",
    "title": "Dr.",
    "full_name": "Arthur Gray",
    "email": "arthur@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "archived": false,
    "archived_at": null,
    "deletable": true,
    "created_at": "2018-08-29T14:19:05+00:00",
    "updated_at": "2018-08-29T14:19:05+00:00",
    "links": {
        "show": "/clients/1",
        "edit": "/clients/1/edit"
    }
}
json
{
    "object": "client",
    "id": 73845,
    "status": "pending",
    "name": {
        "object": "name",
        "title": "mr",
        "other_title": null,
        "first_name": "Martin",
        "middle_name": "Seamus",
        "last_name": "McFly",
        "name": "Martin McFly",
        "full_name": "Martin Seamus McFly",
        "complete_name": "Mr Martin Seamus McFly"
    },
    "email": "marty@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "national_insurance_number": null,
    "is_deletable": true,
    "created_at": "2022-05-21T14:15:22Z",
    "updated_at": "2022-05-21T14:15:22Z",
    "archived_at": null
}

INFO

📌 Please refer to Retrieve a client for more information.

Update a client ​

v1PUThttps://id.amiqus.co/api/clients/{id}
v2PATCHhttps://id.amiqus.co/api/v2/clients/{id}

In v1, this endpoint accepted a PUT request, v2 will now only accept a PATCH request. Please note that the same changes to making a POST request to Create a client applies to PATCH request to Update a client, except that there are no required properties.

Request:

Added

Changed

Removed

Response:

Added

Changed

Removed

Below are examples of responses:

json
{

    "id": 1,
    "status": null,
    "first_name": "Arthur",
    "last_name": "Gray",
    "middle_name": "Elliot",
    "title": "Dr.",
    "full_name": "Arthur Gray",
    "email": "arthur@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "archived": false,
    "archived_at": null,
    "deletable": true,
    "created_at": "2018-08-29T14:19:05+00:00",
    "updated_at": "2018-08-29T14:19:05+00:00",
    "links": {
        "show": "/clients/1",
        "edit": "/clients/1/edit"
    }
}
json
{
    "object": "client",
    "id": 73845,
    "status": "pending",
    "name": {
        "object": "name",
        "title": "mr",
        "other_title": null,
        "first_name": "Martin",
        "middle_name": "Seamus",
        "last_name": "McFly",
        "name": "Martin McFly",
        "full_name": "Martin Seamus McFly",
        "complete_name": "Mr Martin Seamus McFly"
    },
    "email": "marty@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "national_insurance_number": null,
    "is_deletable": true,
    "created_at": "2022-05-21T14:15:22Z",
    "updated_at": "2022-05-21T14:15:22Z",
    "archived_at": null
}

INFO

📌 Please refer to Update a client for more information.

Delete a Client ​

v1DELETEhttps://id.amiqus.co/api/clients/{id}
v2DELETEhttps://id.amiqus.co/api/v2/clients/{id}

Changed:

  • A 204 No Content status will be returned when a client is successfully deleted (this was a 200 OK status previously in v1).
  • Team members with the admin role can delete clients. Team members with the member role can delete clients provided the client has no associated records.

Below are examples of responses:

json
{
    "status": true
}
json
204 No Content

INFO

📌 Please refer to Delete a client for more information.

Client Addresses ​

To retrieve, add or update an address associated with a client, this was previously achieved by using the v1 Retrieve a client, Add a new client, Update a client endpoints. This approach has been deprecated and replaced by two dedicated endpoints for client addresses below.

Retrieve address for a client ​

v1GEThttps://id.amiqus.co/api/clients/{id}
v2GEThttps://id.amiqus.co/api/v2/clients/{id}/address

When making a request using the v2 Retrieve a client the address is no longer an expandable property. Therefore the following properties have been removed: address.unit, address.house_name, address.house_number, address_street_name, address_second_street, address.district, address.district, address.city, address.provincee,address.postcode, address.country

Below are examples of responses:

json
{
    "data": [
        {
            "id": 1,
            "status": null,
            "first_name": "Arthur",
            "last_name": "Gray",
            "middle_name": "Elliot",
            "title": "Dr.",
            "full_name": "Arthur Gray",
            "email": "arthur@example.com",
            "landline": null,
            "mobile": null,
            "dob": null,
            "reference": null,
            "archived": false,
            "archived_at": null,
            "deletable": true,
            "created_at": "2018-08-29T14:19:05+00:00",
            "updated_at": "2018-08-29T14:19:05+00:00",
            "links": {
                "show": "/clients/1",
                "edit": "/clients/1/edit"
            }
        }
    ]
}
json
{
    "object": "address",
    "data": [
        {
            "unit": "3rd Floor",
            "house_name": "Citypoint",
            "house_number": "65",
            "street_name": "Haymarket Terrace",
            "second_street": null,
            "district": null,
            "city": "Edinburgh",
            "province": null,
            "postcode": "EH12 5HD",
            "country": "GB"
        }
    ]
}

INFO

📌 Please refer to Retrieve address for a client for more information.

Replace address for a client (or add an address) ​

v1POSThttps://id.amiqus.co/api/clients
v1PUThttps://id.amiqus.co/api/clients/{id}
v2PUThttps://id.amiqus.co/api/v2/clients/{id}/address

The ability to add an address at same time as creating a new client (Add a new client) and the ability to update an address at the same time as updating a client (Update an existing client) has been removed in the related v2 endpoint counterparts (Create a client, Update a client).

To create a new address and associate it with an existing client or to update and existing client’s address, please see Replace an address for a client.

Below are examples of responses:

json
{
    "id": 1,
    "status": null,
    "first_name": "Arthur",
    "last_name": "Gray",
		"middle_name": "Elliot",
    "title": "Dr.",
    "full_name": "Arthur Gray",
    "email": "arthur@example.com",
    "landline": null,
    "mobile": null,
    "dob": null,
    "reference": null,
    "archived": false,
    "archived_at": null,
    "deletable": true,
    "created_at": "2018-08-29T14:19:05+00:00",
    "updated_at": "2018-08-29T14:19:05+00:00",
    "links": {
        "show": "/clients/1",
        "edit": "/clients/1/edit"
    }
}
json
{
    "object": "address",
    "unit": "3rd Floor",
    "house_name": "Citypoint",
    "house_number": "65",
    "street_name": "Haymarket Terrace",
    "second_street": null,
    "district": null,
    "city": "Edinburgh",
    "province": null,
    "postcode": "EH12 5HD",
    "country": "GB"
}

INFO

📌 Please refer to Replace an address for a client for more information.

©2024 Amiqus Resolution Ltd. | Company Registration Number: SC511150 | Data Protection Registration Number: ZA136760