# UHS-DTS Information API

This API lets an authorized external system read DTS management information.

## Base URL

```text
https://dts.datacolabx.com
```

## Authentication

Send the shared key with every request.

```http
Accept: application/json
X-DTS-Api-Key: <shared-dts-api-key>
```

Configure the same key in DTS:

```dotenv
DTS_INFORMATION_API_KEY=<shared-dts-api-key>
```

## Get Information

```http
GET /api/dts/information
```

The available sections are:

- `summary`
- `users`
- `organizations`
- `document_types`
- `workflow_templates`
- `role_permissions`
- `document_requests`
- `audit_trails`

Use `include` to request only the sections your integration needs.

```http
GET /api/dts/information?include=document_requests
```

## Query Parameters

| Parameter | Example | Description |
| --- | --- | --- |
| `include` | `summary,document_requests` | Comma-separated response sections. Omit it to return every section. |
| `per_page` | `100` | Maximum records returned per section. Default `100`, maximum `500`. |
| `date` | `2026-07-13` | Return requests created on one date. |
| `date_from` | `2026-07-01` | Start of a request-created date range. |
| `date_to` | `2026-07-13` | End of a request-created date range. |
| `document_type` | `Academic Transcript` | Exact document type name. |
| `status` | `In Progress` | Dashboard status label or its lowercase slug. |
| `search` | `2026-0042` | Search document name, document ID, UHS code, document type, registry number, or finished number. |

Supported status filters:

- `All` or `all` (the same as omitting `status`)
- `In Progress` or `in-progress`
- `Overdue SLA` or `overdue-sla`
- `Approved` or `approved`
- `Completed` or `completed`
- `Rejected` or `rejected`

`date` is intended for a single day. For a period, use `date_from` and `date_to` instead.

## Filter Examples

All document requests created in a period:

```http
GET /api/dts/information?include=document_requests&date_from=2026-07-01&date_to=2026-07-13
```

Only completed Academic Transcript requests:

```http
GET /api/dts/information?include=document_requests&document_type=Academic%20Transcript&status=completed
```

Search by UHS code or another document value:

```http
GET /api/dts/information?include=document_requests&search=2026-0042
```

## Document Request Response

Document requests contain readable labels instead of internal workflow objects. The API does not expose the public tracking token or workflow template.

```json
{
  "success": true,
  "generated_at": "2026-07-13T08:00:00.000000Z",
  "sections": ["document_requests"],
  "data": {
    "document_requests": {
      "total": 25,
      "status_summary": {
        "total": 25,
        "items": [
          { "label": "In Progress", "key": "in-progress", "count": 18 },
          { "label": "Overdue SLA", "key": "overdue-sla", "count": 2 },
          { "label": "Approved", "key": "approved", "count": 0 },
          { "label": "Completed", "key": "completed", "count": 5 },
          { "label": "Rejected", "key": "rejected", "count": 0 }
        ]
      },
      "items": [
        {
          "id": 125,
          "uhs_code": "2026-0042",
          "registry_document_number": "2026-0015",
          "finished_document_number": "2026-0009",
          "document_name": "Academic Transcript Request",
          "document_code": "UHS75",
          "document_type": "Academic Transcript",
          "description": "Submitted from AMS Student.",
          "dashboard_status": "In Progress",
          "submitter": "Barang LeangHour",
          "current_holder": "Central Office",
          "created_at": "2026-07-13T07:40:00.000000Z",
          "updated_at": "2026-07-13T08:00:00.000000Z"
        }
      ]
    }
  }
}
```

Without a `status` filter, `status_summary.items` contains every supported status. When a status is selected, both the records and summary are limited to that status:

```json
{
  "total": 5,
  "status_summary": {
    "total": 5,
    "items": [
      { "label": "Completed", "key": "completed", "count": 5 }
    ]
  }
}
```

The applied filters and available filter list are intentionally documented here and are not repeated in every API response.

## cURL Example

```bash
curl -X GET "https://dts.datacolabx.com/api/dts/information?include=summary,document_requests&status=in-progress" \
  -H "Accept: application/json" \
  -H "X-DTS-Api-Key: <shared-dts-api-key>"
```

## Errors

Invalid or missing API key:

```json
{
  "success": false,
  "message": "Unauthorized DTS information API key."
}
```

Invalid filters return HTTP `422` with Laravel validation details.

## Notes

- Passwords and remember tokens are never returned.
- Document requests and audit trails return the latest records first.
- A current holder can be a user or an organization responsible for the active stage.
- Completed and rejected requests have an empty current holder.