chore: update v3 OpenAPI specs to v3.837.0

[Ed Fricker (beastawakens)]

User description

Automated v3 OpenAPI spec update for v3.837.0.

Triggered by Solomon Nsubuga (@solnsubuga) - assigned to you in case it needs a manual merge.

---

PR Type

Enhancement, Documentation

---

Description

• Add synchronous POST /v3/aml/sync OpenAPI spec

• Document headers, idempotency, signatures, 200/408/500 flows

• Update kyc_receipt examples to real URL

• Bump spec version, README table, CHANGELOG

---

Diagram Walkthrough

flowchart LR
  A["v3 One-Time AML spec"] -- "existing" --> B["POST /v3/aml (async, 202 + callback)"]
  A -- "new" --> C["POST /v3/aml/sync (inline result)"]
  C -- "docs" --> D["headers, idempotency, signatures"]
  C -- "responses" --> E["200 examples, 400-500, 408 timeout"]
  A -- "metadata" --> F["README + CHANGELOG + version 1.1.0"]

Loading

File Walkthrough

	Relevant files
Enhancement	v3-one-time-aml-entry.yaml Add synchronous One-Time AML endpoint to entry spec            specs/v3/v3-one-time-aml-entry.yaml Added new POST /v3/aml/sync path with full description, headers, multipart request body, and response examples (clear, block, attention, high risk). Documented error responses: 400, 401, 402, 403, 404, 408, 413, 415, 429, 500 including SmileID-Job-ID headers. Updated API info description to cover both async and sync endpoints; bumped version to 1.1.0. Changed kyc_receipt example from null to a receipts URL. +429/-6  openapi.yaml Add /v3/aml/sync operation to aggregated spec                        specs/v3/openapi.yaml Mirrored the new /v3/aml/sync POST operation into the aggregated OpenAPI spec with parameters, request body, and all response codes/examples. Updated kyc_receipt example value in the existing async AML callback example. +405/-1
Documentation	README.md Document new sync AML endpoint in README                                  README.md Added table row documenting POST /v3/aml/sync for inline One-Time AML results. +1/-0      CHANGELOG.md Add v3.837.0 changelog entry                                                          CHANGELOG.md Added v3.837.0 release entry noting updates to openapi and v3-one-time-aml-entry. +7/-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: 2 🔵🔵⚪⚪⚪

🏅 Score: 80

🧪 No relevant tests

🔒 No security concerns identified

🔀 No multiple PR themes

⚡ Recommended focus areas for review Schema Contradicts Documentation The requestBody description states callback_url is optional for the sync endpoint, but the body reuses OneTimeAmlRequest unchanged — the same schema used by the async endpoint where callback_url is required. Any generated SDK or request validator built from this spec will still enforce callback_url on /v3/aml/sync, contradicting the documented behaviour. A variant schema (or an allOf that overrides required) is needed for the difference to be machine-readable. Same issue in specs/v3/openapi.yaml. requestBody: required: true description: >- Identical to `POST /v3/aml`, except that `callback_url` is optional because no callback is sent. 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' Contradictory 408 Guidance The 408 description says the job is terminal in error and that callers should "resubmit rather than poll", but the accompanying error example message tells the caller to "retrieve its result from /v3/status/{job_id}", and the SmileID-Job-ID header description says it is "The Smile job id to poll for this screening". Integrators reading the example payload will implement polling that can never return a result. The example message and header description should match the stated resubmit-with-idempotency-key behaviour. Same text is duplicated in specs/v3/openapi.yaml. '408': description: >- Request Timeout — the screening provider did not answer within the request deadline, so no result was produced and nothing is billed. The job exists and is terminal in `error`, so `GET /v3/status/{jobId}` will only ever return that error: resubmit rather than poll. Send `SmileID-Idempotency-Key` to make the resubmission safe to repeat. headers: SmileID-Job-ID: description: The Smile job id to poll for this screening. schema: type: string example: job_01h8x9y2z3a4b5c6d7e8f9g0h1 content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: Request Timeout message: >- The screening provider did not respond in time. The job is still recorded — retrieve its result from /v3/status/{job_id}. Placeholder Example Value kyc_receipt examples were changed from null to the truncated placeholder https://receipts.smileidentity.com/..., which is not a resolvable URL. If the OneTimeAmlCallback schema declares format: uri for this field, example-validation tooling will flag it, and consumers copying the example get an invalid link. A realistic full URL (or retaining null for the clear case) would be safer. Also worth confirming that the block_high_risk example — where the request was blocked before screening ran — should carry a receipt URL at all. kyc_receipt: 'https://receipts.smileidentity.com/...'

