# Make your first API request

Source: https://ethicsportal.eu/developers/quickstart/

## 1\. Accept your agreements

Sign in to EthicsPortal and accept any outstanding account terms or organisation agreement. API requests are refused until you do.

## 2\. Create an API token

For an integration your organisation depends on, an administrator opens the organisation, selects **Organisation API tokens**, then **Create API token**. For your own scripts, open your account settings and select **Personal API tokens** instead. [Compare token types](https://ethicsportal.eu/developers/authentication/#choose-a-token-type).

Complete the fresh-authentication challenge and give the credential a recognisable name. Keep the preselected read scopes for a monitoring integration. To configure channels or create organisations, follow the [organisation setup guide](https://ethicsportal.eu/developers/organisation-setup/) and select those scopes explicitly.

Copy the token immediately: the full value is displayed once. Store it in your integration’s secret store. Tokens expire after 90 days.

## 3\. Discover your organisation

Set `ETHICSPORTAL_TOKEN` through your secret manager or a private local environment. The examples use environment-variable references so the token is not written into source code.

```
export ETHICSPORTAL_ORIGIN='https://secure.ethicsportal.eu'
curl --fail-with-body \
  -H "Authorization: Bearer $ETHICSPORTAL_TOKEN" \
  -H 'Accept: application/json' \
  "$ETHICSPORTAL_ORIGIN/identity.json"
```

The response contains the token’s type, name, last four characters, scopes, expiry and last use, and the IDs and names of the organisations it can reach. Use `expires_at` to replace the token before it expires. Copy the required organisation’s `id` into `ETHICSPORTAL_ORGANIZATION_ID`. Treat all IDs as strings; do not decode them or substitute reporter access codes.

## 4\. Fetch report metadata

```
curl --fail-with-body \
  -H "Authorization: Bearer $ETHICSPORTAL_TOKEN" \
  -H 'Accept: application/json' \
  "$ETHICSPORTAL_ORIGIN/organizations/$ETHICSPORTAL_ORGANIZATION_ID/whistleblower/reports.json?limit=50"
```

The reports are in the response’s `data` array. An empty `data` array means there are no matching reports you can access. While `next_cursor` is not `null`, request the list again with `cursor` set to that value. [Pagination example](https://ethicsportal.eu/developers/examples/pagination/).

## 5\. Add notifications

[Register a webhook](https://ethicsportal.eu/developers/webhooks/) for lifecycle or deadline events. Verify signatures and persist receipt before acknowledging delivery. Periodically use the API to reconcile current state after missed or out-of-order events.

## If the request fails

A `401` indicates a missing or unusable token. A `403` can indicate an outstanding agreement. A `404` can mean integrations are disabled or the organisation/report is outside your access. [Errors and rate limits](https://ethicsportal.eu/developers/pagination-and-errors/#errors).