Amiqus Developers

Appearance

Automation ​

Overview ​

This guide will walk you through the process of automating client management and issuing records using a series of API calls. By following these steps, you will be able to create a seamless workflow that integrates client creation and record issuance. This is particularly useful for systems such as registration forms on your website, allowing you to streamline these processes efficiently and effectively.

The result is a record that is sent to a client, either automatically via email or with a link that you can provide them with manually. The client can then go through the process of completing the record by uploading their documents and fulfilling any other necessary requirements. This automation not only saves time but also ensures a consistent and reliable process for managing client records.

This page focuses on working code for each API call. For the end-to-end flow, including webhook setup, creating records from a template and what to do once the client has completed their checks, see the Standard Amiqus Integration Flow guide.

If your team uses cases, Steps 2 and 4 show how to create a case for the client and add the record to it, so your team can review the client's checks together.

Objective: Automate the process of managing clients, issuing records and grouping them into cases.

Cases may not be enabled for your team

Cases are the default structure for teams, but a small number of legacy teams work with clients and records only, and the cases endpoints are not available to them.

A record you create through the API does not belong to a case until you explicitly add it. Records are never placed in a case automatically, even on a team that uses cases. Add them with Update items for a case, and store the association on your side if you need to look it up later.

Step 1: Creating a Client ​

To begin the automation, create a client. This is usually the first step in automating workflows, allowing subsequent operations to be linked to a specific client. This client entry will only contain basic details such as their full name and email. It will not trigger any records to be sent to the client.

Endpoint: POST /api/v2/clientsDescription: Create a new client by providing necessary details like name and email.

Code Example:

php
<?php

class CreateClient
{
  public function __construct(private string $apiUrl, private string $accessToken)
  {
  }

  public function createClient(array $clientData): array
  {
    $url = $this->apiUrl . '/clients';
    $headers = [
      'Content-Type: application/json',
      'Authorization: Bearer ' . $this->accessToken
    ];
    $payload = json_encode($clientData);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
      throw new Exception(curl_error($ch));
    }

    $statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($statusCode !== 201) {
      throw new Exception('Failed to create client, status code: ' . $statusCode);
    }

    return json_decode($response, true);
  }
}

$clientCreator = new CreateClient('https://id.amiqus.co/api/v2', 'your_access_token');
$clientData = [
  'name' => [
    'title' => 'mr',
    'first_name' => 'Martin',
    'middle_name' => 'Seamus',
    'last_name' => 'McFly'
  ],
  'email' => 'marty@example.com'
];

try {
  $client = $clientCreator->createClient($clientData);
  echo 'Client created successfully: ' . print_r($client, true);
} catch (Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
python
import requests
import json

class CreateClient:
    def __init__(self, api_url, access_token):
        self.api_url = api_url
        self.access_token = access_token

    def create_client(self, client_data):
        url = f"{self.api_url}/clients"
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f"Bearer {self.access_token}"
        }
        payload = json.dumps(client_data)

        response = requests.post(url, headers=headers, data=payload)

        if response.status_code != 201:
            raise Exception(f"Failed to create client, status code: {response.status_code}")

        return response.json()

client_creator = CreateClient('https://id.amiqus.co/api/v2', 'your_access_token')
client_data = {
    'name': {
        'title': 'mr',
        'first_name': 'Martin',
        'middle_name': 'Seamus',
        'last_name': 'McFly'
    },
    'email': 'marty@example.com'
}

try:
    client = client_creator.create_client(client_data)
    print('Client created successfully:', client)
except Exception as e:
    print('Error:', str(e))
javascript
const axios = require('axios');

class CreateClient {
  constructor(apiUrl, accessToken) {
    this.apiUrl = apiUrl;
    this.accessToken = accessToken;
  }

