# Inject a domain

Domain injection inserts a new domain between an existing parent domain and one or more child domains. Use it to add a governance layer without rebuilding the hierarchy.

Use carefully
Domain injection changes policy inheritance for future intents in the reparented child domains. Review policy impact before submitting the intent.

## API reference and shared process

| Task | API reference |
|  --- | --- |
| View current hierarchy | [Get domain details](/products/custody/v1.36/reference/api/openapi/domains/getdomain), [List domains](/products/custody/v1.36/reference/api/openapi/domains/getdomains) |
| Dry run the injection intent | [Perform a dry run](/products/custody/v1.36/reference/api/openapi/intents/intentdryrun) |
| Submit the signed injection intent | [Propose an intent](/products/custody/v1.36/reference/api/openapi/intents/createintent) |


Domain injection uses the same `v0_CreateDomain` intent as normal domain creation, with `childrenDomainIds` populated. For the general domain creation procedure, see [Manage domains](/products/custody/v1.36/governance/domains/reference).

## When to use domain injection

| Scenario | Example |
|  --- | --- |
| Add compliance oversight | Insert a compliance domain above operational domains. |
| Group regions | Move existing country domains under a new regional domain. |
| Consolidate policy control | Apply shared policies to a set of child domains. |
| Retrofit governance | Add a missing parent layer after launch. |


## Before and after


```mermaid
flowchart TB
    subgraph Before["Before injection"]
        Root1["Root"]
        A1["Domain A"]
        B1["Domain B"]
        Root1 --> A1
        Root1 --> B1
    end

    subgraph After["After injection"]
        Root2["Root"]
        New["Injected domain"]
        A2["Domain A"]
        B2["Domain B"]
        Root2 --> New
        New --> A2
        New --> B2
    end
```

## Prerequisites

- Administrator access to the parent domain.
- Domain IDs for every child domain to reparent.
- Child domains are `Unlocked`.
- Policies for the injected domain are reviewed.
- Approvers understand the policy impact.


Open intents in child domains are not affected by policies from the newly injected parent. New intents created after injection can be affected by the injected domain's policies.

## Procedure

1. Get the domain IDs for the child domains.
2. Prepare a `v0_CreateDomain` payload with `childrenDomainIds`.
3. Include users and policies required by the injected domain.
4. Dry run the intent.
5. Submit the signed intent.
6. After approval and execution, verify that child domains now show the injected domain as parent.
7. Test a representative new intent in a child domain to confirm policy behavior.


## API payload example

The following example creates a compliance domain and reparents two existing child domains beneath it. The `childrenDomainIds` field is what makes this an injection rather than a regular domain creation.


```json
{
  "payload": {
    "id": "2d37d78f-6f75-4667-93f7-1c6c07d77491",
    "alias": "Compliance",
    "lock": "Unlocked",
    "governingStrategy": "ConsiderDescendants",
    "permissions": {
      "readAccess": {
        "domains": ["admin"],
        "users": ["admin"],
        "accounts": ["admin", "compliance"],
        "transactions": ["admin", "compliance"],
        "policies": ["admin"],
        "endpoints": ["admin"],
        "requests": ["admin", "compliance"],
        "events": ["admin", "compliance"]
      }
    },
    "description": "Injected compliance domain",
    "customProperties": {},
    "users": [],
    "policies": [],
    "childrenDomainIds": [
      "c837a972-4ea9-4abf-8e56-b70cc41b74dc",
      "7ec9c5a5-ff89-490f-99c1-6ea827c62bbb"
    ],
    "type": "v0_CreateDomain"
  }
}
```

Dry run before submitting:


```sh
curl -X POST "${CUSTODY_API_URL}/v1/intents/dry-run" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @inject-domain-intent.json
```

Submit the signed intent:


```sh
curl -X POST "${CUSTODY_API_URL}/v1/intents" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "requestId: 0f50461a-d6d2-45c5-a57d-baa099cd562f" \
  -d @signed-inject-domain-intent.json
```

## Validation after execution

After the intent executes:

1. Call [Get domain details](/products/custody/v1.36/reference/api/openapi/domains/getdomain) for the injected domain.
2. Call [Get domain details](/products/custody/v1.36/reference/api/openapi/domains/getdomain) for each reparented child domain.
3. Confirm the injected domain appears in the expected place in the hierarchy.
4. Call [Perform a dry run](/products/custody/v1.36/reference/api/openapi/intents/intentdryrun) for a representative child-domain intent to confirm the expected policy is selected.


## Common mistakes

| Mistake | Result | Fix |
|  --- | --- | --- |
| Child domain is locked | Injection fails. | Unlock child domains before injection. |
| Missing child ID | A child remains under the old parent. | Include all intended child domains. |
| Wrong governing strategy | Parent policy behavior differs from design. | Review strategy before submission. |
| No dry run | Policy or payload errors are discovered late. | Dry run before proposing the intent. |


For field details, see [Domain reference](/products/custody/v1.36/governance/domains/reference).