---
url: /api/companies.md
---
# List Companies

Returns the companies your API key's user can raise payment requests for. Use an `id` from here as `requestingCompany` when you [create a request](/api/create-request).

## Endpoint

| Method | URL |
|---|---|
| `GET` | `/api/companies` |

No query parameters, no body. Sign it like any `GET`:

```
<timestamp>.GET./api/companies.
```

## Response

`data` is an array of companies (complete in one response, not paginated):

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Company ID. Use it as `requestingCompany` |
| `name` | `string` | Company name |

Only companies where the user can **create** requests at one or more sites are listed. If the user cannot create requests anywhere, `data` is `[]`.

## Example

::: code-group

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

```js [Node.js]
// callJohari is from the Signing page
const result = await callJohari("GET", "/api/companies");
console.log(result.data);
```

```python [Python]
# call_johari is from the Signing page
result = call_johari("GET", "/api/companies")
print(result["data"])
```

:::

Response `200`:

```json
{
  "status": "success",
  "data": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b901",
      "name": "Example Construction Ltd"
    },
    {
      "id": "6650f1a2b3c4d5e6f7a8b902",
      "name": "Example Developers Ltd"
    }
  ],
  "message": "Companies fetched successfully"
}
```

## Common mistakes

::: danger Hard-coding IDs from another environment
The test server and the live server have different IDs. Look them up on each environment, or keep a separate mapping for each.
:::

::: tip This is your first test
`GET /api/companies` is the simplest signed call. If it returns `200`, your key, secret, clock and signing are all correct.
:::

## Related pages

* [List Sites](/api/sites)
* [List Cost Codes](/api/cost-codes)