  async createClient(clientData) {
    const url = `${this.apiUrl}/clients`;
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.accessToken}`
    };

    try {
      const response = await axios.post(url, clientData, { headers });
      if (response.status !== 201) {
        throw new Error(`Failed to create client, status code: ${response.status}`);
      }
      return response.data;
    } catch (error) {
      throw new Error(error.message);
    }
  }
}

const clientCreator = new CreateClient('https://id.amiqus.co/api/v2', 'your_access_token');
const clientData = {
  name: {
    title: 'mr',
    first_name: 'Martin',
    middle_name: 'Seamus',
    last_name: 'McFly'
  },
  email: 'marty@example.com'
};

clientCreator.createClient(clientData)
  .then(client => {
    console.log('Client created successfully:', client);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Step 2: Creating a Case (optional) ​

If your team uses cases, create a case for the client so that their records can be reviewed together. Store the case id from the response, as you will need it to add the record to the case in Step 4.

If the client already has a case that this record belongs to, for example a follow-up check during an ongoing onboarding, you can skip this step and use the existing case id instead. A case can gain further records at any point, but adding a record does not change the case's status. A case that has already been reviewed, for example one marked approved, keeps that status, so your team will need to review the case again once the new record is complete.

Endpoint: POST /api/v2/casesDescription: Create a case for the client by providing the client id, a name and, optionally, your own reference.

Code Example:

php
<?php

class CreateCase
{
  public function __construct(private string $apiUrl, private string $accessToken)
  {
  }

  public function createCase(int $clientId): array
  {
    $url = $this->apiUrl . '/cases';
    $headers = [
      'Content-Type: application/json',
      'Authorization: Bearer ' . $this->accessToken
    ];
    $payload = json_encode([
      'client' => $clientId,
      'name' => 'Full-time onboarding',
      'reference' => 'AQFT123'
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
      throw new Exception(curl_error($ch));
    }

    $statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($statusCode !== 201) {
      throw new Exception('Failed to create case, status code: ' . $statusCode);
    }

    return json_decode($response, true);
  }
}

// Usage
$caseCreator = new CreateCase('https://id.amiqus.co/api/v2', 'your_access_token');
$clientId = 7832;

try {
  $case = $caseCreator->createCase($clientId);
  echo 'Case created successfully: ' . print_r($case, true);
} catch (Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
python
import requests
import json

class CreateCase:
    def __init__(self, api_url, access_token):
        self.api_url = api_url
        self.access_token = access_token

    def create_case(self, client_id):
        url = f"{self.api_url}/cases"
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f"Bearer {self.access_token}"
        }
        payload = json.dumps({
            'client': client_id,
            'name': 'Full-time onboarding',
            'reference': 'AQFT123'
        })

        response = requests.post(url, headers=headers, data=payload)

        if response.status_code != 201:
            raise Exception(f"Failed to create case, status code: {response.status_code}")

        return response.json()

# Usage
case_creator = CreateCase('https://id.amiqus.co/api/v2', 'your_access_token')
client_id = 7832

try:
    case = case_creator.create_case(client_id)
    print('Case created successfully:', case)
except Exception as e:
    print('Error:', str(e))
javascript
const axios = require('axios');

class CreateCase {
  constructor(apiUrl, accessToken) {
    this.apiUrl = apiUrl;
    this.accessToken = accessToken;
  }

  async createCase(clientId) {
    const url = `${this.apiUrl}/cases`;
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.accessToken}`
    };
    const payload = {
      client: clientId,
      name: 'Full-time onboarding',
      reference: 'AQFT123'
    };

    try {
      const response = await axios.post(url, payload, { headers });
      if (response.status !== 201) {
        throw new Error(`Failed to create case, status code: ${response.status}`);
      }
      return response.data;
    } catch (error) {
      throw new Error(error.message);
    }
  }
}

// Usage
const caseCreator = new CreateCase('https://id.amiqus.co/api/v2', 'your_access_token');
const clientId = 7832;

