Skip to content

feat: updating document missing errors to be more specific #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pengying merged 1 commit into from
Mar 25, 2026
Merged

feat: updating document missing errors to be more specific #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 32 additions & 14 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

46 changes: 32 additions & 14 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion openapi/components/schemas/common/NgnAccountInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ properties:
description: Nigerian bank account number
minLength: 10
maxLength: 10
example: 0123456789
example: '0123456789'
Copy link
Copy Markdown
Contributor Author

@pengying pengying Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AaryamanBhute I think this fix needs to be at the generator level? Lint complaining

pattern: ^[0-9]{10}$
bankName:
type: string
Expand Down
2 changes: 1 addition & 1 deletion openapi/components/schemas/common/PhpAccountInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,4 @@ properties:
description: Bank account number
minLength: 1
maxLength: 34
example: 001234567890
example: '001234567890'
2 changes: 1 addition & 1 deletion openapi/components/schemas/common/SgdAccountInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ properties:
description: Bank account number
minLength: 1
maxLength: 34
example: 0123456789
example: '0123456789'
swiftCode:
type: string
description: The SWIFT/BIC code of the bank
Expand Down
26 changes: 25 additions & 1 deletion openapi/components/schemas/documents/DocumentType.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,29 @@ enum:
- UTILITY_BILL
- SELFIE
- OTHER
description: Type of identity or business verification document
description: >-
Type of identity or business verification document. Document types are
grouped by verification category:

**Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID

**Business — Legal presence** — CERTIFICATE_OF_INCORPORATION,
ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION,
STATE_REGISTRY_EXCERPT

**Business — Company details** — INFORMATION_STATEMENT,
STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION,
ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION,
INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE

**Business — Control structure** — ARTICLES_OF_INCORPORATION,
ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE,
INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT

**Business — Ownership structure** — SHAREHOLDER_REGISTER,
INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE,
STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION,
ARTICLES_OF_ASSOCIATION

**Proof of address** — PROOF_OF_ADDRESS
example: PASSPORT
Comment on lines +22 to 47
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Several enum values not assigned to a verification category

Seven document types in the DocumentType enum are not listed under any verification category in the updated description: BANK_STATEMENT, TAX_RETURN, BUSINESS_LICENSE, POWER_OF_ATTORNEY, UTILITY_BILL, SELFIE, and OTHER.

This is particularly noticeable for UTILITY_BILL and BANK_STATEMENT, which were previously listed as accepted proof-of-address document types in the API response examples (now removed in this PR). Developers scanning this description for guidance on what to upload will have no indication of when (if ever) these document types are appropriate.

If these document types are still accepted by the API for any error category, please add them to the relevant category. If they are genuinely unused or deprecated, consider adding a note explaining their status (e.g., "legacy types, no longer accepted by any verification requirement").

Prompt To Fix With AI 
This is a comment left during a code review.
Path: openapi/components/schemas/documents/DocumentType.yaml
Line: 22-47

Comment:
**Several enum values not assigned to a verification category**

Seven document types in the `DocumentType` enum are not listed under any verification category in the updated description: `BANK_STATEMENT`, `TAX_RETURN`, `BUSINESS_LICENSE`, `POWER_OF_ATTORNEY`, `UTILITY_BILL`, `SELFIE`, and `OTHER`.

This is particularly noticeable for `UTILITY_BILL` and `BANK_STATEMENT`, which were previously listed as accepted proof-of-address document types in the API response examples (now removed in this PR). Developers scanning this description for guidance on what to upload will have no indication of when (if ever) these document types are appropriate.

If these document types are still accepted by the API for any error category, please add them to the relevant category. If they are genuinely unused or deprecated, consider adding a note explaining their status (e.g., "legacy types, no longer accepted by any verification requirement").

How can I resolve this? If you propose a fix, please make it concise.

24 changes: 23 additions & 1 deletion openapi/components/schemas/verifications/VerificationError.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,29 @@ properties:
description: >-
Document types that would satisfy this requirement. The integrator
can upload any one of the listed types. Present when type is
MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.
MISSING_LEGAL_PRESENCE_DOCUMENT,
MISSING_COMPANY_DETAILS_DOCUMENT,
MISSING_CONTROL_STRUCTURE_DOCUMENT,
MISSING_OWNERSHIP_STRUCTURE_DOCUMENT,
MISSING_PROOF_OF_ADDRESS_DOCUMENT,
MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.


| Error Type | Accepted Document Types |

|---|---|

| MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT |

| MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE |

| MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT |

| MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION |

| MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS |

| MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID |
Comment on lines 24 to +49
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Broken Markdown table due to >- folded YAML scalar

The >- (folded) block scalar folds line breaks between non-empty lines into spaces and converts individual blank lines into literal newlines. Because there is one blank line between each table row in this source file (e.g. lines 36, 38, 40, 42, 44, 46, 48), the output string has a \n (single newline → blank line) separating every row from the next. The bundled openapi.yaml and mintlify/openapi.yaml confirm this — they serialize the result as a |- (literal) block and show blank lines between rows 1–2, 2–3, etc. In standard Markdown, a blank line between table rows terminates the table, so rows 2–6 render as paragraph text rather than table cells.

Switch to |- (literal block scalar) and remove the blank lines between table rows so they remain consecutive:

