# EnRep Client API Manual

## Overview

The EnRep Client API allows your authorised systems to read selected EnRep data for integration with external platforms, asset systems, dashboards, and compliance workflows.

The API is currently read-only. Limited write access may be added in a future API version.

## Base URL

Use your EnRep domain:

```text
https://your-enrep-domain.co.uk/api/v1/
```

EnRep will confirm the correct base URL for your organisation.

## Authentication

Each request must include your API key:

```http
Authorization: Bearer YOUR_API_KEY
```

Your API key is generated by your EnRep administrator. The full key is shown once when generated. Regenerating the key invalidates the previous key.

## Response Format

Successful responses use:

```json
{
  "ok": true,
  "data": []
}
```

Errors use:

```json
{
  "ok": false,
  "error": "Invalid API key"
}
```

## Pagination

List endpoints support:

```text
?page=1&per_page=100
```

The maximum `per_page` value is `500`.

## Date Filters

By default, ambiguous dates are interpreted in UK format:

```text
date_format=uk
31-05-2026
31/05/2026
```

For US-style dates, include:

```text
date_format=us
05-31-2026
05/31/2026
```

ISO dates are also accepted:

```text
2026-05-31
```

## Endpoints

### Status

```http
GET /api/v1/status.php
```

Returns the API service name, version, and environment reference.

### Clients

```http
GET /api/v1/clients.php
GET /api/v1/clients.php?clientnumber=1001
```

Returns live client profiles available within your EnRep system.

Supported filters:

| Parameter      | Description                      | Example |
| -------------- | -------------------------------- | ------- |
| `clientnumber` | Return one client profile.       | `1001`  |
| `page`         | Page number for list responses.  | `1`     |
| `per_page`     | Records per page, maximum `500`. | `100`   |

### Locations

```http
GET /api/v1/locations.php
GET /api/v1/locations.php?clientnumber=1001
GET /api/v1/locations.php?locnumber=123
```

Returns live sites/locations.

Supported filters:

| Parameter      | Description                      | Example |
| -------------- | -------------------------------- | ------- |
| `clientnumber` | Return locations for one client. | `1001`  |
| `locnumber`    | Return one location.             | `123`   |
| `page`         | Page number for list responses.  | `1`     |
| `per_page`     | Records per page, maximum `500`. | `100`   |

### Assets

```http
GET /api/v1/assets.php
GET /api/v1/assets.php?clientnumber=1001
GET /api/v1/assets.php?locnumber=123
GET /api/v1/assets.php?clientnumber=1001&locnumber=123
GET /api/v1/assets.php?itemnumber=456
```

Returns live assets/equipment. Use `include_archived=1` only where EnRep has confirmed archived records should be included.

Filters can be chained where it makes sense. For example, `clientnumber=1001&locnumber=123` returns assets for one site belonging to one client.

Supported filters:

| Parameter                   | Description                                                          | Example      |
| --------------------------- | -------------------------------------------------------------------- | ------------ |
| `clientnumber`              | Return assets for one client.                                        | `1001`       |
| `locnumber`                 | Return assets for one location. Can be combined with `clientnumber`. | `123`        |
| `itemnumber`                | Return one asset. Can be combined with `clientnumber`.               | `456`        |
| `include_archived`          | Include archived assets where agreed.                                | `1`          |
| `last_examination_date`     | Return assets last examined on this exact date.                      | `15-01-2026` |
| `last_examination_from`     | Return assets examined on or after this date.                        | `01-01-2026` |
| `last_examination_to`       | Return assets examined on or before this date.                       | `31-01-2026` |
| `next_examination_due_date` | Return assets due on this exact date.                                | `15-06-2026` |
| `next_examination_due_from` | Return assets due on or after this date.                             | `01-06-2026` |
| `next_examination_due_to`   | Return assets due on or before this date.                            | `30-06-2026` |
| `date_format`               | Interpret ambiguous dates as UK or US format.                        | `uk`         |
| `page`                      | Page number for list responses.                                      | `1`          |
| `per_page`                  | Records per page, maximum `500`.                                     | `100`        |

### Reports

