Skip to content
EthicsPortal API

Configure a whistleblowing channel

PATCH
/organizations/{organization_id}/whistleblower/portal/configuration.json
curl --request PATCH \
  --url https://secure.ethicsportal.eu/organizations/example/whistleblower/portal/configuration.json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "portal": { "legal_name": "Example company", "country_code": "FR", "registration_number": "EXAMPLE-123", "address": "1 Example Street", "employee_range": "1-49", "industry": "professional_scientific_services", "website": null, "phone_number": null, "compliance_officer_id": "mAbCde", "brand_color": "#123456", "retention_months": 60, "social_dialogue_consulted": false, "voice_recording_enabled": false, "email_intake_enabled": false } }'

Change the channel’s company details and settings. Requires channel:write. A personal token also needs its user to be a current administrator; an organisation token needs only the scope. Send application/json with a nonempty portal object; only supplied fields change. Unknown fields, query parameters and incorrect JSON types are rejected. Verified company details remain locked. Retention minimums, active administrator appointments and readiness rules are the same as the web application. active, verified, slug, billing and organisation flags cannot be set.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization_id
required
string

Obfuscated organisation ID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
portal
required
object
>= 1 properties
legal_name
string | null
<= 255 characters
country_code

A supported ISO 3166-1 alpha-2 country code. Country-specific retention minimums apply.

string | null
registration_number
string | null
address
string | null
employee_range
string | null
Allowed values: 1-49 50-249 250+ ""
industry
string | null
Allowed values: agriculture_forestry mining_quarrying manufacturing energy_utilities water_waste_management construction wholesale_retail_trade transportation_logistics hospitality_food_services information_communication financial_services_insurance real_estate professional_scientific_services administrative_support_services public_administration_defence education healthcare_social_work arts_entertainment_recreation other ""
website
string | null
phone_number
string | null
compliance_officer_id

An active administrator membership in this organisation, identified by its obfuscated ID. Creation returns your membership_id. Null removes the appointment and can make the channel inactive. Raw database IDs are rejected.

string | null
brand_color
string | null
retention_months

Must also meet the selected country’s minimum. Defaults to 60 months. A country change and its retention adjustment are validated together.

integer
Allowed values: 12 24 36 48 60
social_dialogue_consulted
boolean
voice_recording_enabled
boolean
email_intake_enabled
boolean

Example 

{
  "portal": {
    "legal_name": "Example company",
    "country_code": "FR",
    "registration_number": "EXAMPLE-123",
    "address": "1 Example Street",
    "employee_range": "1-49",
    "industry": "professional_scientific_services",
    "website": null,
    "phone_number": null,
    "compliance_officer_id": "mAbCde",
    "brand_color": "#123456",
    "retention_months": 60,
    "social_dialogue_consulted": false,
    "voice_recording_enabled": false,
    "email_intake_enabled": false
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Validated settings saved. active is derived, never a promise of activation.

Media typeapplication/json
object
legal_name
required
string | null
<= 255 characters
country_code
required

A supported ISO 3166-1 alpha-2 country code. Country-specific retention minimums apply.

string | null
registration_number
required
string | null
address
required
string | null
employee_range
required
string | null
Allowed values: 1-49 50-249 250+ ""
industry
required
string | null
Allowed values: agriculture_forestry mining_quarrying manufacturing energy_utilities water_waste_management construction wholesale_retail_trade transportation_logistics hospitality_food_services information_communication financial_services_insurance real_estate professional_scientific_services administrative_support_services public_administration_defence education healthcare_social_work arts_entertainment_recreation other ""
website
required
string | null
phone_number
required
string | null
compliance_officer_id
required

An active administrator membership in this organisation, identified by its obfuscated ID. Creation returns your membership_id. Null removes the appointment and can make the channel inactive. Raw database IDs are rejected.

string | null
brand_color
required
string | null
retention_months
required

Must also meet the selected country’s minimum. Defaults to 60 months. A country change and its retention adjustment are validated together.

integer
Allowed values: 12 24 36 48 60
social_dialogue_consulted
required
boolean
voice_recording_enabled
required
boolean
email_intake_enabled
required
boolean
id
required
string
active
required
boolean
verified
required
boolean
reporting_form_url
required
string format: uri
missing_fields
required
Array<string>
unique items
Allowed values: legal_name country_code registration_number address employee_range industry compliance_officer_id

Example 

{
  "legal_name": "Example company",
  "country_code": "FR",
  "registration_number": "EXAMPLE-123",
  "address": "1 Example Street",
  "employee_range": "1-49",
  "industry": "professional_scientific_services",
  "website": null,
  "phone_number": null,
  "compliance_officer_id": "mAbCde",
  "brand_color": "#123456",
  "retention_months": 60,
  "social_dialogue_consulted": false,
  "voice_recording_enabled": false,
  "email_intake_enabled": false,
  "id": "AB12CD34",
  "active": false,
  "verified": false,
  "reporting_form_url": "https://secure.ethicsportal.eu/p/AB12CD34",
  "missing_fields": []
}

400

Section titled “400”

Invalid JSON body, attributes or types.

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

Section titled “401”

Missing or unusable 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

Section titled “403”

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

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

404

Section titled “404”

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

422

Section titled “422”

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

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

429

Section titled “429”

Rate limit exceeded. Retry-After: 60.

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