Invite a member

POST

/organizations/{organization_id}/invitations.json

curl --request POST \
  --url https://secure.ethicsportal.eu/organizations/example/invitations.json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "invitation": { "email": "new.handler@example.com", "role": "member" } }'

• EthicsPortal application

Email an invitation that is valid for 14 days. The invitee accepts it in EthicsPortal; the API never returns the acceptance link. Up to 30 invitations per organisation per hour. A personal token also needs its user to be a current administrator of the organisation.

Authorizations

• personalToken
  members:write
• organizationToken
  members:write

Parameters

Path Parameters

organization_id

required

string

Obfuscated organisation ID returned by identity.

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters /^[\x21-\x7e]+$/

Recommended on every POST. Retrying with the same key and the same request within 24 hours returns the first response (with Idempotent-Replayed: true) instead of acting twice. Only successful responses and validation errors are stored; any other outcome releases the key. Reusing a key with a different request returns 409 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_key_in_progress. Keys are scoped to the token.

Request Body^required

Media typeapplication/json

object

invitation

required

object

email

required

string format: email

role

required

string

Allowed values: admin member viewer

Example

{
  "invitation": {
    "email": "new.handler@example.com",
    "role": "member"
  }
}

Responses

201

Invitation sent.

Media typeapplication/json

object

id

required

string

email

required

string

role

required

string

Allowed values: admin member viewer

expires_at

required

string format: date-time

last_sent_at

required

string | null format: date-time

created_at

required

string format: date-time

Example

{
  "id": "tUvWxy",
  "email": "new.handler@example.com",
  "role": "member",
  "expires_at": "2026-11-23T10:00:00Z",
  "last_sent_at": "2026-11-09T10:00:00Z",
  "created_at": "2026-11-09T10:00:00Z"
}

400

Invalid query, body or cursor

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "invalid_request",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

401

Missing, unknown, expired or revoked token

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "invalid_token",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

403

The token lacks the required scope (WWW-Authenticate names it), the user’s role does not allow the action, or an agreement must be accepted in the web application

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "insufficient_scope",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

404

Organisation or resource missing or inaccessible, or API access suspended

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "not_found",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

409

This Idempotency-Key was already used with a different request, or its first request is still running

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

422

Validation failed; fields are named, values are not echoed

Media typeapplication/json

object

error

required

object

code

required

Allowed value: validation_failed

fields

required

Array<string>

>= 1 items unique items

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "validation_failed",
    "fields": [
      "email"
    ],
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

429

Rate limited; retry after the Retry-After interval

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: invalid_token forbidden insufficient_scope not_found invalid_request agreement_required rate_limited idempotency_key_reused idempotency_key_in_progress not_retryable channel_inactive invitation_unavailable already_subscribed no_subscription

feedback_url

required

Where to tell EthicsPortal what went wrong: POST product feedback here with the same token.

string format: uri

Example

{
  "error": {
    "code": "rate_limited",
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}