caseCreator.createCase(clientId)
  .then(clientCase => {
    console.log('Case created successfully:', clientCase);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Step 3: Creating a Record ​

Once the client (and, optionally, the case) is created, choose the steps you'd like the client to complete and create a record to be issued to the client. The below example will issue a record to a client that will ask them to conduct a Photo ID check and a Criminal Record check.

Endpoint: POST /api/v2/recordsDescription: Create a record to initiate a range of checks for the client.

Code Example:

php
<?php

class CreateRecord
{
  public function __construct(private string $apiUrl, private string $accessToken)
  {
  }

  public function createRecord(int $clientId): array
  {
    $url = $this->apiUrl . '/records';
    $headers = [
      'Content-Type: application/json',
      'Authorization: Bearer ' . $this->accessToken
    ];
    $payload = json_encode([
      'client' => $clientId,
      'steps' => [
        [
          'type' => 'check.photo_id',
          'preferences' => [
            'report_type' => 'biometric'
          ]
        ],
        [
          'type' => 'check.criminal_record',
          'preferences' => [
            'region' => 'england',
            'type' => 'standard'
          ]
        ]
      ],
      'notification' => 'email',
      'message' => 'Please complete the following request to begin onboarding with Fusion Industries.',
      'reminder' => true
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
      throw new Exception(curl_error($ch));
    }

    $statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($statusCode !== 201) {
      throw new Exception('Failed to create record, status code: ' . $statusCode);
    }

    return json_decode($response, true);
  }
}

// Usage
$recordCreator = new CreateRecord('https://id.amiqus.co/api/v2', 'your_access_token');
$clientId = 7832;

try {
  $record = $recordCreator->createRecord($clientId);
  echo 'Record created successfully: ' . print_r($record, true);
} catch (Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
python
import requests
import json

class CreateRecord:
    def __init__(self, api_url, access_token):
        self.api_url = api_url
        self.access_token = access_token

    def create_record(self, client_id):
        url = f"{self.api_url}/records"
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f"Bearer {self.access_token}"
        }
        payload = json.dumps({
            'client': client_id,
            'steps': [
                {
                    'type': 'check.photo_id',
                    'preferences': {
                        'report_type': 'biometric'
                    }
                },
                {
                    'type': 'check.criminal_record',
                    'preferences': {
                        'region': 'england',
                        'type': 'standard'
                    }
                }
            ],
            'notification': 'email',
            'message': 'Please complete the following request to begin onboarding with Fusion Industries.',
            'reminder': True
        })

        response = requests.post(url, headers=headers, data=payload)

        if response.status_code != 201:
            raise Exception(f"Failed to create record, status code: {response.status_code}")

        return response.json()

# Usage
record_creator = CreateRecord('https://id.amiqus.co/api/v2', 'your_access_token')
client_id = 7832

try:
    record = record_creator.create_record(client_id)
    print('Record created successfully:', record)
except Exception as e:
    print('Error:', str(e))
javascript
const axios = require('axios');

class CreateRecord {
  constructor(apiUrl, accessToken) {
    this.apiUrl = apiUrl;
    this.accessToken = accessToken;
  }

  async createRecord(clientId) {
    const url = `${this.apiUrl}/records`;
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.accessToken}`
    };
    const payload = {
      client: clientId,
      steps: [
        {
          type: 'check.photo_id',
          preferences: {
            report_type: 'biometric'
          }
        },
        {
          type: 'check.criminal_record',
          preferences: {
            region: 'england',
            type: 'standard'
          }
        }
      ],
      notification: 'email',
      message: 'Please complete the following request to begin onboarding with Fusion Industries.',
      reminder: true
    };

    try {
      const response = await axios.post(url, payload, { headers });
      if (response.status !== 201) {
        throw new Error(`Failed to create record, status code: ${response.status}`);
      }
      return response.data;
    } catch (error) {
      throw new Error(error.message);
    }
  }
}

// Usage
const recordCreator = new CreateRecord('https://id.amiqus.co/api/v2', 'your_access_token');
const clientId = 7832;

recordCreator.createRecord(clientId)
  .then(record => {
    console.log('Record created successfully:', record);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Step 4: Adding the Record to the Case (optional) ​

Finally, add the record you created in Step 3 to the case you created in Step 2. Records are never added to a case automatically, so without this step the record will not appear in the case. Items are merged with any already on the case, and only newly added items are returned.

The link between a case and its records is one-directional: you can list the records in a case, but a record has no case property and records cannot be filtered by case. If your integration needs to know which case a record belongs to, store the case id alongside the record id on your side.

Endpoint: PATCH /api/v2/cases/{id}/itemsDescription: Add one or more records to a case.

Code Example:

php
<?php

class AddRecordToCase
{
  public function __construct(private string $apiUrl, private string $accessToken)
  {
  }

  public function addRecordToCase(int $caseId, int $recordId): ?array
  {
    $url = $this->apiUrl . '/cases/' . $caseId . '/items';
    $headers = [
      'Content-Type: application/json',
      'Authorization: Bearer ' . $this->accessToken
    ];
    $payload = json_encode([
      [
        'id' => $recordId,
        'type' => 'record'
      ]
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
      throw new Exception(curl_error($ch));
    }

    $statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    // 201 returns the newly added items; 204 returns no content
    if (!in_array($statusCode, [201, 204], true)) {
      throw new Exception('Failed to add record to case, status code: ' . $statusCode);
    }

    return $statusCode === 201 ? json_decode($response, true) : null;
  }
}

// Usage
$caseItemUpdater = new AddRecordToCase('https://id.amiqus.co/api/v2', 'your_access_token');
$caseId = 8723;
$recordId = 983434;

try {
  $items = $caseItemUpdater->addRecordToCase($caseId, $recordId);
  echo 'Record added to case successfully: ' . print_r($items, true);
} catch (Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
python
import requests
import json

class AddRecordToCase:
    def __init__(self, api_url, access_token):
        self.api_url = api_url
        self.access_token = access_token

    def add_record_to_case(self, case_id, record_id):
        url = f"{self.api_url}/cases/{case_id}/items"
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f"Bearer {self.access_token}"
        }
        payload = json.dumps([
            {
                'id': record_id,
                'type': 'record'
            }
        ])

        response = requests.patch(url, headers=headers, data=payload)

        # 201 returns the newly added items; 204 returns no content
        if response.status_code not in (201, 204):
            raise Exception(f"Failed to add record to case, status code: {response.status_code}")

        return response.json() if response.status_code == 201 else None

# Usage
case_item_updater = AddRecordToCase('https://id.amiqus.co/api/v2', 'your_access_token')
case_id = 8723
record_id = 983434

try:
    items = case_item_updater.add_record_to_case(case_id, record_id)
    print('Record added to case successfully:', items)
except Exception as e:
    print('Error:', str(e))
javascript
const axios = require('axios');

class AddRecordToCase {
  constructor(apiUrl, accessToken) {
    this.apiUrl = apiUrl;
    this.accessToken = accessToken;
  }

  async addRecordToCase(caseId, recordId) {
    const url = `${this.apiUrl}/cases/${caseId}/items`;
    const headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.accessToken}`
    };
    const payload = [
      {
        id: recordId,
        type: 'record'
      }
    ];

    try {
      const response = await axios.patch(url, payload, { headers });
      // 201 returns the newly added items; 204 returns no content
      if (![201, 204].includes(response.status)) {
        throw new Error(`Failed to add record to case, status code: ${response.status}`);
      }
      return response.status === 201 ? response.data : null;
    } catch (error) {
      throw new Error(error.message);
    }
  }
}

// Usage
const caseItemUpdater = new AddRecordToCase('https://id.amiqus.co/api/v2', 'your_access_token');
const caseId = 8723;
const recordId = 983434;

caseItemUpdater.addRecordToCase(caseId, recordId)
  .then(items => {
    console.log('Record added to case successfully:', items);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Next steps ​

Company Registration Number: SC511150 — Data Protection Registration Number: ZA136760
Policies:
UK Digital Verification Services Trust Framework certifiedCyber Essentials Certified Plus logoISO 27001 Information Security managementAWS Qualified Software logoTop 50 data privacy productsTop 50 governance, risk and compliance productsG2 High Performer badgeG2 Leader badgeG2 Highest User Adoption badgeG2 Users Love Us badge