# Create an organisation

Source: https://ethicsportal.eu/developers/api/operations/createorganization/

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

* EthicsPortal application

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](https://ethicsportal.eu/developers/api/#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 Bodyrequired

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

**id**

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

**id**

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

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

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

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

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

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

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