```http
GET /api/v1/reports.php
GET /api/v1/reports.php?clientnumber=1001
GET /api/v1/reports.php?clientnumber=1001&locnumber=123
GET /api/v1/reports.php?itemnumber=456
GET /api/v1/reports.php?clientnumber=1001&itemnumber=456
GET /api/v1/reports.php?repnumber=789
```

Returns report metadata for assets in your EnRep system.

Use `include_report_data=1` to include decoded report answer data where stored as JSON.

Filters can be chained where it makes sense. For example, `clientnumber=1001&itemnumber=456` returns reports for one asset belonging to one client.

Supported filters:

| Parameter                   | Description                                                           | Example      |
| --------------------------- | --------------------------------------------------------------------- | ------------ |
| `clientnumber`              | Return reports for one client.                                        | `1001`       |
| `locnumber`                 | Return reports for one location. Can be combined with `clientnumber`. | `123`        |
| `itemnumber`                | Return reports for one asset. Can be combined with `clientnumber`.    | `456`        |
| `repnumber`                 | Return one report. Can be combined with `clientnumber`.               | `789`        |
| `examination_date`          | Return reports examined on this exact date.                           | `15-01-2026` |
| `examination_from`          | Return reports examined on or after this date.                        | `01-01-2026` |
| `examination_to`            | Return reports examined on or before this date.                       | `31-01-2026` |
| `next_examination_due_date` | Return reports with next due date on this exact date.                 | `15-06-2026` |
| `next_examination_due_from` | Return reports with next due date on or after this date.              | `01-06-2026` |
| `next_examination_due_to`   | Return reports with next due date on or before this date.             | `30-06-2026` |
| `report_created_date`       | Return reports created on this exact date.                            | `15-01-2026` |
| `report_created_from`       | Return reports created on or after this date.                         | `01-01-2026` |
| `report_created_to`         | Return reports created on or before this date.                        | `31-01-2026` |
| `date_format`               | Interpret ambiguous dates as UK or US format.                         | `uk`         |
| `include_report_data`       | Include decoded report answer data where available.                   | `1`          |
| `page`                      | Page number for list responses.                                       | `1`          |
| `per_page`                  | Records per page, maximum `500`.                                      | `100`        |

## API Reference

The sections below describe the fields returned by each endpoint. Fields may be returned as an empty string where the information is not recorded for a particular client, site, asset, or report.

### Standard Response Fields

| Field   | Type            | Description                                  | Example                                   |
| ------- | --------------- | -------------------------------------------- | ----------------------------------------- |
| `ok`    | boolean         | Whether the request succeeded.               | `true`                                    |
| `data`  | object or array | The returned record or list of records.      | `[]`                                      |
| `meta`  | object or null  | Pagination information for list responses.   | `{"page":1,"per_page":100,"returned":25}` |
| `error` | string          | Error message returned when `ok` is `false`. | `Invalid API key`                         |

### Pagination Fields

| Field      | Type    | Description                                  | Example |
| ---------- | ------- | -------------------------------------------- | ------- |
| `page`     | integer | Current result page.                         | `1`     |
| `per_page` | integer | Maximum records requested per page.          | `100`   |
| `returned` | integer | Number of records returned in this response. | `25`    |

### Status Fields

Returned by:

```http
GET /api/v1/status.php
```

| Field         | Type   | Description                  | Example            |
| ------------- | ------ | ---------------------------- | ------------------ |
| `service`     | string | API service name.            | `EnRep Client API` |
| `version`     | string | API version.                 | `v1`               |
| `environment` | string | EnRep environment reference. | `/example`         |

### Client Fields

Returned by:

```http
GET /api/v1/clients.php
```

