Create an organisation

POST

/organizations.json

const url = 'https://secure.ethicsportal.eu/organizations.json';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"organization":{"name":"Example organisation"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://secure.ethicsportal.eu/organizations.json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "organization": { "name": "Example organisation" } }'

Create an organisation. Requires organizations:create, which only personal tokens can hold, current user terms, and at least one active membership. An assistant connection is the exception: a person with no organisation can create their first one through it. The owner and an administrator membership are assigned from the token user. Creates the default inactive whistleblowing channel. No billing or DPA acceptance is performed: the owner accepts the DPA in a browser, and until then the organisation’s operations answer agreement_required. Limited to 10 creation attempts per user per minute, across tokens. Send an Idempotency-Key so a retry after a lost response returns the first response instead of creating a second organisation.

Authorizations

personalToken
organizations:create

Parameters

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

application/json

object

organization

required

object

name

required

string

>= 1 characters <= 100 characters

Example

{
  "organization": {
    "name": "Example organisation"
  }
}

Responses

201

Organisation and owner membership created, with a default channel.

application/json

object

required

string

name

required

string

membership_id

required

The creating user’s administrator membership, as an obfuscated ID. Use as compliance_officer_id to appoint yourself.

string

channel

required

object

required

string

active

required

boolean

reports_url

required

string format: uri

channel_url

required

string format: uri

members_url

required

string format: uri

webhooks_url

required

string format: uri

audit_trail_url

required

string format: uri

documents_url

required

string format: uri

billing_url

required

string format: uri

Example

{
  "id": "gHiJkl",
  "name": "Example organisation",
  "membership_id": "mAbCde",
  "channel": {
    "id": "AB12CD34",
    "active": false
  },
  "reports_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/whistleblower/reports.json",
  "channel_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/whistleblower/portal.json",
  "members_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/members.json",
  "webhooks_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/webhooks.json",
  "audit_trail_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/whistleblower/audit_logs.json",
  "documents_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/whistleblower/documents.json",
  "billing_url": "https://secure.ethicsportal.eu/organizations/gHiJkl/subscriptions.json"
}

Headers

Location

string format: uri

Organisation web page; requires a separate authenticated browser session.

400

Invalid JSON body, attributes or types.

application/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 or unusable token.

application/json

object

error

required

object

code

required

string

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

Required scope missing, a personal token whose user is not a current administrator, or agreement_required until browser acceptance.

application/json

object

error

required

object

code

required

string

feedback_url

required

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

string format: uri

Example

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

404

Resource inaccessible, or API access suspended.

application/json

object

error

required

object

code

required

string

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

application/json

object

error

required

object

code

required

string

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

Model validation failed. Fields are attribute names only; values and personal data are never reflected.

application/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": [
      "name"
    ],
    "feedback_url": "https://secure.ethicsportal.eu/me/feedback.json"
  }
}

429

Rate limit exceeded. Retry-After: 60.

application/json

object

error

required

object

code

required

string

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"
  }
}

Create an organisation

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

201

Example

Headers

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

Request Body^required