Create Child
Create a new child organisation under the caller's organisation.
The child organisation is created with the given name and linked to the caller as its parent. Only top-level organisations can create children โ the API enforces single-level hierarchy.
โถAttributes
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Organisation name (1โ255 characters) |
operator_name | string | null | No | Operator legal name (1โ200 chars) |
operator_address_street | string | null | No | Operator address โ street |
operator_address_postal_code | string | null | No | Operator address โ postal code |
operator_address_city | string | null | No | Operator address โ city |
operator_address_full | string | null | No | Operator address โ single-line fallback |
operator_country | string | null | No | ISO 3166-1 alpha-2 country code (e.g. GB) |
operator_email | string | null | No | Operator contact email (RFC 5321; โค 320 chars) |
operator_eori | string | null | No | EORI number: 2-letter country code + up to 15 alphanumeric chars (e.g. XI274615093000) |
operator_identifier_type | "EORI" | "VAT" | null | No | Identifier scheme for the EORI/VAT value |
operator_phone | string | null | No | E.164 phone number (e.g. +441234567890) |
default_activity_type | "DOMESTIC" | "IMPORT" | "EXPORT" | null | No | Default EUDR activity type for new DDS records |
default_country_of_activity | string | null | No | Default country of activity for IMPORT/EXPORT โ EU-27 or XI only |
default_geo_location_confidential | boolean | null | No | Default geo-location confidentiality flag for new DDS records |
The three default_* fields are the org-level EUDR submission defaults. Two
combinations are refused with 422: DOMESTIC together with a
default_country_of_activity, and an activity default the organisation's own
operator could never file under (IMPORT/EXPORT with a VAT-identified
operator, or any non-IMPORT value with a non-EU operator_country). See
PATCH /organizations/me for the full rules.
The response includes read-only fields plan, tier, and domain which are set to their default values (free, standard, null) on creation.
A default internal API key is automatically created for the child organisation (not included in the response).
โถIdempotency
Send an optional Idempotency-Key header to make the create safe to retry. The key is 1โ128 characters from AโZ aโz 0โ9 . _ : -.
| Request | Result |
|---|---|
| New key | 201, the child is created |
| Same key, same body | 201, the original response again (same id, Location and body). Nothing is created. |
| Same key, different body | 409 with data.code idempotency_conflict |
| Malformed key | 400 VALIDATION_ERROR |
- Keys are scoped to the calling organisation and never expire.
- Two concurrent requests with the same key create exactly one organisation.
- Bodies are compared on
data.attributes. Key order and whitespace aroundnamedo not matter. An attribute sent asnulland the same attribute left out are different bodies. - Body validation runs first, so a reused key with an invalid body gets
400(malformed body) or422(invalid attribute values), not409. A failed create stores nothing, so the same key can be retried with a corrected body. - If the child has since been unlinked (
DELETE /organizations/children/{id}), a replay still returns the stored201, and itsLocationreturns404. - If Epoch deletes the child organisation outright, its key is freed, and the same key creates a new organisation.
- Without the header, behaviour is unchanged.
โถConstraints
- The caller must be a top-level organisation (not itself a child).
- The
x-acting-asheader must not be set.
Required scope:
organizations:write