Make your first API request

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.

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 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.

5. Add notifications

Register a webhook 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.