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

FieldTypeRequiredDescription
namestringYesOrganisation name (1โ€“255 characters)
operator_namestring | nullNoOperator legal name (1โ€“200 chars)
operator_address_streetstring | nullNoOperator address โ€” street
operator_address_postal_codestring | nullNoOperator address โ€” postal code
operator_address_citystring | nullNoOperator address โ€” city
operator_address_fullstring | nullNoOperator address โ€” single-line fallback
operator_countrystring | nullNoISO 3166-1 alpha-2 country code (e.g. GB)
operator_emailstring | nullNoOperator contact email (RFC 5321; โ‰ค 320 chars)
operator_eoristring | nullNoEORI number: 2-letter country code + up to 15 alphanumeric chars (e.g. XI274615093000)
operator_identifier_type"EORI" | "VAT" | nullNoIdentifier scheme for the EORI/VAT value
operator_phonestring | nullNoE.164 phone number (e.g. +441234567890)
default_activity_type"DOMESTIC" | "IMPORT" | "EXPORT" | nullNoDefault EUDR activity type for new DDS records
default_country_of_activitystring | nullNoDefault country of activity for IMPORT/EXPORT โ€” EU-27 or XI only
default_geo_location_confidentialboolean | nullNoDefault 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 . _ : -.

RequestResult
New key201, the child is created
Same key, same body201, the original response again (same id, Location and body). Nothing is created.
Same key, different body409 with data.code idempotency_conflict
Malformed key400 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 around name do not matter. An attribute sent as null and the same attribute left out are different bodies.
  • Body validation runs first, so a reused key with an invalid body gets 400 (malformed body) or 422 (invalid attribute values), not 409. 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 stored 201, and its Location returns 404.
  • 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-as header must not be set.

Required scope: organizations:write