Client FetchAll API

Retrieve paginated clients with optional filtering and search capabilities

Endpoint

GET/client/fetchAll

Retrieves a paginated list of clients with filtering, search capabilities, and preferred contact information.

Authentication

Provide your API token in the request headers:

X-Api-Token: your_token_prefix.your_token_secret

Parameters

Pagination

Parameter Type Required Description
page integer Optional Page number (default: 1, min: 1)
per_page integer Optional Items per page (default: 50, min: 1, max: 100)

Filtering

Parameter Type Required Description
active boolean Optional Filter by client active status
corporate boolean Optional Filter by client type (true=corporate, false=individual)
branch_id integer Optional Filter by specific branch ID
search string Optional Search across first name, last name, corporate name, and trading name

Usage Examples

Basic usage - get all clients
GET /client/fetchAll
Get active clients only
GET /client/fetchAll?active=true&page=1&per_page=25
Search for clients
GET /client/fetchAll?search=Smith&corporate=false
Filter by branch
GET /client/fetchAll?branch_id=5&active=true
Corporate clients with pagination
GET /client/fetchAll?corporate=true&page=2&per_page=20

Response Format

{
  "success": true,
  "data": [
    {
      "id": 123,
      "first_name": "John",
      "last_name": "Smith",
      "preferred_name": "Johnny",
      "title": "Mr",
      "gender": "male",
      "preferred_pronoun": "he/him",
      "date_of_birth": "1985-06-15",
      "corporate_name": null,
      "corporate_trading_name": null,
      "corporate_acn": null,
      "corporate_abn": null,
      "is_active": true,
      "is_corporate": false,
      "is_mailable": true,
      "is_account_client": false,
      "branch_id": 5,
      "consultant_id": 10,
      "passenger_id": null,
      "referral_source_id": 3,
      "group_id": null,
      "date_created": "2024-01-15 09:30:00",
      "last_modified": "2024-01-15 10:45:00",
      "modified_by": 15,
      "contact": {
        "preferred_email": "john.smith@email.com",
        "preferred_phone": "+61 400 123 456",
        "preferred_address": "123 Collins Street, Suite 456, Melbourne, VIC, 3000, Australia"
      }
    },
    {
      "id": 124,
      "first_name": null,
      "last_name": null,
      "preferred_name": null,
      "title": null,
      "gender": "unspecified",
      "preferred_pronoun": null,
      "date_of_birth": null,
      "corporate_name": "ABC Corporation",
      "corporate_trading_name": "ABC Corp",
      "corporate_acn": "123456789",
      "corporate_abn": "12345678901",
      "is_active": true,
      "is_corporate": true,
      "is_mailable": false,
      "is_account_client": true,
      "branch_id": 3,
      "consultant_id": 15,
      "passenger_id": null,
      "referral_source_id": null,
      "group_id": 5,
      "date_created": "2024-01-10 14:20:00",
      "last_modified": "2024-01-12 16:30:00",
      "modified_by": 12,
      "contact": {
        "preferred_email": "accounts@abccorp.com.au",
        "preferred_phone": "+61 3 9876 5432",
        "preferred_address": "456 Business Ave, Corporate Park, Sydney, NSW, 2000, Australia"
      }
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "per_page": 50,
    "total_pages": 25,
    "has_next": true,
    "has_previous": false
  },
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Response Fields

Client Information

Field Type Description
id integer Unique client identifier
first_name string Client first name (null for corporate clients)
last_name string Client last name (null for corporate clients)
preferred_name string Client's preferred name
title string Client title (Mr, Mrs, Ms, Dr, etc.)
gender string Client's gender
preferred_pronoun string Client's preferred pronouns
date_of_birth date Client's date of birth (YYYY-MM-DD)

Corporate Information

Field Type Description
corporate_name string Corporate name (null for individual clients)
corporate_trading_name string Corporate trading name
corporate_acn string Australian Company Number
corporate_abn string Australian Business Number

Client Status & Relationships

Field Type Description
is_active boolean Whether the client is active
is_corporate boolean Whether the client is corporate or individual
is_mailable boolean Whether the client can receive mail
is_account_client boolean Whether this is an account client
branch_id integer Associated branch identifier
consultant_id integer Primary consultant identifier
passenger_id integer Associated passenger identifier
referral_source_id integer Referral source identifier
group_id integer Client group identifier

Timestamps & Contact Summary

Field Type Description
date_created datetime When the client was created
last_modified datetime When the client was last updated
modified_by integer User ID who last modified the client
contact.preferred_email string Client's preferred email address
contact.preferred_phone string Client's preferred phone number
contact.preferred_address string Client's preferred address (formatted)

Pagination

Field Type Description
total integer Total number of clients matching the filters
page integer Current page number
per_page integer Number of items per page
total_pages integer Total number of pages
has_next boolean Whether there is a next page
has_previous boolean Whether there is a previous page

Error Responses

Authentication error
{
  "success": false,
  "error": "Missing X-Api-Token header",
  "code": 401,
  "timestamp": "2024-01-15T09:30:00+00:00"
}
Invalid parameters
{
  "success": false,
  "error": "Invalid parameter value",
  "code": 400,
  "details": {
    "parameter": "per_page",
    "message": "Value must be between 1 and 100"
  },
  "timestamp": "2024-01-15T09:30:00+00:00"
}

Code Examples

JavaScript (Fetch)

const response = await fetch('/client/fetchAll?active=true&per_page=25', {
  headers: {
    'X-Api-Token': 'your_api_token_here'
  }
});

const data = await response.json();
if (data.success) {
  console.log('Clients:', data.data);
  console.log('Total:', data.pagination.total);
  
  // Process each client
  data.data.forEach(client => {
    const name = client.is_corporate
      ? client.corporate_name
      : `${client.first_name} ${client.last_name}`;
    console.log(`Client: ${name}, Email: ${client.contact.preferred_email}`);
  });
}

PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, '/client/fetchAll?active=true&per_page=25');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Token: your_api_token_here'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

if ($data['success']) {
    echo "Found " . $data['pagination']['total'] . " clients\n";
    
    foreach ($data['data'] as $client) {
        $name = $client['is_corporate']
            ? $client['corporate_name']
            : $client['first_name'] . ' ' . $client['last_name'];
        echo "Client: {$name}\n";
    }
}

Python (requests)

import requests

headers = {'X-Api-Token': 'your_api_token_here'}
params = {'active': 'true', 'per_page': 25}

response = requests.get('/client/fetchAll', headers=headers, params=params)
data = response.json()

if data['success']:
    print(f"Found {data['pagination']['total']} clients")
    
    for client in data['data']:
        name = (client['corporate_name'] if client['is_corporate']
                else f"{client['first_name']} {client['last_name']}")
        print(f"Client: {name}, Email: {client['contact']['preferred_email']}")