Contracts
List contracts (paged, filterable). Billing-adjacent client data - requires module_client.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| search | query | string | |
| page | query | integer | |
| limit | query | integer | |
| status | query | string | Raw contract_status value (e.g. Active, Expired, Cancelled) - manually set, not auto-derived from dates |
| client_id | query | integer | |
| expiring | query | integer (0 | 1) | Only contracts already past renewal_date or due within 45 days |
Example request
curl "https://YOUR-HOST/api/v1/contracts" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/contracts",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/contracts", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/contracts");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Paged contract list
| Field | Type | Description |
|---|---|---|
| data | array of object | |
| data[].id | integer | |
| data[].name | string | |
| data[].type | string | |
| data[].status | string | Raw contract_status value - manually set, may disagree with renewal_date; see is_expired/is_due_soon |
| data[].client | string | |
| data[].value | number | |
| data[].renewal_frequency | string | |
| data[].start_date | string | |
| data[].end_date | string | |
| data[].renewal_date | string | |
| data[].is_expired | boolean | |
| data[].is_due_soon | boolean | renewal_date is today or within the next 45 days |
| data[].has_sla | boolean | |
| data[].has_allowance | boolean | |
| total | integer | |
| page | integer | |
| limit | integer |
Example response
json
{
"data": [
{
"id": 1,
"name": "string",
"type": "string",
"status": "string",
"client": "string",
"value": 1.5,
"renewal_frequency": "string",
"start_date": "string",
"end_date": "string",
"renewal_date": "string",
"is_expired": true,
"is_due_soon": true,
"has_sla": true,
"has_allowance": true
}
],
"total": 1,
"page": 1,
"limit": 1
}
Contract detail with SLA, current-month hours-allowance usage, and documents
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer | |
| month | query | integer | Allowance month, 1-12, defaults to current month |
| year | query | integer | Allowance year, defaults to current year |
Example request
curl "https://YOUR-HOST/api/v1/contracts/1" \
-H "Authorization: Bearer $TOKEN"
import requests
response = requests.get(
"https://YOUR-HOST/api/v1/contracts/1",
headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/contracts/1", {
method: "GET",
headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/contracts/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);
Responses
200Contract detail
| Field | Type | Description |
|---|---|---|
| id | integer | |
| name | string | |
| type | string | |
| status | string | |
| client | string | |
| value | number | |
| renewal_frequency | string | |
| start_date | string | |
| end_date | string | |
| renewal_date | string | |
| is_expired | boolean | |
| is_due_soon | boolean | |
| details | string | |
| sla | object | |
| sla.high | object | |
| sla.high.response_time | integer | Hours; null when not configured |
| sla.high.resolution_time | integer | Hours; null when not configured |
| sla.medium | object | |
| sla.medium.response_time | integer | Hours; null when not configured |
| sla.medium.resolution_time | integer | Hours; null when not configured |
| sla.low | object | |
| sla.low.response_time | integer | Hours; null when not configured |
| sla.low.resolution_time | integer | Hours; null when not configured |
| allowance | object | Same shape as the month/year/remote/onsite fields of AllowanceUsage, for this one contract |
| allowance.month | integer | |
| allowance.year | integer | |
| allowance.remote | object | Included vs. used hours for one delivery method (remote or onsite) over the requested month. When this allowance isn't configured (no active contract sets it), included/remaining/pct are null and used is 0 - treat null 'included' as "feature inactive" and don't render this period. |
| allowance.remote.included | number | Hours included, or null if this allowance is not configured |
| allowance.remote.used | number | Hours used so far this month (flat per-ticket rate, not actual worked time); 0 when included is null |
| allowance.remote.remaining | number | included - used; negative when over allowance; null when included is null |
| allowance.remote.pct | number | used / included as a percentage, capped at 100; null when included is null |
| allowance.onsite | object | Included vs. used hours for one delivery method (remote or onsite) over the requested month. When this allowance isn't configured (no active contract sets it), included/remaining/pct are null and used is 0 - treat null 'included' as "feature inactive" and don't render this period. |
| allowance.onsite.included | number | Hours included, or null if this allowance is not configured |
| allowance.onsite.used | number | Hours used so far this month (flat per-ticket rate, not actual worked time); 0 when included is null |
| allowance.onsite.remaining | number | included - used; negative when over allowance; null when included is null |
| allowance.onsite.pct | number | used / included as a percentage, capped at 100; null when included is null |
| documents | array of object | |
| documents[].id | integer | |
| documents[].name | string | |
| documents[].mime_type | string | |
| documents[].size | integer | |
| documents[].uploaded_at | string | |
| documents[].url | string | |
| created_at | string | |
| updated_at | string |
Example response
json
{
"id": 1,
"name": "string",
"type": "string",
"status": "string",
"client": "string",
"value": 1.5,
"renewal_frequency": "string",
"start_date": "string",
"end_date": "string",
"renewal_date": "string",
"is_expired": true,
"is_due_soon": true,
"details": "string",
"sla": {
"high": {
"response_time": 1,
"resolution_time": 1
},
"medium": {
"response_time": 1,
"resolution_time": 1
},
"low": {
"response_time": 1,
"resolution_time": 1
}
},
"allowance": {
"month": 1,
"year": 1,
"remote": {
"included": 1.5,
"used": 1.5,
"remaining": 1.5,
"pct": 1.5
},
"onsite": {
"included": 1.5,
"used": 1.5,
"remaining": 1.5,
"pct": 1.5
}
},
"documents": [
{
"id": 1,
"name": "string",
"mime_type": "string",
"size": 1,
"uploaded_at": "string",
"url": "string"
}
],
"created_at": "string",
"updated_at": "string"
}
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |