chore: sync v3 specs from lambda v3.549.0

[Ed Fricker (beastawakens)]

User description

Automated v3 OpenAPI spec sync from smileidentity/lambda v3.549.0.

---

PR Type

Enhancement

---

Description

• Add new API specs: biometric auth, block user, document verification, enhanced doc verification, smart selfie compare, services, supported documents, ID status, verification status

• Restructure user PII fields into nested user_details object across existing specs

• Rename terminology from "job" to "verification" throughout

• Remove SmileID-Partner-ID header requirement from several endpoints

• Update enrollment endpoint path from /v3/enroll to /v3/registration

• Update token API partner ID pattern and add user_id field

---

Diagram Walkthrough

flowchart LR
  A["New Specs Added"] -- "biometric auth, block user, doc verification, etc." --> B["V3 API Specs"]
  C["Existing Specs Updated"] -- "user_details nesting, job→verification rename" --> B
  D["Token API"] -- "pattern fix, user_id field" --> B

Loading

File Walkthrough

	Relevant files
Documentation	1 files CHANGELOG.md Add v3.549.0 changelog entry listing updated specs              +18/-0
Enhancement	14 files v3-biometric-authentication-entry.yaml Add new biometric authentication endpoint spec                      +280/-0  v3-biometric-enrollment-entry.yaml Restructure to user_details, rename path and terminology  +40/-42  v3-biometric-kyc-entry.yaml Restructure to user_details, rename job to verification    +41/-35  v3-block-user.yaml Add new block/unblock user endpoint spec                                  +261/-0  v3-document-verification-entry.yaml Add new document verification endpoint spec                            +414/-0  v3-enhanced-document-verification-entry.yaml Add new enhanced document verification endpoint spec          +424/-0  v3-enhanced-kyc-entry.yaml Restructure to user_details, add validation errors, remove partner header +48/-37  v3-enhanced-kyc-job-status.yaml Add new verification status polling endpoint spec                +152/-0  v3-id-status.yaml Add new ID type availability status endpoint spec                +140/-0  v3-replay-callback.yaml Rename job to verification, remove partner header                +20/-27  v3-services.yaml Add new services API for bank codes and ID types                  +205/-0  v3-smart-selfie-compare-entry.yaml Add new smart selfie compare endpoint spec                              +300/-0  v3-supported-documents.yaml Add new supported documents listing endpoint spec                +187/-0  v3-token.yaml Update partner ID pattern, add user_id and operationId      +6/-3

---

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[prfectionist]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🏅 Score: 75

🧪 No relevant tests

🔒 No security concerns identified

🔀 No multiple PR themes

⚡ Recommended focus areas for review Inconsistent Enum Casing The AcceptedResponse status enum was changed from [Accepted] to [accepted] (lowercase), and the example was also changed to accepted. However, in other new specs like v3-biometric-authentication-entry.yaml and v3-smart-selfie-compare-entry.yaml, the enum remains [Accepted] (capitalized). This inconsistency could confuse SDK consumers who parse the status field. enum: [accepted] Missing Validation Constraint The user_details object requires given_names and last_name but the "at least one of email or phone_number" constraint is only documented in the description, not enforced in the schema (no oneOf, anyOf, or custom validation keyword). This is consistent with other specs in this PR but means the OpenAPI schema alone cannot validate this business rule, potentially leading to invalid requests passing schema validation. user_details: type: object required: - given_names - last_name description: >- Consumer-stated PII fields for the user. Either email or phone_number must be provided. properties: given_names: type: string minLength: 1 example: Jane last_name: type: string minLength: 1 example: Smith email: type: string format: email nullable: true description: At least one of email or phone_number is required. example: jane@example.com phone_number: type: string pattern: '^\+' nullable: true description: Phone number in E.164 format. At least one of email or phone_number is required. example: '+2348012345678' Inconsistent Terminology The AcceptedResponse uses description: TypeID format job identifier for tracking. (line 392) and the 202 response says "job submitted for processing" (line 100), while other updated specs in this PR have renamed "job" to "verification" throughout. This new file should follow the same terminology convention established by the other changes in this PR. description: TypeID format job identifier for tracking. example: job_01h8x9y2z3a4b5c6d7e8f9g0h1 user_id: type: string description: TypeID format user identifier (or partner-provided User-ID). example: user_01h8x9y2z3a4b5c6d7e8f9g0h1 created_at: type: string format: date-time description: ISO 8601 timestamp of when the job was created. Breaking Pattern Change The partner ID pattern was changed from ^\d{3,}$ (at least 3 digits, allowing leading zeros) to ^[1-9]\d*$ (no leading zeros, minimum 1 digit). This is a potentially breaking change for partners whose IDs have leading zeros or are exactly 1-2 digits. The description also changed from "at least 3 digits" to "no leading zeros" which relaxes the minimum length constraint. pattern: '^[1-9]\d*$' Breaking API Change The endpoint path changed from /v3/enroll to /v3/registration and the SmileID-Partner-ID header was removed. These are breaking changes for existing API consumers. The removal of the Partner-ID header means existing clients sending this header may need to be updated, and the path change will break all existing integrations targeting /v3/enroll. /v3/registration:

[prfectionist]

Suggestion: The AcceptedResponse status enum uses Accepted (capitalized) here, but other new specs like v3-biometric-kyc-entry.yaml and v3-document-verification-entry.yaml use accepted (lowercase). This inconsistency will cause SDK code generation issues and client-side parsing failures when consumers check the status field across different endpoints. [general, importance: 6]

Suggested change

	AcceptedResponse:
	type: object
	properties:
	status:
	type: string
	enum: [Accepted]
	AcceptedResponse:
	type: object
	properties:
	status:
	type: string
	enum: [accepted]

[prfectionist]

Suggestion: The new pattern ^[1-9]\d*$ allows single-digit partner IDs (e.g., "1"), which is less restrictive than the previous ^\d{3,}$ (minimum 3 digits). If the intent is to disallow leading zeros while still requiring at least 3 digits, the pattern should enforce a minimum length. [general, importance: 7]

Suggested change

	pattern: '^[1-9]\d*$'
	example: '1234'
	pattern: '^[1-9]\d{2,}$'
	example: '1234'

[prfectionist]

Suggestion: The TypeID pattern here uses [0-9a-z]{26} but the v3-enhanced-kyc-job-status.yaml spec uses the correct Crockford Base32 character set [0-9a-hjkmnp-tv-z]{26} (excluding i, l, o, u). This pattern would incorrectly accept invalid TypeIDs containing those excluded characters. [possible issue, importance: 8]

Suggested change

	pattern: '^job_[0-9a-z]{26}$'
	pattern: '^job_[0-9a-hjkmnp-tv-z]{26}$'

[prfectionist]

Suggestion: The response example uses status: accepted (lowercase) but the AcceptedResponse schema below defines enum: [Accepted] (capitalized). The example will fail schema validation. Either the enum or the example needs to be aligned. [possible issue, importance: 8]

Suggested change

	example:
	status: Accepted
	status: accepted
	message: Request accepted and queued for processing.
	job_id: job_01h8x9y2z3a4b5c6d7e8f9g0h1
	example:
	status: Accepted
	message: Request accepted and queued for processing.
	job_id: job_01h8x9y2z3a4b5c6d7e8f9g0h1

[Copilot]

Pull request overview

Automated sync of the v3 OpenAPI specifications from smileidentity/lambda v3.549.0, updating existing endpoint specs and adding several new v3 service/reference endpoints.

Changes:

• Added new v3 spec documents for services/reference endpoints (e.g., supported documents, bank codes, ID status, verification status, block user).
• Updated multiple existing v3 endpoint specs (token, enrollment, KYC, replay callback, etc.) to reflect upstream contract and naming/field-structure changes.
• Updated CHANGELOG.md with a new v3.549.0 entry.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
specs/v3/v3-token.yaml	Updates token endpoint metadata/validation and request body schema.
specs/v3/v3-supported-documents.yaml	Adds unauthenticated supported-documents listing endpoint spec.
specs/v3/v3-smart-selfie-compare-entry.yaml	Adds smart selfie compare async entry endpoint spec.
specs/v3/v3-services.yaml	Adds unauthenticated “services” reference endpoints (bank codes, supported ID types).
specs/v3/v3-replay-callback.yaml	Updates replay-callback wording and authentication/header requirements; adds operationId.
specs/v3/v3-id-status.yaml	Adds authenticated ID availability/status endpoint spec.
specs/v3/v3-enhanced-kyc-job-status.yaml	Adds verification status lookup endpoint spec.
specs/v3/v3-enhanced-kyc-entry.yaml	Updates Enhanced KYC entry schema (notably user_details) and operationId.
specs/v3/v3-enhanced-document-verification-entry.yaml	Adds enhanced document verification multipart entry endpoint spec.
specs/v3/v3-document-verification-entry.yaml	Adds document verification multipart entry endpoint spec.
specs/v3/v3-block-user.yaml	Adds authenticated block/unblock user endpoint spec.
specs/v3/v3-biometric-kyc-entry.yaml	Updates biometric KYC entry schema (notably user_details) and accepted response shape.
specs/v3/v3-biometric-enrollment-entry.yaml	Updates enrollment endpoint path and request schema (notably user_details).
specs/v3/v3-biometric-authentication-entry.yaml	Adds biometric authentication async entry endpoint spec.
CHANGELOG.md	Adds v3.549.0 changelog entry for the spec sync.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.