curl -s -X POST \
  "https://engine.example.com/v1/holders:onboard" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: onboard-holder-alpha" \
  -H "Content-Type: application/json" \
  -d '{
    "kyc": {
      "provider": "kyc-provider",
      "ref": "case-20261003-0001"
    },
    "party": "alpha::12207ae69b2ef2f1249abd41923a06ee30bffa9298a17b0a875355c441bf32045d73",
    "holderId": "alpha",
    "attributes": {
      "residency": {
        "value": "SG",
        "state": "verified",
        "expiresAt": "2027-10-01T00:00:00Z",
        "proofHash": "sha256:71bb0d85eaa3ef967532c1362a20fed032d5889aa1cdd659e18a61485aefde94",
        "evidence": "kyc/alpha/residency"
      },
      "investorType": {
        "value": "professional",
        "state": "verified",
        "expiresAt": null,
        "proofHash": "sha256:99104191dccbd729f5ee8dd91329ceb2be83da5eec4358e7e33c410e2882ad96",
        "evidence": "kyc/alpha/investor-type"
      }
    }
  }'

// A client from OpenAPI Generator: see Build a client.
import {
  Configuration,
  HoldersApi,
  OnboardHolderBodyFromJSON,
  ProblemFromJSON,
  ResponseError,
} from "./nodeasset-client";

const api = new HoldersApi(new Configuration({
  basePath: "https://engine.example.com",
  accessToken: process.env.TOKEN,
}));

try {
  const answer = await api.onboardHolder({
    // Your id for this action: a retry is the same write.
    idempotencyKey: "onboard-holder-alpha",
    onboardHolderBody: OnboardHolderBodyFromJSON({
      kyc: {
        provider: "kyc-provider",
        ref: "case-20261003-0001",
      },
      party: "alpha::12207ae69b2ef2f1249abd41923a06ee30bffa9298a17b0a875355c441bf32045d73",
      holderId: "alpha",
      attributes: {
        residency: {
          value: "SG",
          state: "verified",
          expiresAt: "2027-10-01T00:00:00Z",
          proofHash: "sha256:71bb0d85eaa3ef967532c1362a20fed032d5889aa1cdd659e18a61485aefde94",
          evidence: "kyc/alpha/residency",
        },
        investorType: {
          value: "professional",
          state: "verified",
          expiresAt: null,
          proofHash: "sha256:99104191dccbd729f5ee8dd91329ceb2be83da5eec4358e7e33c410e2882ad96",
          evidence: "kyc/alpha/investor-type",
        },
      },
    }),
  });
  if (answer.state === "awaiting") {
    // Awaiting approval: it runs once approved.
    console.log("Awaiting approval:", answer.actionKey);
  } else {
    // Follow the operation until it succeeds or fails.
    console.log("Operation:", answer.operationId, answer.state);
  }
} catch (e) {
  if (!(e instanceof ResponseError)) throw e;
  // A refusal is a problem; its type ends in the slug.
  const problem = ProblemFromJSON(await e.response.json());
  const slug = problem.type.split(":").pop();
  console.error(e.response.status, slug, problem.detail);
}

# A client from OpenAPI Generator: see Build a client.
import os
import sys

import nodeasset_client

