# List the organizations and their ids

- Endpoint: `GET /v1/organization`
- Production: `https://api.main-team.org/v1/organization`
- Sandbox: `https://apisnd.main-team.org/v1/organization`
- Operation: `listOrganizations` (Reference data)
- Authentication: `Authorization: Bearer <token>`, a short-lived token you sign with your API key and secret
- Permission: `organization/read:$org:$ID`

## Description

Every organization that runs exams, a page at a time (`limit` up to 100). Each one’s `_id` is the `organizationId` in the path of every organization-scoped operation: exams, applications, certificates, reports, sign-in links and the organization’s own student records.

`mto`, the organization that holds your students’ main records, is not listed. The operations without `organizationId` in the path act on it, so you never need its id.

Being listed does not mean your account may act on an organization. That is set by the roles an operator gave your account, and an operation on any other organization answers `403 forbidden`.

The list is in no guaranteed order and rarely changes, so fetch it once and keep it.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `page` | query | no | number | Page number. Defaults to 1. |
| `limit` | query | no | number | Items per page. Defaults to 20, max 100. |

## Response

`200` Success: `message` is "Organizations fetched successfully.".

```json
{
  "success": true,
  "message": "Organizations fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "64b7f0c2a1d3e4f5a6b7c8d9",
      "name": "Example Science Olympiad",
      "slug": "stem",
      "logo": "https://cdn.example.org/logos/example-science-olympiad.png",
      "desc": "An international olympiad in science and mathematics.",
      "defaultRedirect": "https://my.example-olympiad.org"
    }
  ]
}
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://hub.main-team.org/api/errors#unauthorized) | The token is missing or malformed, is not signed with your account’s `apiSecret`, breaks the `iat` and `exp` rules, has expired or been revoked, or its account is not active. All of these answer the same. |
| 403 | [`forbidden`](https://hub.main-team.org/api/errors#forbidden) | The token is valid, but no role on your account allows `organization/read` on `mto`, the organization every operation without `:organizationId` acts on, or a role denies it. |
| 429 | [`too_many_requests`](https://hub.main-team.org/api/errors#too_many_requests) | Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in `Retry-After` before sending again. |
| 500 | [`internal_error`](https://hub.main-team.org/api/errors#internal_error) | Something failed on our side. Retry later, and quote `request_id` if it goes on. |

## Code samples

### curl

```bash
# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/organization?page=1&limit=20' \
  -H "Authorization: Bearer $TOKEN"
```

### Node.js

```js
const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/organization?page=1&limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data, body.pagination);
```

### PHP

```php
<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/organization?page=1&limit=20');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body['data']);
print_r($body['pagination']);
```