Onboard Represented Business

Onboard one represented business. A new or pending intent requires transient nrsCredentials; a completed replay with the same idempotency key and normalized profile may omit credentials. New completion and completed replay both return 201, distinguished by replayed. The immutable gatewaySubBusinessId is initially allocated from the verified NRS business ID and never silently remapped; the current external mapping is returned in firsBusinessId and nrsIdentity.nrsBusinessId.

Authorization

apiKey

x-api-key<token>

The API key generated for your business in Duplo Dashboard. The credential's ipWhitelisted setting is enforced end to end on the customer-facing custom-domain Gateway routes in this public contract. A trusted edge overwrites the configured client-IP header and Gateway carries that verified address over its authenticated internal hop; caller-supplied X-Forwarded-For values are never trusted. An empty IP allowlist permits any source. When an allowlist is configured, a missing, malformed, or nonmatching verified client address is rejected with HTTP 403.

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

X-Request-ID?string

Optional caller correlation metadata. Gateway creates a new authoritative request ID, returns it in the response X-Request-ID header and Problem Details requestId, and propagates that generated value to its dependencies.

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

Length1 <= 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`

`application/problem+json`

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

{
  "onboardingIntentId": "33333333-3333-4333-8333-333333333333",
  "gatewaySubBusinessId": "nrs-business-demo",
  "firsBusinessId": "nrs-business-demo",
  "nrsIdentity": {
    "entityId": "entity-demo",
    "entityReference": "entity-reference-demo",
    "nrsBusinessId": "nrs-business-demo",
    "businessName": "Acme Retail Limited",
    "tin": "12345678-0001",
    "irnTemplate": "{{invoice_id}}-2A3A045D-{{YYYYMMDD}}"
  },
  "status": "completed",
  "replayed": false,
  "cryptoVersion": 0
}

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_REQUEST_SERVER_FIELD_SUPPLIED",
  "title": "Server-managed field was supplied",
  "status": 400,
  "detail": "The request contains a field that is resolved by the gateway.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_REQUEST_SERVER_FIELD_SUPPLIED",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "REMOVE_SERVER_FIELD",
    "description": "Remove the server-managed field and submit the request again.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_REQUEST_SERVER_FIELD_SUPPLIED"
  },
  "retry": {
    "strategy": "AFTER_CORRECTION"
  },
  "message": "The request contains a field that is resolved by the gateway.",
  "statusCode": 400,
  "path": "/sub-businesses"
}

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_AUTH_API_KEY_REQUIRED",
  "title": "API key is required",
  "status": 401,
  "detail": "The API key header is missing.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_AUTH_API_KEY_REQUIRED",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "SUPPLY_API_KEY",
    "description": "Add the API key header and submit the request again.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_AUTH_API_KEY_REQUIRED"
  },
  "retry": {
    "strategy": "AFTER_CORRECTION"
  },
  "message": "The API key header is missing.",
  "statusCode": 401,
  "path": "/sub-businesses"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "http://example.com",
  "code": "GW_REQUEST_INVALID_JSON",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "timestamp": "2019-08-24T14:15:22Z",
  "action": {
    "code": "string",
    "description": "string",
    "documentation": "http://example.com"
  },
  "retry": {
    "strategy": "DO_NOT_RETRY",
    "sameIdempotencyKey": true,
    "afterSeconds": 0
  },
  "errors": [
    {
      "location": "header",
      "field": "string",
      "pointer": "string",
      "code": "REQUIRED",
      "detail": "string"
    }
  ],
  "operationId": "string",
  "message": "string",
  "statusCode": 0,
  "path": "string"
}

Onboard Represented Business

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

413application/problem+json

422application/problem+json

429application/problem+json

502application/problem+json

503application/problem+json

508application/problem+json

defaultapplication/problem+json

Newly completed onboarding

Original result returned for a completed replay

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`