config = nodeasset_client.Configuration(
    host="https://engine.example.com",
    access_token=os.environ["TOKEN"],
)
with nodeasset_client.ApiClient(config) as client:
    api = nodeasset_client.HoldersApi(client)
    try:
        answer = api.onboard_holder(
            # Your id for this action: a retry is the same write.
            idempotency_key="onboard-holder-alpha",
            onboard_holder_body=nodeasset_client.OnboardHolderBody.model_validate({
                "kyc": {
                    "provider": "kyc-provider",
                    "ref": "case-20261003-0001",
                },
                "party": "alpha::12207ae69b2ef2f1249abd41923a06ee30bffa9298a17b0a875355c441bf32045d73",
                "holderId": "alpha",
                "attributes": {
                    "residency": {
                        "value": "SG",
                        "state": "verified",
                        "expiresAt": "2027-10-01T00:00:00Z",
                        "proofHash": "sha256:71bb0d85eaa3ef967532c1362a20fed032d5889aa1cdd659e18a61485aefde94",
                        "evidence": "kyc/alpha/residency",
                    },
                    "investorType": {
                        "value": "professional",
                        "state": "verified",
                        "expiresAt": None,
                        "proofHash": "sha256:99104191dccbd729f5ee8dd91329ceb2be83da5eec4358e7e33c410e2882ad96",
                        "evidence": "kyc/alpha/investor-type",
                    },
                },
            }),
        )
        if answer.state == "awaiting":
            # Awaiting approval: it runs once approved.
            print("Awaiting approval:", answer.action_key)
        else:
            # Follow the operation until it succeeds or fails.
            print("Operation:", answer.operation_id, answer.state)
    except nodeasset_client.ApiException as e:
        # A refusal is a problem; its type ends in the slug.
        problem = nodeasset_client.Problem.from_json(e.body)
        slug = problem.type.rsplit(":", 1)[-1]
        print(e.status, slug, problem.detail, file=sys.stderr)

// A client from OpenAPI Generator: see Build a client.
import nodeasset.client.ApiClient;
import nodeasset.client.ApiException;
import nodeasset.client.api.HoldersApi;
import nodeasset.client.model.OnboardHolderBody;
import nodeasset.client.model.Problem;
import nodeasset.client.model.WriteAnswer;

public class OnboardHolder {
  public static void main(String[] args) throws Exception {
    ApiClient client = new ApiClient();
    client.updateBaseUri("https://engine.example.com");
    client.setRequestInterceptor(builder ->
        builder.header("Authorization", "Bearer " + System.getenv("TOKEN")));
    HoldersApi api = new HoldersApi(client);

    try {
      var request = HoldersApi.APIOnboardHolderRequest.newBuilder()
          // Your id for this action: a retry is the same write.
          .idempotencyKey("onboard-holder-alpha")
          .onboardHolderBody(client.getObjectMapper().readValue("""
              {
                "kyc": {
                  "provider": "kyc-provider",
                  "ref": "case-20261003-0001"
                },
                "party": "alpha::12207ae69b2ef2f1249abd41923a06ee30bffa9298a17b0a875355c441bf32045d73",
                "holderId": "alpha",
                "attributes": {
                  "residency": {
                    "value": "SG",
                    "state": "verified",
                    "expiresAt": "2027-10-01T00:00:00Z",
                    "proofHash": "sha256:71bb0d85eaa3ef967532c1362a20fed032d5889aa1cdd659e18a61485aefde94",
                    "evidence": "kyc/alpha/residency"
                  },
                  "investorType": {
                    "value": "professional",
                    "state": "verified",
                    "expiresAt": null,
                    "proofHash": "sha256:99104191dccbd729f5ee8dd91329ceb2be83da5eec4358e7e33c410e2882ad96",
                    "evidence": "kyc/alpha/investor-type"
                  }
                }
              }
              """, OnboardHolderBody.class))
          .build();
      WriteAnswer answer = api.onboardHolder(request);
      if (answer.getState() == WriteAnswer.StateEnum.AWAITING) {
        // Awaiting approval: it runs once approved.
        System.out.println("Awaiting approval: " + answer.getActionKey());
      } else {
        // Follow the operation until it succeeds or fails.
        System.out.println("Operation: " + answer.getOperationId() + " " + answer.getState());
      }
    } catch (ApiException e) {
      // A refusal is a problem; its type ends in the slug.
      Problem problem = client.getObjectMapper()
          .readValue(e.getResponseBody(), Problem.class);
      String type = problem.getType();
      String slug = type.substring(type.lastIndexOf(':') + 1);
      System.err.println(e.getCode() + " " + slug + " " + problem.getDetail());
    }
  }
}