From 537dc9463b7201fec969c7ec7bb80a3dc33b7f60 Mon Sep 17 00:00:00 2001 From: Aaron Kanter Date: Thu, 13 Aug 2026 23:47:43 +0000 Subject: [PATCH 1/2] Unify individual customer identification on idType/identifier/countryOfIssuance --- mintlify/openapi.yaml | 22 ++++++------------- mintlify/snippets/sandbox-verification.mdx | 10 ++++----- openapi.yaml | 22 ++++++------------- .../IndividualCustomerCreateRequest.yaml | 14 ------------ .../customers/IndividualCustomerFields.yaml | 18 ++++++++------- .../components/schemas/errors/FieldError.yaml | 2 +- 6 files changed, 30 insertions(+), 58 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 0fef08e37..f73ba6d5b 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -11769,7 +11769,7 @@ components: field: type: string description: Dot-notation path to the offending field. - example: taxIdentifier + example: identifier constraint: $ref: '#/components/schemas/FieldConstraint' message: @@ -12430,15 +12430,16 @@ components: example: US address: $ref: '#/components/schemas/Address' - taxIdType: + idType: $ref: '#/components/schemas/IdentificationType' - taxIdentifier: + identifier: type: string - description: Tax-identification number. For US persons this is the SSN (format `###-##-####`) or ITIN. For non-US persons this is the tax number issued by `taxIdCountryOfIssuance`. + writeOnly: true + description: The individual's identification number, required to onboard them as a US account holder. Only SSN (format `###-##-####`) and ITIN are currently accepted; other identification types are rejected. Write-only — never returned in customer responses. example: 123-45-6789 - taxIdCountryOfIssuance: + countryOfIssuance: type: string - description: Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when `taxIdType` is `NON_US_TAX_ID`. + description: Country that issued the identification (ISO 3166-1 alpha-2). Required when `idType` is `NON_US_TAX_ID`. example: US - $ref: '#/components/schemas/CustomerEdd' IndividualCustomer: @@ -12982,15 +12983,6 @@ components: allOf: - $ref: '#/components/schemas/CustomerCreateRequest' - $ref: '#/components/schemas/IndividualCustomerFields' - - type: object - properties: - idType: - $ref: '#/components/schemas/IdentificationType' - identifier: - type: string - writeOnly: true - description: The individual's tax identification number. Required to onboard the individual as a US account holder. Only SSN and ITIN are currently accepted for an individual account holder; other identification types are rejected. Write-only — never returned in customer responses. - example: 123-45-6789 BusinessInfo: type: object description: Additional information required for business entities diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index 4e1827fed..ec00245b3 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -13,7 +13,7 @@ The **last 3 characters** of the `fullName` on `POST /customers` (with `customer Because terminal suffixes resolve at creation, only `001` and `003` customers can be submitted for verification. Use any non-suffixed name to mint ready-to-transact approved customers, and a `001` name to exercise the full submission flow. -Submitting for verification has the same data requirements as production: full name, birth date, nationality, `taxIdType` + `taxIdentifier`, address, and an identity document uploaded via `POST /documents`. Anything missing comes back as `verificationStatus: RESOLVE_ERRORS` with one entry per problem in `errors`: +Submitting for verification has the same data requirements as production: full name, birth date, nationality, `idType` + `identifier`, address, and an identity document uploaded via `POST /documents`. Anything missing comes back as `verificationStatus: RESOLVE_ERRORS` with one entry per problem in `errors`: ```json { @@ -22,8 +22,8 @@ Submitting for verification has the same data requirements as production: full n { "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001", "type": "MISSING_FIELD", - "field": "taxIdentifier", - "reason": "Tax identifier is required" + "field": "identifier", + "reason": "Identifier is required" }, { "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001", @@ -74,8 +74,8 @@ Fix-and-resubmit example — the standard integration loop: -H "Content-Type: application/json" \ -d '{ "customerType": "INDIVIDUAL", - "taxIdType": "SSN", - "taxIdentifier": "111-22-3333", + "idType": "SSN", + "identifier": "111-22-3333", "address": { "line1": "123 Main St", "city": "Seattle", "state": "WA", "postalCode": "98101", "country": "US" } }' diff --git a/openapi.yaml b/openapi.yaml index 0fef08e37..f73ba6d5b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -11769,7 +11769,7 @@ components: field: type: string description: Dot-notation path to the offending field. - example: taxIdentifier + example: identifier constraint: $ref: '#/components/schemas/FieldConstraint' message: @@ -12430,15 +12430,16 @@ components: example: US address: $ref: '#/components/schemas/Address' - taxIdType: + idType: $ref: '#/components/schemas/IdentificationType' - taxIdentifier: + identifier: type: string - description: Tax-identification number. For US persons this is the SSN (format `###-##-####`) or ITIN. For non-US persons this is the tax number issued by `taxIdCountryOfIssuance`. + writeOnly: true + description: The individual's identification number, required to onboard them as a US account holder. Only SSN (format `###-##-####`) and ITIN are currently accepted; other identification types are rejected. Write-only — never returned in customer responses. example: 123-45-6789 - taxIdCountryOfIssuance: + countryOfIssuance: type: string - description: Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when `taxIdType` is `NON_US_TAX_ID`. + description: Country that issued the identification (ISO 3166-1 alpha-2). Required when `idType` is `NON_US_TAX_ID`. example: US - $ref: '#/components/schemas/CustomerEdd' IndividualCustomer: @@ -12982,15 +12983,6 @@ components: allOf: - $ref: '#/components/schemas/CustomerCreateRequest' - $ref: '#/components/schemas/IndividualCustomerFields' - - type: object - properties: - idType: - $ref: '#/components/schemas/IdentificationType' - identifier: - type: string - writeOnly: true - description: The individual's tax identification number. Required to onboard the individual as a US account holder. Only SSN and ITIN are currently accepted for an individual account holder; other identification types are rejected. Write-only — never returned in customer responses. - example: 123-45-6789 BusinessInfo: type: object description: Additional information required for business entities diff --git a/openapi/components/schemas/customers/IndividualCustomerCreateRequest.yaml b/openapi/components/schemas/customers/IndividualCustomerCreateRequest.yaml index d960df9df..30531f661 100644 --- a/openapi/components/schemas/customers/IndividualCustomerCreateRequest.yaml +++ b/openapi/components/schemas/customers/IndividualCustomerCreateRequest.yaml @@ -2,17 +2,3 @@ title: Individual Customer Create Request allOf: - $ref: ./CustomerCreateRequest.yaml - $ref: ./IndividualCustomerFields.yaml - - type: object - properties: - idType: - $ref: ./IdentificationType.yaml - identifier: - type: string - writeOnly: true - description: >- - The individual's tax identification number. Required to onboard the - individual as a US account holder. Only SSN and ITIN are currently - accepted for an individual account holder; other identification - types are rejected. Write-only — never returned in customer - responses. - example: 123-45-6789 diff --git a/openapi/components/schemas/customers/IndividualCustomerFields.yaml b/openapi/components/schemas/customers/IndividualCustomerFields.yaml index 36c980a30..4f049ffba 100644 --- a/openapi/components/schemas/customers/IndividualCustomerFields.yaml +++ b/openapi/components/schemas/customers/IndividualCustomerFields.yaml @@ -24,19 +24,21 @@ allOf: example: US address: $ref: ../common/Address.yaml - taxIdType: + idType: $ref: ./IdentificationType.yaml - taxIdentifier: + identifier: type: string + writeOnly: true description: >- - Tax-identification number. For US persons this is the SSN (format - `###-##-####`) or ITIN. For non-US persons this is the tax number - issued by `taxIdCountryOfIssuance`. + The individual's identification number, required to onboard them as + a US account holder. Only SSN (format `###-##-####`) and ITIN are + currently accepted; other identification types are rejected. + Write-only — never returned in customer responses. example: 123-45-6789 - taxIdCountryOfIssuance: + countryOfIssuance: type: string description: >- - Country that issued the tax identifier (ISO 3166-1 alpha-2). Required - when `taxIdType` is `NON_US_TAX_ID`. + Country that issued the identification (ISO 3166-1 alpha-2). Required + when `idType` is `NON_US_TAX_ID`. example: US - $ref: ./CustomerEdd.yaml diff --git a/openapi/components/schemas/errors/FieldError.yaml b/openapi/components/schemas/errors/FieldError.yaml index 5b74061c0..83570d320 100644 --- a/openapi/components/schemas/errors/FieldError.yaml +++ b/openapi/components/schemas/errors/FieldError.yaml @@ -10,7 +10,7 @@ properties: field: type: string description: Dot-notation path to the offending field. - example: taxIdentifier + example: identifier constraint: $ref: ./FieldConstraint.yaml message: From e6acf94d7d60858469be05e066bdde05a74dc29f Mon Sep 17 00:00:00 2001 From: Aaron Kanter Date: Fri, 14 Aug 2026 10:40:05 +0000 Subject: [PATCH 2/2] Document countryOfIssuance as US-defaulting for individuals The description said countryOfIssuance was required for NON_US_TAX_ID, but the individual endpoints reject that type outright, so the documented combination could never be submitted. Describe what individuals actually get: SSN and ITIN are US-issued, so the field defaults to US and any other value is rejected. Co-Authored-By: akanter --- mintlify/openapi.yaml | 2 +- openapi.yaml | 2 +- .../schemas/customers/IndividualCustomerFields.yaml | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index f73ba6d5b..3e147822c 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -12439,7 +12439,7 @@ components: example: 123-45-6789 countryOfIssuance: type: string - description: Country that issued the identification (ISO 3166-1 alpha-2). Required when `idType` is `NON_US_TAX_ID`. + description: 'Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to `US` and is rejected if set to anything else.' example: US - $ref: '#/components/schemas/CustomerEdd' IndividualCustomer: diff --git a/openapi.yaml b/openapi.yaml index f73ba6d5b..3e147822c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -12439,7 +12439,7 @@ components: example: 123-45-6789 countryOfIssuance: type: string - description: Country that issued the identification (ISO 3166-1 alpha-2). Required when `idType` is `NON_US_TAX_ID`. + description: 'Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to `US` and is rejected if set to anything else.' example: US - $ref: '#/components/schemas/CustomerEdd' IndividualCustomer: diff --git a/openapi/components/schemas/customers/IndividualCustomerFields.yaml b/openapi/components/schemas/customers/IndividualCustomerFields.yaml index 4f049ffba..971ae24fd 100644 --- a/openapi/components/schemas/customers/IndividualCustomerFields.yaml +++ b/openapi/components/schemas/customers/IndividualCustomerFields.yaml @@ -38,7 +38,8 @@ allOf: countryOfIssuance: type: string description: >- - Country that issued the identification (ISO 3166-1 alpha-2). Required - when `idType` is `NON_US_TAX_ID`. + Country that issued the identification (ISO 3166-1 alpha-2). Optional + for an individual account holder: SSN and ITIN are US-issued, so this + defaults to `US` and is rejected if set to anything else. example: US - $ref: ./CustomerEdd.yaml