[prfectionist]

Suggestion: The 408 description says the job is terminal in error and callers should resubmit rather than poll, but the example message instructs them to retrieve the result from /v3/status/{job_id}. This contradiction will push integrators into a useless polling loop; make the example consistent with the documented behaviour. [general, importance: 5]

Suggested change

	example:
	status: Request Timeout
	message: >-
	The screening provider did not respond in time. The job is still recorded —
	retrieve its result from /v3/status/{job_id}.
	example:
	status: Request Timeout
	message: >-
	The screening provider did not respond in time. No result was produced and
	nothing was billed — resubmit with the same SmileID-Idempotency-Key.

[prfectionist]

Suggestion: For the 408 case the spec simultaneously says the job is terminal in error (resubmit, do not poll) and tells the caller to poll /v3/status/{job_id}. Align both the header description and the example message with the resubmit-with-idempotency-key guidance. [general, importance: 5]

Suggested change

	headers:
	SmileID-Job-ID:
	description: The Smile job id to poll for this screening.
	schema:
	type: string
	example: job_01h8x9y2z3a4b5c6d7e8f9g0h1
	content:
	application/json:
	schema:
	$ref: '#/components/schemas/ApiErrorResponse'
	example:
	status: Request Timeout
	message: >-
	The screening provider did not respond in time. The job is still recorded —
	retrieve its result from /v3/status/{job_id}.
	headers:
	SmileID-Job-ID:
	description: The Smile job id recorded for this screening (terminal in `error`).
	schema:
	type: string
	example: job_01h8x9y2z3a4b5c6d7e8f9g0h1
	content:
	application/json:
	schema:
	$ref: '#/components/schemas/ApiErrorResponse'
	example:
	status: Request Timeout
	message: >-
	The screening provider did not respond in time. No result was produced and
	nothing was billed — resubmit with the same SmileID-Idempotency-Key.

[prfectionist]

Suggestion: The documented 16–128 character and character-set constraints for the idempotency key are not expressed in the schema, so generated clients and validators will happily send keys that the API rejects (or worse, silently start a new billed screening). Encode the constraints as minLength, maxLength, and pattern. [general, importance: 5]

Suggested change

	- name: SmileID-Idempotency-Key
	in: header
	required: false
	description: >-
	Opaque key, 16 to 128 characters of `A-Z a-z 0-9 - _`, that makes a submission safe to
	repeat. The job id is derived from it, so a request carrying a key you have already used
	resolves to that same job: it returns the original result and screens — and bills —
	nothing a second time. Send one whenever you might retry, since a retry without a key
	starts a new, separately billed screening.
	schema:
	type: string
	example: kuda-onboarding-8f14e45fceea167a
	- name: SmileID-Idempotency-Key
	in: header
	required: false
	description: >-
	Opaque key, 16 to 128 characters of `A-Z a-z 0-9 - _`, that makes a submission safe to
	repeat. The job id is derived from it, so a request carrying a key you have already used
	resolves to that same job: it returns the original result and screens — and bills —
	nothing a second time. Send one whenever you might retry, since a retry without a key
	starts a new, separately billed screening.
	schema:
	type: string
	minLength: 16
	maxLength: 128
	pattern: '^[A-Za-z0-9_-]{16,128}$'
	example: kuda-onboarding-8f14e45fceea167a