Onboard Represented Business

Register a headless business you invoice on behalf of. All local profile fields, the TIN selector, and NRS QR material are optional. For a new or pending intent, nrsCredentials is required; a completed replay with the same normalized profile and idempotency key may omit it. When tin is omitted, the authenticated NRS entity must contain exactly one active business. When tin is supplied, it must select exactly one active business.

The NRS password is transient: it terminates at Gateway and is never logged, persisted, echoed, or forwarded to Spend. Gateway derives NRS identity and ownership values. The following fields are rejected if supplied: existingBusinessId, businessId, parentBusinessId, entityId, entityReference, firsBusinessId, nrsBusinessId, businessName, and irnTemplate.

Authorization

apiKey

x-api-key<token>

The API key generated for your business in Duplo Dashboard.

In: header

Header Parameters

x-idempotency-key*string

Stable key identifying one logical command. Gateway management keys contain 8–128 letters, digits, dots, underscores, colons, or hyphens. For onboarding, the key binds the normalized optional profile; a completed replay may omit NRS credentials and QR material.

Match^[A-Za-z0-9._:-]+$

Length8 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Optional local display name. It is not used to select or replace the NRS-verified name.

Length1 <= length <= 50

legalName?string

Optional local legal-name metadata. It is not used to select or replace NRS identity.

Length1 <= length <= 50

tin?string

Optional NRS business selector. If omitted, the NRS entity must have exactly one active business. If supplied, its trimmed, case-insensitive value must match exactly one active NRS business.

Length1 <= length <= 255

email?string

Optional local contact email for the represented business.

Formatemail

Lengthlength <= 254

phoneNumber?string

Optional local contact number in E.164 format.

Match^\+[1-9]\d{6,18}$

Lengthlength <= 20

invoiceNumberPrefix?string

Optional local invoice-number prefix.

Length1 <= length <= 32

nrsCredentials?

Transient NRS portal credentials. Required to start or resume onboarding while the intent is pending; may be omitted only when replaying an already-completed intent. Gateway never forwards them to Spend.

nrsCryptoKeys?

Optional, all-or-nothing NRS QR material. Gateway treats both values as opaque, stores them exactly as supplied, and does not parse a certificate, check dates, normalize the strings, measure RSA key size, or verify a key match. The QR generator interprets the values only when QR generation is attempted. A privateKey property is not supported.

Response Body

`application/json`

curl -X POST "https://example.com/sub-businesses" \  -H "x-idempotency-key: command-acme-retail-0001" \  -H "Content-Type: application/json" \  -d '{    "nrsCredentials": {      "email": "nrs-owner@acme.example",      "password": "replace-at-runtime"    }  }'

{
  "onboardingIntentId": "33333333-3333-4333-8333-333333333333",
  "gatewaySubBusinessId": "44444444-4444-4444-8444-444444444444",
  "status": "completed",
  "replayed": true,
  "cryptoVersion": 0
}

{
  "onboardingIntentId": "33333333-3333-4333-8333-333333333333",
  "gatewaySubBusinessId": "44444444-4444-4444-8444-444444444444",
  "status": "completed",
  "replayed": false,
  "cryptoVersion": 0
}

{
  "message": "existingBusinessId is server-resolved and must not be supplied",
  "error": "Bad Request",
  "statusCode": 400
}

{
  "message": "Missing required 'x-api-key' header",
  "error": "Unauthorized",
  "statusCode": 401
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

{
  "message": "string",
  "error": "string",
  "statusCode": 0
}

Onboard Represented Business

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

413application/json

422application/json

429application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`