Expandable Properties

Expandable properties are available on certain endpoints to allow retrieval of nested resources or additional data within a parent resource. This is particularly useful when fetching lists of resources, and prevents having to make subsequent requests to retrieve the expandable data for each individual resource. Expandable properties are collapsed by default to keep responses concise and efficient.

Expandable properties are labelled with "expandable: true", and are listed within the endpoint's query parameters.

Example

Expandable properties are typically an integer when collapsed, and an object when expanded. Expandable properties may also be null or arrays depending on the resource. For more details see Property Types

The following example is of a document object with an expandable attachment property. Once expanded, the attachment property contains the complete attachment object.

Collapsed

{
    "object": "document",
    "id": 3342,
    "name": "Non-disclosure agreement",
    "description": "Generic non-disclosure agreement",
    "is_enabled": true,
    "attachment": 43375,
    "created_at": "2022-08-17T13:56:05Z",
    "updated_at": "2022-08-17T13:56:05Z"
}

Expanded

{
    "object": "document",
    "id": 3342,
    "name": "Non-disclosure agreement",
    "description": "Generic non-disclosure agreement",
    "is_enabled": true,
    "attachment": {
        "object": "attachment",
        "id": 43375,
        "name": "367452af-3931-4207-851a-adda324cd3d6.pdf",
        "original": "NDA-final.pdf",
        "type": "application/pdf",
        "size": 272534,
        "av_status": "clean",
        "created_at": "2022-08-17T13:56:05Z",
        "updated_at": "2022-08-17T13:56:05Z"
    },
    "created_at": "2022-08-17T13:56:05Z",
    "updated_at": "2022-08-17T13:56:05Z"
}

Usage

The expand property should be included as a query parameter in the API request url. The value of this property typically represents the resource that you want to expand. For example to expand the check property for check step types in List all steps for a record, the GET request url should be:

https://id.amiqus.co/api/v2/records/123/steps?expand=check

Where available, multiple resources can be expanded using a comma separated list. The order of the values is not important:

https://id.amiqus.co/api/v2/records/123/steps?expand=check,form,document

Nested expandable properties

It is not possible to expand properties within expanded data. For example accessing credits with an expanded causer can list a check object. The check in turn, at its own endpoint, Retrieve a check, can expand both record and response. However, it is not possible to do so here.

https://id.amiqus.co/api/v2/credits?expand=causer

Expanded causer

{
  "object": "credit_history",
  "id": 2,
  "credits": -1,
  "reason": null,
  "causer": {
    "object": "check",
    "id": 19,
    "type": "dummy",
    "record": 23,
    "status": "accepted",
    "response": true,
    "allow_replay": false,
    "allow_cancel": false,
    "requires_consent": true,
    "created_at": "2024-09-05T10:46:35Z",
    "updated_at": "2024-09-09T14:02:57Z"
  },
  "created_at": "2024-09-09T14:02:47Z"
}

Expanding nested response property

{
  "expand": [
    "The expand parameter must be one of: causer"
  ]
}

Property Types

The value of an expandable property both in its collapsed and expanded state depends on the resource being expanded. A typical expandable property representing a single resource will be be of the following types:

State	Type	Description
Both	null	Property has no resource.
Collapsed	integer	Property has a single resource, value is the resource ID.
Collapsed	Array of integer	Property has multiple resources, values are the resource IDs.
Collapsed	object	Property has one of a number of resource types, value is an object containing the resource ID and object type.
Expanded	object	Property has a single resource, value is the full resource object.
Expanded	Array of object	Property has multiple resources, values are the full resource objects.

Advanced Examples

Multiple resources

Resources with expandable properties containing multiple values are arrays of integers when collapsed, an array of objects when expanded. When the expandable property is empty, it is null whether collapsed or expanded, however some expandable properties will never be empty.

An example is List all documents for a record, where a Document Request object, record_document, may contain multiple attachments. Before the client has complete the step, the attachments property is null.

Collapsed

{
  "object": "record_document",
  "id": 5481,
  "type": "requested",
  "name": "3e337df9-872a-4753-b86a-87cb535ee16d.pdf",
  "status": "complete",
  "config": {
    "instructions": "A utility bill dated within the last three months."
  },
  "source": {
    "type": "record",
    "id": 3247
  },
  "attachments": [
    1267,
    1282
  ],
  "created_at": "2022-08-24T14:15:22Z",
  "updated_at": "2022-08-24T14:15:22Z",
  "completed_at": "2022-08-25T11:02:13Z"
}

Expanded

{
  "object": "record_document",
  "id": 5481,
  "type": "requested",
  "name": "3e337df9-872a-4753-b86a-87cb535ee16d.pdf",
  "status": "complete",
  "config": {
    "instructions": "A utility bill dated within the last three months."
  },
  "source": {
    "type": "record",
    "id": 3247
  },
  "attachments": [
    {
      "object": "attachment",
      "id": 1267,
      "name": "1d420ac7-a87a-444a-936b-dc29991ab8ed.pdf",
      "original": "Electricity-page_one.pdf",
      "type": "application/pdf",
      "size": 74590,
      "av_status": "clean",
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-24T14:15:22Z"
    },
    {
      "object": "attachment",
      "id": 1282,
      "name": "42e77676-1652-496e-b64d-2194dfab4a3c.pdf",
      "original": "Electricity-page_two.pdf",
      "type": "application/pdf",
      "size": 42156,
      "av_status": "clean",
      "created_at": "2022-08-24T14:19:51Z",
      "updated_at": "2022-08-24T14:19:51Z"
    }
  ],
  "created_at": "2022-08-24T14:15:22Z",
  "updated_at": "2022-08-24T14:15:22Z",
  "completed_at": "2022-08-25T11:02:13Z"
}