| Field                       | Type    | Description                                | Example                   |
| --------------------------- | ------- | ------------------------------------------ | ------------------------- |
| `clientnumber`              | integer | EnRep client reference number.             | `1001`                    |
| `client_name`               | string  | Client name.                               | `Example Engineering Ltd` |
| `address.address_line_1`    | string  | First address line.                        | `Unit 1`                  |
| `address.address_line_2`    | string  | Second address line.                       | `Industrial Estate`       |
| `address.town`              | string  | Town or city.                              | `Bristol`                 |
| `address.county`            | string  | County.                                    | `Somerset`                |
| `address.postcode`          | string  | Postcode.                                  | `BS1 1AA`                 |
| `telephone`                 | string  | Main telephone number.                     | `0117 000 0000`           |
| `secondary_telephone`       | string  | Secondary telephone number.                | `0117 000 0001`           |
| `mobile`                    | string  | Mobile number.                             | `07123 456789`            |
| `email`                     | string  | Main email address.                        | `contact@example.co.uk`   |
| `primary_contact.name`      | string  | Primary contact name.                      | `Jane Smith`              |
| `primary_contact.position`  | string  | Primary contact job title or role.         | `Facilities Manager`      |
| `primary_contact.telephone` | string  | Primary contact telephone number.          | `0117 000 0002`           |
| `primary_contact.mobile`    | string  | Primary contact mobile number.             | `07123 456780`            |
| `primary_contact.email`     | string  | Primary contact email address.             | `jane@example.co.uk`      |
| `contract_number`           | string  | Contract or account reference, where used. | `CON-1001`                |
| `ancillary_reference`       | string  | Additional client reference, where used.   | `A-123`                   |

### Location Fields

Returned by:

```http
GET /api/v1/locations.php
GET /api/v1/locations.php?locnumber=123
```

| Field                        | Type    | Description                           | Example                |
| ---------------------------- | ------- | ------------------------------------- | ---------------------- |
| `clientnumber`               | integer | EnRep client reference number.        | `1001`                 |
| `locnumber`                  | integer | EnRep site/location reference number. | `123`                  |
| `site_name`                  | string  | Site or location name.                | `Main Warehouse`       |
| `site_reference`             | string  | Site reference, where recorded.       | `WH-01`                |
| `address.address_line_1`     | string  | First site address line.              | `Warehouse 1`          |
| `address.address_line_2`     | string  | Second site address line.             | `Trading Estate`       |
| `address.address_line_3`     | string  | Third site address line.              | `North Road`           |
| `address.address_line_4`     | string  | Fourth site address line.             | `Bristol`              |
| `address.postcode`           | string  | Site postcode.                        | `BS1 1AA`              |
| `telephone`                  | string  | Site telephone number.                | `0117 000 0000`        |
| `secondary_telephone`        | string  | Secondary site telephone number.      | `0117 000 0001`        |
| `mobile`                     | string  | Site mobile number.                   | `07123 456789`         |
| `email`                      | string  | Site email address.                   | `site@example.co.uk`   |
| `contacts.local_contact`     | string  | Local site contact.                   | `John Smith`           |
| `contacts.property_manager`  | string  | Property manager or site manager.     | `Jane Smith`           |
| `contacts.contact_telephone` | string  | Site contact telephone number.        | `0117 000 0002`        |
| `contacts.other_contact`     | string  | Other contact information.            | `Security desk`        |
| `notes`                      | string  | Site notes, where available.          | `Access via rear gate` |

### Asset Fields

Returned by:

```http
GET /api/v1/assets.php
GET /api/v1/assets.php?locnumber=123
GET /api/v1/assets.php?itemnumber=456
```

