# Claims

> API reference · Wathiqaty Insurer API v1 (draft)

The full claim workflow: `submitted` → `under_review` ⇄ `documents_requested` → `approved` → `settled` → `closed`, or `rejected` → `closed`. The customer can withdraw before a decision. Your staff can work the same claims in the Wathiqaty portal at the same time; both see the same state.

Base URL: `https://sandbox-api.wathiqaty.com/api/v1` (sandbox), `https://api.wathiqaty.com/api/v1` (production).

- List claims: `GET /partner/claims`
- Get a claim: `GET /partner/claims/{id}`
- Set your claim number: `PUT /partner/claims/{id}/external-reference`
- Start reviewing: `POST /partner/claims/{id}/start-review`
- Request documents: `POST /partner/claims/{id}/document-requests`
- Accept or reject a document: `POST /partner/claims/{id}/documents/{documentId}/review`
- Preview an approval: `GET /partner/claims/{id}/approval-preview`
- Approve a claim: `POST /partner/claims/{id}/approve`
- Reject a claim: `POST /partner/claims/{id}/reject`
- Mark a claim paid: `POST /partner/claims/{id}/settle`
- Close a claim: `POST /partner/claims/{id}/close`
- List claim messages: `GET /partner/claims/{id}/messages`
- Message the customer: `POST /partner/claims/{id}/messages`

## List claims

`GET /partner/claims`

- Auth: Bearer token, scope `claims:read`

Drafts are never visible to you.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Claim status. One of: `submitted`, `under_review`, `documents_requested`, `approved`, `rejected`, `settled`, `closed`, `withdrawn`. |
| `policyId` | uuid | no | On this policy. |
| `categoryId` | uuid | no | Claim category. |
| `insuranceType` | string | no | Line of business. One of: `individual_medical`, `new_cars`. |
| `updatedSince` | date-time | no | Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed). |
| `page` | integer | no | Page number, from 1. Default 1. |
| `size` | integer | no | Items per page, 1–100. Default 20. |
| `sortOrder` | string | no | Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`. |

### Request examples

```bash
curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/claims" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.get(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Get,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

A page of claims.

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
        "number": "CLM-00000107",
        "externalReference": null,
        "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
        "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
        "status": "submitted",
        "incidentDate": "2026-12-01",
        "claimedAmount": "4200.00",
        "approvedAmount": null,
        "items": [
          {
            "lineId": "l1",
            "description": "Outpatient consultation",
            "claimedAmount": "700.00"
          },
          {
            "lineId": "l2",
            "description": "MRI scan",
            "claimedAmount": "3500.00"
          }
        ],
        "documents": [
          {
            "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
            "requirementKey": "medical_report",
            "status": "pending",
            "fileName": "report.pdf",
            "url": "https://files.wathiqaty.com/claims/report.pdf"
          }
        ],
        "documentRequests": [],
        "policyCoverage": {
          "sumInsured": "250000.00",
          "consumed": "0.00",
          "remaining": "250000.00"
        },
        "submittedAt": "2026-12-02T08:30:00.000Z",
        "updatedAt": "2026-12-02T08:30:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

## Get a claim

`GET /partner/claims/{id}`

- Auth: Bearer token, scope `claims:read`

With items, documents (download from `url`), open document requests and `policyCoverage` (what is left of the sum insured).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Request examples