No values

{
  "object": "record_document",
  "id": 5481,
  "type": "requested",
  "name": "3e337df9-872a-4753-b86a-87cb535ee16d.pdf",
  "status": "pending",
  "config": {
    "instructions": "A utility bill dated within the last three months."
  },
  "source": {
    "type": "record",
    "id": 3247
  },
  "attachments": null,
  "created_at": "2022-08-24T14:15:22Z",
  "updated_at": "2022-08-24T14:15:22Z",
  "completed_at": null
}

One of multiple types

Resources with expandable properties containing a single value of variable type are objects both when collapsed and expanded. The collapsed object contains the object type and its unique identifier. When the expandable property is empty, it is null whether collapsed or expanded, however some expandable properties will never be empty.

An example is List all files for a client, where the Client File's source may be one of a number of types depending on where it was uploaded. The following example is of a file uploaded by a team member to the client's documents area. The source type is client, and expanded value is the client object. The client_file object always has a source, so the property will never be null.

Collapsed

{
  "object": "client_file",
  "id": 31788,
  "type": "internal",
  "source": {
    "id": 73845,
    "type": "client"
  },
  "name": "73db4d13-6c1b-40b1-94fc-2cf6d7ac22d2.pdf",
  "attachment": {
    "object": "attachment",
    "id": 31782,
    "name": "73db4d13-6c1b-40b1-94fc-2cf6d7ac22d2.pdf",
    "original": "JobSpec-final.pdf",
    "type": "application/pdf",
    "size": 16053,
    "av_status": "clean",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Expanded

{
  "object": "client_file",
  "id": 31788,
  "type": "internal",
  "source": {
    "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
  },
  "name": "73db4d13-6c1b-40b1-94fc-2cf6d7ac22d2.pdf",
  "attachment": {
    "object": "attachment",
    "id": 31782,
    "name": "73db4d13-6c1b-40b1-94fc-2cf6d7ac22d2.pdf",
    "original": "JobSpec-final.pdf",
    "type": "application/pdf",
    "size": 16053,
    "av_status": "clean",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Empty values

Resources with expandable properties that can be empty, are null both when collapsed and expanded. Not all expandable properties can be empty, so refer to the resource in the API reference.

An example is List all documents for a record, where a Document Request object's expandable attachments property is null until the client has completed this step.

Collapsed

{
  "object": "record_document",
  "id": 5481,
  "type": "requested",
  "name": "3e337df9-872a-4753-b86a-87cb535ee16d.pdf",
  "status": "pending",
  "config": {
    "instructions": "A utility bill dated within the last three months."
  },
  "source": {
    "type": "record",
    "id": 3247
  },
  "attachments": null,
  "created_at": "2022-08-24T14:15:22Z",
  "updated_at": "2022-08-24T14:15:22Z",
  "completed_at": null
}

Expanded

{
  "object": "record_document",
  "id": 5481,
  "type": "requested",
  "name": "3e337df9-872a-4753-b86a-87cb535ee16d.pdf",
  "status": "pending",
  "config": {
    "instructions": "A utility bill dated within the last three months."
  },
  "source": {
    "type": "record",
    "id": 3247
  },
  "attachments": null,
  "created_at": "2022-08-24T14:15:22Z",
  "updated_at": "2022-08-24T14:15:22Z",
  "completed_at": null
}

Multiple properties

More than one expandable property can be expanded in a single request by providing a comma-separated value in the expand query parameter.

An example is List all forms for a client, where a both client and record are expandable properties when the client form is a requested type.

To expand both, provide the query parameter: ?expand=client,record.

Collapsed

{
  "object": "client_form",
  "id": 37344,
  "reference": "2ddb20b8-e0e3-45ae-a638-42610b990a6a",
  "type": "requested",
  "client": 73212,
  "record": 87564,
  "name": "New starter form",
  "description": null,
  "instructions": null,
  "fields": [...],
  "version": 1,
  "created_at": "2022-05-22T08:22:12Z",
  "updated_at": "2022-05-22T08:22:12Z",
  "completed_at": null,
  "archived_at": null
}

Expanded

{
  "object": "client_form",
  "id": 37344,
  "reference": "2ddb20b8-e0e3-45ae-a638-42610b990a6a",
  "type": "requested",
  "client": {
    "object": "client",
    "id": 73212,
    "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
  },
  "record": {
    "object": "record",
    "id": 87564,
    "status": "pending",
    "perform_url": "https://id.amiqus.co/i/0vz32B9CZpO1yLsKPdy9q",
    "email": "marty@example.com",
    "steps": [...],
    "client": 73212,
    "created_at": "2022-05-22T08:22:12Z",
    "updated_at": "2022-05-22T08:22:12Z",
    "archived_at": null
  },
  "name": "New starter form",
  "description": null,
  "instructions": null,
  "fields": [...],
  "version": 1,
  "created_at": "2022-05-22T08:22:12Z",
  "updated_at": "2022-05-22T08:22:12Z",
  "completed_at": null,
  "archived_at": null
}