| Field                       | Type    | Description                                                          | Example                     |
| --------------------------- | ------- | -------------------------------------------------------------------- | --------------------------- |
| `clientnumber`              | integer | EnRep client reference number.                                       | `1001`                      |
| `locnumber`                 | integer | EnRep site/location reference number.                                | `123`                       |
| `itemnumber`                | integer | EnRep asset reference number.                                        | `456`                       |
| `site_name`                 | string  | Site or location name.                                               | `Main Warehouse`            |
| `site_postcode`             | string  | Site postcode.                                                       | `BS1 1AA`                   |
| `asset_code`                | string  | Asset type or category code.                                         | `LIFT`                      |
| `asset_description`         | string  | Description/name of the asset or equipment.                          | `Passenger lift`            |
| `safe_working_load`         | string  | Safe working load or rating, where applicable.                       | `630 kg`                    |
| `plant_number`              | string  | Plant or asset number.                                               | `LIFT-01`                   |
| `serial_number`             | string  | Serial number.                                                       | `ABC123`                    |
| `ancillary_number`          | string  | Ancillary asset number, where used.                                  | `ANC-01`                    |
| `manufacturer`              | string  | Manufacturer name.                                                   | `Example Manufacturer`      |
| `model`                     | string  | Model reference.                                                     | `X100`                      |
| `date_of_manufacture`       | string  | Date or year of manufacture, where recorded.                         | `2020`                      |
| `sub_location`              | string  | Sub-location within the site.                                        | `Loading bay`               |
| `detailed_location`         | string  | More detailed location information.                                  | `Bay 3, north wall`         |
| `last_examination_date`     | string  | Last examination date, formatted as `YYYY-MM-DD` where possible.     | `2026-01-10`                |
| `next_examination_due_date` | string  | Next examination due date, formatted as `YYYY-MM-DD` where possible. | `2026-07-10`                |
| `last_examination_result`   | string  | Last recorded examination result.                                    | `PASS`                      |
| `condition`                 | string  | Asset condition, where recorded.                                     | `Good`                      |
| `regulations`               | string  | Applicable regulation or inspection regime, where recorded.          | `LOLER`                     |
| `report_type`               | string  | Default or expected report type reference.                           | `500`                       |
| `linked_chain`              | string  | Linked chain/group reference, where used.                            | `CHAIN-001`                 |
| `nfc_reference`             | string  | NFC/EnTag reference, where assigned.                                 | `04AABBCCDD`                |
| `notes`                     | string  | Asset notes, where available.                                        | `Located beside goods lift` |
| `is_live`                   | boolean | Whether the asset is currently live.                                 | `true`                      |

### Report Fields

Returned by:

```http
GET /api/v1/reports.php
GET /api/v1/reports.php?itemnumber=456
GET /api/v1/reports.php?repnumber=789
```

| Field                       | Type           | Description                                                                | Example                      |
| --------------------------- | -------------- | -------------------------------------------------------------------------- | ---------------------------- |
| `repnumber`                 | string         | EnRep report reference number.                                             | `789`                        |
| `master_report_id`          | string         | Master report reference, where used.                                       | `MR-789`                     |
| `previous_report_number`    | string         | Previous report number, where recorded.                                    | `700`                        |
| `previous_examination_date` | string         | Previous examination date, formatted as `YYYY-MM-DD` where possible.       | `2025-07-10`                 |
| `examination_date`          | string         | Examination date, formatted as `YYYY-MM-DD` where possible.                | `2026-01-10`                 |
| `next_examination_due_date` | string         | Next examination due date, formatted as `YYYY-MM-DD` where possible.       | `2026-07-10`                 |
| `report_created_date`       | string         | Date the report was created, formatted as `YYYY-MM-DD` where possible.     | `2026-01-11`                 |
| `delivery_status`           | integer        | Delivery status reference.                                                 | `1`                          |
| `clientnumber`              | integer        | EnRep client reference number.                                             | `1001`                       |
| `itemnumber`                | integer        | EnRep asset reference number.                                              | `456`                        |
| `locnumber`                 | integer        | EnRep site/location reference number.                                      | `123`                        |
| `asset_description`         | string         | Description/name of the inspected asset.                                   | `Passenger lift`             |
| `plant_number`              | string         | Plant or asset number.                                                     | `LIFT-01`                    |
| `serial_number`             | string         | Serial number.                                                             | `ABC123`                     |
| `surveyor_reference`        | string         | Surveyor or engineer reference.                                            | `12`                         |
| `examination_frequency`     | string         | Examination frequency, where recorded.                                     | `6`                          |
| `report_type`               | string         | Report type reference.                                                     | `500`                        |
| `examination_result`        | string         | Recorded examination result.                                               | `PASS`                       |
| `report_data`               | object or null | Additional report answer data. Only returned when `include_report_data=1`. | `{"obs":"No defects noted"}` |

### Parsing Report Data

When `include_report_data=1` is used, `report_data` is returned as a JSON object, not as a text string. The keys inside `report_data` depend on the report type and the answers recorded on the report.

PHP example:

```php
$reportData = $report['report_data'] ?? [];
$observations = $reportData['obs'] ?? '';
```

Server-side JavaScript example:

```javascript
const reportData = report.report_data || {};
const observations = reportData.obs || "";
```

If `report_data` is `null`, no decoded report answer data was available for that report.

## Usage Examples

Replace the example base URL and API key with the details issued to you by EnRep.

### Check API Availability

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/status.php" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### List Clients

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/clients.php?page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### List Sites

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/locations.php?page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### List Assets for One Site

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/assets.php?locnumber=123&page=1&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get One Asset

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/assets.php?itemnumber=456" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Reports for One Asset

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/reports.php?itemnumber=456&page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get One Report

```bash
curl -X GET "https://your-enrep-domain.co.uk/api/v1/reports.php?repnumber=789" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### PHP Example

```php
<?php
$baseUrl = 'https://your-enrep-domain.co.uk/api/v1';
$apiKey = getenv('ENREP_API_KEY');

$ch = curl_init($baseUrl . '/assets.php?per_page=100');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException('EnRep API request failed: ' . $response);
}

$payload = json_decode($response, true);
foreach ($payload['data'] ?? [] as $asset) {
    echo $asset['itemnumber'] . ' - ' . $asset['asset_description'] . PHP_EOL;
}
```

### Server-Side JavaScript Example

Do not expose your API key in browser-side JavaScript. Use this pattern only from a secure server-side process.

```javascript
const baseUrl = "https://your-enrep-domain.co.uk/api/v1";
const apiKey = process.env.ENREP_API_KEY;

async function getDueAssets() {
  const response = await fetch(`${baseUrl}/assets.php?per_page=100`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  });

  const payload = await response.json();
  if (!response.ok) {
    throw new Error(payload.error || "EnRep API request failed");
  }

  return payload.data.filter((asset) => asset.next_examination_due_date);
}

getDueAssets()
  .then((assets) => console.log(assets))
  .catch((error) => console.error(error));
```

### Common Integration Patterns

Pull all live assets:

```text
GET /api/v1/assets.php?page=1&per_page=500
```

Pull live assets for one client:

```text
GET /api/v1/assets.php?clientnumber=1001&page=1&per_page=500
```

Pull all reports for an asset:

```text
GET /api/v1/reports.php?itemnumber=456
```

Pull reports for one client and one site:

```text
GET /api/v1/reports.php?clientnumber=1001&locnumber=123
```

Pull reports for one client and one asset:

```text
GET /api/v1/reports.php?clientnumber=1001&itemnumber=456
```

Pull a specific report:

```text
GET /api/v1/reports.php?repnumber=789
```

Pull reports examined in a UK date range:

```text
GET /api/v1/reports.php?examination_from=01-05-2026&examination_to=31-05-2026&date_format=uk
```

Pull assets due in a US date range:

```text
GET /api/v1/assets.php?next_examination_due_from=05-01-2026&next_examination_due_to=05-31-2026&date_format=us
```

Build an asset dashboard using these fields:

```text
itemnumber
site_name
asset_description
plant_number
serial_number
safe_working_load
last_examination_date
next_examination_due_date
last_examination_result
```

Build an examination history using these fields:

```text
repnumber
itemnumber
asset_description
examination_date
next_examination_due_date
examination_result
report_type
examination_frequency
```

## Example Asset Response

```json
{
  "ok": true,
  "data": {
    "clientnumber": 1001,
    "locnumber": 25,
    "itemnumber": 456,
    "site_name": "Main Warehouse",
    "asset_description": "Passenger lift",
    "plant_number": "LIFT-01",
    "serial_number": "ABC123",
    "manufacturer": "Example Manufacturer",
    "model": "X100",
    "safe_working_load": "630 kg",
    "last_examination_date": "2026-01-10",
    "next_examination_due_date": "2026-07-10",
    "last_examination_result": "PASS",
    "nfc_reference": "..."
  },
  "meta": null
}
```

## Security Notes

Keep the API key private. Do not place it in public websites, mobile apps, or client-side JavaScript.

If a key is lost or exposed, ask EnRep to regenerate it. The previous key will stop working.

## Future Write Access

This version is read-only. If write access is introduced later, it will be added through a future version or explicit write endpoints with separate validation and audit controls.