Suggested change
description: >-
Document types that would satisfy this requirement. The integrator
can upload any one of the listed types. Present when type is
MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.
MISSING_LEGAL_PRESENCE_DOCUMENT,
MISSING_COMPANY_DETAILS_DOCUMENT,
MISSING_CONTROL_STRUCTURE_DOCUMENT,
MISSING_OWNERSHIP_STRUCTURE_DOCUMENT,
MISSING_PROOF_OF_ADDRESS_DOCUMENT,
MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.
| Error Type | Accepted Document Types |
|---|---|
| MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT |
| MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE |
| MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT |
| MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION |
| MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS |
| MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID |
description: |-
Document types that would satisfy this requirement. The integrator
can upload any one of the listed types. Present when type is
MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_COMPANY_DETAILS_DOCUMENT,
MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT,
MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.
| Error Type | Accepted Document Types |
|---|---|
| MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT |
| MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE |
| MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT |
| MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION |
| MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS |
| MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID |

After making this source change, re-run make build to regenerate the bundles.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: openapi/components/schemas/verifications/VerificationError.yaml
Line: 24-49

Comment:
**Broken Markdown table due to `>-` folded YAML scalar**

The `>-` (folded) block scalar folds line breaks between non-empty lines into spaces and converts individual blank lines into literal newlines. Because there is one blank line between each table row in this source file (e.g. lines 36, 38, 40, 42, 44, 46, 48), the output string has a `\n` (single newline → blank line) separating every row from the next. The bundled `openapi.yaml` and `mintlify/openapi.yaml` confirm this — they serialize the result as a `|-` (literal) block and show blank lines between rows 1–2, 2–3, etc. In standard Markdown, a blank line between table rows terminates the table, so rows 2–6 render as paragraph text rather than table cells.

Switch to `|-` (literal block scalar) and remove the blank lines between table rows so they remain consecutive:

```suggestion
    description: |-
      Document types that would satisfy this requirement. The integrator
      can upload any one of the listed types. Present when type is
      MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_COMPANY_DETAILS_DOCUMENT,
      MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT,
      MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.

      | Error Type | Accepted Document Types |
      |---|---|
      | MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT |
      | MISSING_COMPANY_DETAILS_DOCUMENT | INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, CERTIFICATE_OF_INCORPORATION, INCUMBENCY_CERTIFICATE, GOOD_STANDING_CERTIFICATE |
      | MISSING_CONTROL_STRUCTURE_DOCUMENT | ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, INCUMBENCY_CERTIFICATE, INFORMATION_STATEMENT, STATE_REGISTRY_EXCERPT |
      | MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, INFORMATION_STATEMENT, INCUMBENCY_CERTIFICATE, STATE_REGISTRY_EXCERPT, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION |
      | MISSING_PROOF_OF_ADDRESS_DOCUMENT | PROOF_OF_ADDRESS |
      | MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID |
```

After making this source change, re-run `make build` to regenerate the bundles.

How can I resolve this? If you propose a fix, please make it concise.

reason:
type: string
description: Human-readable description of the issue
Expand Down
12 changes: 10 additions & 2 deletions openapi/components/schemas/verifications/VerificationErrorType.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,17 @@ type: string
enum:
- MISSING_FIELD
- INVALID_FIELD
- MISSING_DOCUMENT
- MISSING_LEGAL_PRESENCE_DOCUMENT
- MISSING_COMPANY_DETAILS_DOCUMENT
- MISSING_CONTROL_STRUCTURE_DOCUMENT
- MISSING_OWNERSHIP_STRUCTURE_DOCUMENT
- MISSING_PROOF_OF_ADDRESS_DOCUMENT
- MISSING_IDENTITY_DOCUMENT
- INVALID_DOCUMENT
- EXPIRED_DOCUMENT
- MISSING_BENEFICIAL_OWNER
description: Type of verification error
description: >-
Type of verification error. The category-specific MISSING_*_DOCUMENT
types indicate which document category is needed and determine the
accepted document types returned in acceptedDocumentTypes.
example: MISSING_FIELD
2 changes: 1 addition & 1 deletion openapi/paths/customers/customers.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ post:
taxId: 47-1234567
countriesOfOperation:
- US
businessType: FINTECH
businessType: INFORMATION
purposeOfAccount: CONTRACTOR_PAYOUTS
sourceOfFunds: Funds derived from customer payments for software services
expectedMonthlyTransactionCount: COUNT_100_TO_500
Expand Down
4 changes: 1 addition & 3 deletions openapi/paths/verifications/verifications.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,9 @@ post:
field: customer.address.line1
reason: Business address line 1 is required
- resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001
type: MISSING_DOCUMENT
type: MISSING_PROOF_OF_ADDRESS_DOCUMENT
acceptedDocumentTypes:
- PROOF_OF_ADDRESS
- UTILITY_BILL
- BANK_STATEMENT
reason: Proof of address document is required
- resourceId: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002
type: MISSING_FIELD
Expand Down
4 changes: 1 addition & 3 deletions openapi/webhooks/verification-update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,9 @@ post:
verificationStatus: RESOLVE_ERRORS
errors:
- resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001
type: MISSING_DOCUMENT
type: MISSING_PROOF_OF_ADDRESS_DOCUMENT
acceptedDocumentTypes:
- PROOF_OF_ADDRESS
- UTILITY_BILL
- BANK_STATEMENT
reason: Proof of address document is required
createdAt: '2025-08-15T14:00:00Z'
responses:
Expand Down
Loading