```bash
curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.get(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Get,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "submitted",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Set your claim number

`PUT /partner/claims/{id}/external-reference`

- Auth: Bearer token, scope `claims:write`
- `If-Match`: supported

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `externalReference` | string | yes | Your own reference, 1–100 characters, unique within your company. |

### Request examples

```bash
curl -X PUT "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/external-reference" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: W/"7"" \
  -d '{"externalReference":"CL/2026/000981"}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/external-reference", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    "If-Match": "W/\"7\"",
  },
  body: JSON.stringify({
    "externalReference": "CL/2026/000981"
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.put(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/external-reference",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "If-Match": "W/\"7\"",
    },
    json={
      "externalReference": "CL/2026/000981"
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Put,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/external-reference");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Headers.TryAddWithoutValidation("If-Match", "W/\"7\"");
req.Content = new StringContent(
    """
    {
      "externalReference": "CL/2026/000981"
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": "CL/2026/000981",
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "submitted",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "PUT",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 412 | `version_conflict` | Changed since you read it (`If-Match` doesn't match). Reload and retry. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Start reviewing

`POST /partner/claims/{id}/start-review`

- Auth: Bearer token, scope `claims:write`

`submitted` → `under_review`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/start-review" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/start-review", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/start-review",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/start-review");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "under_review",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Request documents

`POST /partner/claims/{id}/document-requests`

- Auth: Bearer token, scope `claims:write`
- `Idempotency-Key`: optional

→ `documents_requested` (or adds to the open round). The customer is notified and resubmits (`claim.resubmitted`).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `requests` | object[] | yes | 1–20 of `{ requirementKey \| name (1–255), note?, dueDate? }`. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/document-requests" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"requests":[{"name":"Itemised hospital invoice","note":"Stamped by the hospital","dueDate":"2026-12-15"}]}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/document-requests", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "requests": [
      {
        "name": "Itemised hospital invoice",
        "note": "Stamped by the hospital",
        "dueDate": "2026-12-15"
      }
    ]
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests, uuid

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/document-requests",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "requests": [
        {
          "name": "Itemised hospital invoice",
          "note": "Stamped by the hospital",
          "dueDate": "2026-12-15"
        }
      ]
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/document-requests");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Headers.TryAddWithoutValidation("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(
    """
    {
      "requests": [
        {
          "name": "Itemised hospital invoice",
          "note": "Stamped by the hospital",
          "dueDate": "2026-12-15"
        }
      ]
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "documents_requested",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Accept or reject a document

`POST /partner/claims/{id}/documents/{documentId}/review`

- Auth: Bearer token, scope `claims:write`

Rejecting reopens a request for it and moves `under_review` → `documents_requested`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |
| `documentId` | uuid | yes | The document's id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | string | yes | Your decision. One of: `accepted`, `rejected`. |
| `reason` | string | no | 3–2000 characters. Required to reject. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/documents/{documentId}/review" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision":"rejected","reason":"The report is not signed."}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/documents/{documentId}/review", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "decision": "rejected",
    "reason": "The report is not signed."
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/documents/{documentId}/review",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
      "decision": "rejected",
      "reason": "The report is not signed."
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/documents/{documentId}/review");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Content = new StringContent(
    """
    {
      "decision": "rejected",
      "reason": "The report is not signed."
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "submitted",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim or document doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Preview an approval

`GET /partner/claims/{id}/approval-preview`

- Auth: Bearer token, scope `claims:read`

What the customer would be paid after the deductible, and what would remain of the cover. Changes nothing.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `approvedAmount` | decimal | yes | Amount you intend to approve, > 0. |

### Request examples

```bash
curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approval-preview?approvedAmount=<approvedAmount>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approval-preview?approvedAmount=<approvedAmount>", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.get(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approval-preview?approvedAmount=<approvedAmount>",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Get,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approval-preview?approvedAmount=<approvedAmount>");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The preview.

```json
{
  "status": "success",
  "data": {
    "deductibleApplied": "0.00",
    "payableAmount": "4200.00",
    "remainingAfter": "245800.00"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Approve a claim

`POST /partner/claims/{id}/approve`

- Auth: Bearer token, scope `claims:write`
- `Idempotency-Key`: optional

`under_review` → `approved`. Itemised claims list **every** item once (an item below its claimed amount needs a `reason`); other claims send `approvedAmount`. Every document must be reviewed first, and the total can't exceed what is left of the sum insured.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | object[] | no | Itemised claims: `{ lineId, approvedAmount, reason? }` for every item. |
| `approvedAmount` | decimal | no | Other claims: > 0 and ≤ the claimed amount. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approve" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items":[{"lineId":"l1","approvedAmount":"700.00"},{"lineId":"l2","approvedAmount":"3000.00","reason":"Network price for MRI is 3000"}]}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approve", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "items": [
      {
        "lineId": "l1",
        "approvedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "approvedAmount": "3000.00",
        "reason": "Network price for MRI is 3000"
      }
    ]
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests, uuid

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approve",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "items": [
        {
          "lineId": "l1",
          "approvedAmount": "700.00"
        },
        {
          "lineId": "l2",
          "approvedAmount": "3000.00",
          "reason": "Network price for MRI is 3000"
        }
      ]
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/approve");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Headers.TryAddWithoutValidation("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(
    """
    {
      "items": [
        {
          "lineId": "l1",
          "approvedAmount": "700.00"
        },
        {
          "lineId": "l2",
          "approvedAmount": "3000.00",
          "reason": "Network price for MRI is 3000"
        }
      ]
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim, now `approved`.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "approved",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": "3700.00",
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |
| 400 | `documents_pending` | A document is still pending (`details.pendingDocumentIds`). |
| 400 | `claim_not_payable` | Over the remaining cover (`details.remaining`, `details.sumInsured`, `details.consumed`). |
| 422 | `validation_error` | Wrong form for the claim, or items missing or repeated. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Reject a claim

`POST /partner/claims/{id}/reject`

- Auth: Bearer token, scope `claims:write`
- `Idempotency-Key`: optional

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | 3–2000 characters, shown to the customer. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/reject" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"The treatment is excluded under section 4.2 of the wording."}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/reject", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "reason": "The treatment is excluded under section 4.2 of the wording."
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests, uuid

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/reject",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "reason": "The treatment is excluded under section 4.2 of the wording."
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/reject");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Headers.TryAddWithoutValidation("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(
    """
    {
      "reason": "The treatment is excluded under section 4.2 of the wording."
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim, now `rejected`.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "rejected",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Mark a claim paid

`POST /partner/claims/{id}/settle`

- Auth: Bearer token, scope `claims:write`
- `Idempotency-Key`: optional

`approved` → `settled`, with your payment reference.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `settlementReference` | string | yes | 1–255 characters. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/settle" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"settlementReference":"PAY-2026-55120"}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/settle", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "settlementReference": "PAY-2026-55120"
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests, uuid

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/settle",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "settlementReference": "PAY-2026-55120"
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/settle");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Headers.TryAddWithoutValidation("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(
    """
    {
      "settlementReference": "PAY-2026-55120"
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim, now `settled`.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "settled",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Close a claim

`POST /partner/claims/{id}/close`

- Auth: Bearer token, scope `claims:write`

`settled` or `rejected` → `closed`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/close" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/close", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/close",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/close");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

The claim, now `closed`.

```json
{
  "status": "success",
  "data": {
    "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "number": "CLM-00000107",
    "externalReference": null,
    "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "status": "closed",
    "incidentDate": "2026-12-01",
    "claimedAmount": "4200.00",
    "approvedAmount": null,
    "items": [
      {
        "lineId": "l1",
        "description": "Outpatient consultation",
        "claimedAmount": "700.00"
      },
      {
        "lineId": "l2",
        "description": "MRI scan",
        "claimedAmount": "3500.00"
      }
    ],
    "documents": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "requirementKey": "medical_report",
        "status": "pending",
        "fileName": "report.pdf",
        "url": "https://files.wathiqaty.com/claims/report.pdf"
      }
    ],
    "documentRequests": [],
    "policyCoverage": {
      "sumInsured": "250000.00",
      "consumed": "0.00",
      "remaining": "250000.00"
    },
    "submittedAt": "2026-12-02T08:30:00.000Z",
    "updatedAt": "2026-12-02T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | Not allowed in the current status (`details.from`, `details.to`). |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## List claim messages

`GET /partner/claims/{id}/messages`

- Auth: Bearer token, scope `claims:read`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | uuid | no | Messages after this message id. |
| `limit` | integer | no | 1–100. Default 50. |

### Request examples

```bash
curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.get(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Get,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 200

Messages, oldest first.

```json
{
  "status": "success",
  "data": [
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "author": "customer",
      "body": "I uploaded the stamped invoice.",
      "attachments": [],
      "createdAt": "2026-12-03T09:00:00.000Z"
    }
  ],
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).

## Message the customer

`POST /partner/claims/{id}/messages`

- Auth: Bearer token, scope `claims:write`

A public reply on the claim. Retries with the same `clientMessageId` don't post twice.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | The claim's Wathiqaty id. |

### Body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | 1–5000 characters. |
| `clientMessageId` | uuid | no | Your id for the message, for safe retries. |

### Request examples

```bash
curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Thank you, we are reviewing the invoice.","clientMessageId":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"}'
```

```js
const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "body": "Thank you, we are reviewing the invoice.",
    "clientMessageId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
  }),
})
const { data, error } = await res.json()
if (!res.ok) throw new Error(`${res.status} ${error.code}`)
```

```python
import requests

res = requests.post(
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
      "body": "Thank you, we are reviewing the invoice.",
      "clientMessageId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
    },
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {payload['error']['code']}")
data = payload["data"]
```

```csharp
using var req = new HttpRequestMessage(HttpMethod.Post,
    "https://sandbox-api.wathiqaty.com/api/v1/partner/claims/{id}/messages");
req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {accessToken}");
req.Content = new StringContent(
    """
    {
      "body": "Thank you, we are reviewing the invoice.",
      "clientMessageId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
    }
    """,
    Encoding.UTF8, "application/json");
using var res = await http.SendAsync(req);
var json = await res.Content.ReadAsStringAsync();
res.EnsureSuccessStatusCode();
```

### Response 201

The message.

```json
{
  "status": "success",
  "data": {
    "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
    "author": "insurer",
    "body": "Thank you, we are reviewing the invoice.",
    "attachments": [],
    "createdAt": "2026-12-03T09:05:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}
```

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Claim doesn't exist or isn't your company's. |
| 400 | `bad_request` | The claim is closed or withdrawn. |

Plus the generic errors any route can return: [Errors](/guides/errors.md).