chore: update v3 OpenAPI specs to v3.818.0

[Ed Fricker (beastawakens)]

User description

Automated v3 OpenAPI spec update for v3.818.0.

Triggered by Adeyemi Adunola (@Kennyinspire) - assigned to you in case it needs a manual merge.

---

PR Type

Enhancement, Documentation

---

Description

• Add new One-Time AML spec (POST /v3/aml)

• Merge AML endpoint, schemas, callbacks into openapi.yaml

• Register new spec in README and docs viewer

• Document api_url claim in v3 token spec; update CHANGELOG

---

Diagram Walkthrough

flowchart LR
  A["v3-one-time-aml-entry.yaml (new)"] -- "merged into" --> B["openapi.yaml"]
  A -- "listed in" --> C["README.md"]
  A -- "listed in" --> D["docs/index.html"]
  E["v3-token.yaml"] -- "documents api_url claim" --> F["CHANGELOG.md"]

Loading

File Walkthrough

	Relevant files
Enhancement	v3-one-time-aml-entry.yaml New One-Time AML API specification                                              specs/v3/v3-one-time-aml-entry.yaml New standalone spec for async One-Time AML screening (POST /v3/aml, job type 15) Defines multipart request schema OneTimeAmlRequest with countries, full_name, aliases, consent, user_details Adds OneTimeAmlAcceptedResponse, AmlPersonMatch, OneTimeAmlCallback, Consent, ApiErrorResponse schemas Documents full error catalogue (400/401/402/403/404/413/415/429/500) and result callback examples +844/-0  openapi.yaml Integrate One-Time AML into full v3 spec                                  specs/v3/openapi.yaml Adds One-Time AML tag and /v3/aml POST operation Adds async result callback definition with multiple outcome examples Adds OneTimeAmlRequest, OneTimeAmlAcceptedResponse, AmlPersonMatch, OneTimeAmlCallback component schemas +774/-0
Documentation	index.html Add One Time Aml to docs spec list                                              docs/index.html Registers v3-one-time-aml-entry spec in the docs viewer spec list +1/-0      README.md Document One-Time AML endpoint in README                                  README.md Adds One Time Aml row to the API specs table with endpoint and summary +1/-0      v3-token.yaml Mention api_url claim in token description                              specs/v3/v3-token.yaml Documents that the issued JWT payload includes api_url base URL +1/-0      CHANGELOG.md Add v3.818.0 changelog entry                                                          CHANGELOG.md Adds v3.818.0 release entry listing updated openapi, v3-one-time-aml-entry, and v3-token +8/-0

---

---

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: 3 🔵🔵🔵⚪⚪

🏅 Score: 80

🧪 No relevant tests

🔒 No security concerns identified

🔀 No multiple PR themes

⚡ Recommended focus areas for review Missing multipart encoding The request body prose states that countries, aliases, consent, user_details, metadata and partner_params must be sent as JSON-encoded strings, but the multipart media type has no encoding section declaring contentType: application/json for those parts. Code generators and request validators will default to non-JSON serialization for arrays/objects (repeated fields or text/plain), producing requests the server explicitly rejects. Adding an encoding block makes the contract machine-readable and consistent with the description. requestBody: required: true description: >- Sent as multipart/form-data. Scalar fields (full_name, birth_year, strict_match, search_existing_user, user_id, source_sdk, source_sdk_version) are plain form fields. Non-scalar fields must be sent as JSON-encoded strings in their form part: the array fields countries and aliases (e.g. countries='["NG","KE"]') and the object fields consent, user_details, metadata, and partner_params. Multipart has no native array encoding, so a bare or repeated countries field is rejected — it must be a JSON array string. content: multipart/form-data: schema: $ref: '#/components/schemas/OneTimeAmlRequest' Contact requirement not enforceable user_details declares anyOf: [required: email], [required: phone_number], but both fields are nullable: true. A payload with email: null (or phone_number: null) satisfies the anyOf while providing no contact information, so the schema does not actually express "at least one of email or phone_number". Combining the anyOf branches with a non-null constraint (e.g. branch schemas that set nullable: false / type: string) would close the gap. type: object required: - given_names - last_name anyOf: - required: - email - required: - phone_number description: >- Consumer-stated PII fields for the screened user. Either email or phone_number must be provided. properties: given_names: type: string minLength: 1 description: Given names of the individual. example: John last_name: type: string minLength: 1 description: Last name / surname of the individual. example: Doe email: type: string format: email nullable: true description: Email address. At least one of email or phone_number is required. example: john@example.com phone_number: type: string pattern: ^\+[1-9]\d{6,14}$ nullable: true description: >- Phone number in E.164 format (must start with +). At least one of email or phone_number is required. example: '+2348012345678' Schema vs described validation mismatch birth_year is typed as string with pattern ^\d{4}$, but the description says a bare integer is also accepted and that values below 1000 or in the future are rejected. As written, the schema rejects integer input and accepts values like 0000-0999, so client-side validation will disagree with server behavior. Consider minimum/maximum semantics or documenting the exact accepted representation. birth_year: type: string pattern: ^\d{4}$ nullable: true description: >- Optional four-digit birth year, minimum 1000 and maximum the current UTC year. A bare integer is also accepted. Full dates, decimals, non-four-digit values, and future years are rejected. example: '1990' Description contradicts schema The request body description lists metadata among "object fields" that must be JSON-encoded, but the schema defines metadata as an array of {name, value} objects. Integrators following the prose may send an object and get a 400. description: >- Sent as multipart/form-data. Scalar fields (full_name, birth_year, strict_match, search_existing_user, user_id, source_sdk, source_sdk_version) are plain form fields. Non-scalar fields must be sent as JSON-encoded strings in their form part: the array fields countries and aliases (e.g. countries='["NG","KE"]') and the object fields consent, user_details, metadata, and partner_params. Multipart has no native array encoding, so a bare or repeated countries field is rejected — it must be a JSON array string.

[prfectionist]

Suggestion: The description states that countries, aliases, consent, user_details, metadata and partner_params must be sent as JSON-encoded strings, but the multipart body declares no encoding. Without an explicit encoding block, generated clients will serialize arrays/objects with the default multipart rules and produce requests the API rejects. [possible issue, importance: 7]

Suggested change

	content:
	multipart/form-data:
	schema:
	$ref: '#/components/schemas/OneTimeAmlRequest'
	content:
	multipart/form-data:
	schema:
	$ref: '#/components/schemas/OneTimeAmlRequest'
	encoding:
	countries:
	contentType: application/json
	aliases:
	contentType: application/json
	consent:
	contentType: application/json
	user_details:
	contentType: application/json
	metadata:
	contentType: application/json
	partner_params:
	contentType: application/json

[prfectionist]

Suggestion: Mirror the JSON-encoding contract in the standalone spec as well, so SDK generation from this entry file produces the JSON-string parts the endpoint requires for the array/object fields. [possible issue, importance: 7]

Suggested change

	content:
	multipart/form-data:
	schema:
	$ref: '#/components/schemas/OneTimeAmlRequest'
	content:
	multipart/form-data:
	schema:
	$ref: '#/components/schemas/OneTimeAmlRequest'
	encoding:
	countries:
	contentType: application/json
	aliases:
	contentType: application/json
	consent:
	contentType: application/json
	user_details:
	contentType: application/json
	metadata:
	contentType: application/json
	partner_params:
	contentType: application/json

[prfectionist]

Suggestion: The description requires uppercase ISO 3166-1 alpha-2 codes, but the schema only constrains length, so ng or 1! validate successfully and are then rejected server-side. Add a pattern to make the contract enforceable by client validators. [general, importance: 6]

Suggested change

	countries:
	type: array
	minItems: 1
	items:
	type: string
	minLength: 2
	maxLength: 2
	countries:
	type: array
	minItems: 1
	items:
	type: string
	minLength: 2
	maxLength: 2
	pattern: '^[A-Z]{2}$'

[prfectionist]

Suggestion: The pattern accepts values below the documented minimum of 1000 (e.g. 0000, 0999), so clients can pass validation and still get a 400. Tighten the pattern to only allow four-digit years starting from 1000. [general, importance: 5]

Suggested change

	birth_year:
	type: string
	pattern: '^\d{4}$'
	nullable: true
	birth_year:
	type: string
	pattern: '^[1-9]\d{3}$'
	nullable: true

[prfectionist]

Suggestion: Because both contact fields are nullable: true, the anyOf: required constraint is satisfied by sending email: null, defeating the "at least one contact" rule declared in the schema. Drop nullable on these fields so the requirement is actually enforceable. [general, importance: 5]

Suggested change

	email:
	type: string
	format: email
	nullable: true
	description: >-
	Email address. At least one of email or phone_number is required.
	example: john@example.com
	phone_number:
	type: string
	pattern: '^\+[1-9]\d{6,14}$'
	nullable: true
	email:
	type: string
	format: email
	description: >-
	Email address. At least one of email or phone_number is required.
	example: john@example.com
	phone_number:
	type: string
	pattern: '^\+[1-9]\d{6,14}$'