---
url: /api/cost-codes.md
---
# List Cost Codes

Returns the cost codes a company uses. A cost code says **what the money is for** (security, plaster, site utilities...). Use a `value` from here as `costCode` when you [create a request](/api/create-request).

## Endpoint

| Method | URL |
|---|---|
| `GET` | `/api/companies/:companyID/cost-codes` |

| Path parameter | Description |
|---|---|
| `companyID` | An `id` from [List Companies](/api/companies) |

```
<timestamp>.GET./api/companies/6650f1a2b3c4d5e6f7a8b901/cost-codes.
```

## Response

`data` is an array of cost codes, sorted by `value` (complete in one response, not paginated):

| Field | Type | Description |
|---|---|---|
| `value` | `string` | The cost code. Use it as `costCode` |
| `label` | `string` | Code and name together, good for showing to people |
| `category` | `string` | The group the code belongs to, e.g. `"contractor"` or `"developer"`. The groups differ between companies and new ones can be added, so do not hard-code a list. For display and filtering only; you never send it back |

## Example

::: code-group

```bash [cURL]
COMPANY_ID="6650f1a2b3c4d5e6f7a8b901"
TS=$(date +%s)
SIG=$(printf '%s' "$TS.GET./api/companies/$COMPANY_ID/cost-codes." \
  | openssl dgst -sha256 -hmac "$SIGNING_SECRET" \
  | sed 's/^.* //')
curl "$BASE_URL/api/companies/$COMPANY_ID/cost-codes" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TS" \
  -H "x-signature: $SIG"
```

```js [Node.js]
const companyID = "6650f1a2b3c4d5e6f7a8b901";
const result = await callJohari("GET", `/api/companies/${companyID}/cost-codes`);
console.log(result.data);
```

```python [Python]
company_id = "6650f1a2b3c4d5e6f7a8b901"
result = call_johari("GET", f"/api/companies/{company_id}/cost-codes")
print(result["data"])
```

:::

Response `200`:

```json
{
  "status": "success",
  "data": [
    {
      "value": "1001",
      "label": "1001 - Site Utilities",
      "category": "contractor"
    },
    {
      "value": "1003",
      "label": "1003 - Security & Guards",
      "category": "contractor"
    },
    {
      "value": "1801",
      "label": "1801 - Screed",
      "category": "contractor"
    },
    {
      "value": "1802",
      "label": "1802 - Plaster",
      "category": "contractor"
    }
  ],
  "message": "Cost codes fetched successfully"
}
```

Response `404`, when the company ID is wrong or the user cannot raise requests for it:

```json
{
  "status": "error",
  "data": null,
  "message": "Company not found"
}
```

## Common mistakes

::: danger Sending the cost code as a number
`costCode` must be a string: `"1003"`, not `1003`.
:::

::: danger Sending the label
Send `value` (`"1003"`), not `label` (`"1003 - Security & Guards"`).
:::

::: danger Using another company's cost code
Each company has its own set. Use a `value` from **the same company** as `requestingCompany`.
:::

## Related pages

* [Create a Request](/api/create-request)