---
url: /api/sites.md
---
# List Sites

Returns a company's sites where your API key's user can raise payment requests. Use an `id` from here as `requestingSite` when you [create a request](/api/create-request).

A site is a project location, for example one building project.

## Endpoint

| Method | URL |
|---|---|
| `GET` | `/api/companies/:companyID/sites` |

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

Sign the full path, with the ID in it:

```
<timestamp>.GET./api/companies/6650f1a2b3c4d5e6f7a8b901/sites.
```

## Response

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

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Site ID (a UUID). Use it as `requestingSite` |
| `name` | `string` | Site name |

Only the sites where the user can **create** requests are listed, not every site of the company.

## Example

::: code-group

```bash [cURL]
COMPANY_ID="6650f1a2b3c4d5e6f7a8b901"
TS=$(date +%s)
SIG=$(printf '%s' "$TS.GET./api/companies/$COMPANY_ID/sites." \
  | openssl dgst -sha256 -hmac "$SIGNING_SECRET" \
  | sed 's/^.* //')
curl "$BASE_URL/api/companies/$COMPANY_ID/sites" \
  -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}/sites`);
console.log(result.data);
```

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

:::

Response `200`:

```json
{
  "status": "success",
  "data": [
    {
      "id": "3c9a7f52-1d4e-4b8a-9f6c-2e1d5a7b8c90",
      "name": "Block A Apartments"
    },
    {
      "id": "8e1b4c7d-2a3f-4d5e-8b9c-0a1b2c3d4e5f",
      "name": "Riverside Warehouse"
    }
  ],
  "message": "Sites 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 Mixing a site with the wrong company
A site belongs to one company. When you create a request, `requestingSite` must be a site of `requestingCompany`, or you get `400`.
:::

## Related pages

* [List Companies](/api/companies)
* [List Approvers](/api/approvers)