> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit Verification from URL > Submit a verification for a user with documents provided via presigned URLs. This endpoint is useful when documents are already stored in a cloud storage provider (e.g. AWS S3, Google Cloud Storage) and accepts identity document, residence document, and selfie verification payloads. A verification is a check performed on a user to verify information provided by the user, typically by a third party such as an identity verification provider. Checks are most commonly performed on documents, such as a passport or driver's license, but can also include sanctions or Politically Exposed Person (PEP) checks. ## URL and file requirements URLs must be HTTPS URLs on allowlisted domains, up to 4096 characters. Each redirect target must also use HTTPS and an allowlisted domain. The server follows up to three redirects. The server extracts the decoded filename from the submitted URL path. The filename must be 255 bytes or less, cannot be `.` or `..`, and cannot contain path separators or control characters. It must include an extension matching the detected file content. Downloaded files can be up to 150 MiB (157286400 bytes). The size limit is enforced from the `Content-Length` header and while streaming the response body. Accepted file types are JPEG/JPG, PNG, PDF, MP4/M4V, WebM, and MOV/QuickTime. Passport identity document submissions must omit `back_url`. Identity document submissions must include raw verifier response evidence for KYC verification. Provide either `metadata.verifier_response` or `verifier_response_url`. If `verifier_response_url` is provided, that file is used as raw verifier response evidence instead of `metadata.verifier_response`. `metadata.verified_at` must be a valid date-time. Invalid values are rejected instead of being replaced with the submission time. If file upload or final verification submission fails, files uploaded for that request are discarded. ## Domain allowlisting For security, the domains you use for presigned URLs must be allowlisted before you can use this endpoint. Contact your account manager to configure the allowed domains for your integration. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json post /v1/users/{user_id}/verifications/url openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversions (rule-driven and one-shot fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Funds (deposits, withdrawals, addresses, transactions), Portfolio, Earn, Reports, Webhooks, and Ramp (hosted fiat-to-crypto on-ramp checkout). All requests must be authenticated. All monetary values are decimal strings; all timestamps are ISO 8601 UTC. List endpoints are cursor-paginated. Errors follow a uniform shape (see `*ErrorResponse` schemas). version: v1 contact: name: Payward Services API Support url: https://docs.payward.com email: api-support@payward.com servers: - url: https://api.services.payward.com description: Production security: - ApiKey: [] ApiNonce: [] ApiSign: [] tags: - name: Users description: >- Users and headless-user onboarding flows that the partner manages. - **Create User** provisions a user with full identity verification fields collected up front. - **Create Headless User** provisions a lightweight user when your licensing agreement allows you to manage KYC data outside Payward. - **Get User** retrieves the user's profile, verification status, and required actions. - **Update User** updates user profile fields and may re-trigger verification. Use the returned user `id` for calls that require the user's identifier. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversions description: >- Rule-driven and one-shot fiat ↔ crypto value movement, including conversion rules, deposits, and whitelisted wallets. - name: Earn description: >- Manage auto-earn preferences and retrieve allocation and reward information. - name: Funds description: >- Deposits, withdrawals, addresses, methods, and the consolidated funding-transactions ledger. - name: Portfolio description: End-user portfolio summary, history, and transaction views. - name: Price Trigger Swaps description: Limit-style orders that execute when a configured price trigger is met. - name: On-chain Swaps description: >- Wallet-funded onchain quote trading for xStock and USDC pairs. On-chain quotes settle on-chain through the Payward on-chain proxy contract. - name: Ramp description: >- Hosted fiat-to-crypto on-ramp checkout: country / fiat / payment-method / cryptocurrency-asset discovery, transaction limits and prospective quotes, and the hosted checkout URL. - name: Reports description: Settlement and reconciliation reports for the partner. - name: Swaps description: >- Direct partner-to-Payward swap quotes and executions (institutional FX-style trading). - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/users/{user_id}/verifications/url: post: tags: - Verifications summary: Submit Verification from URL description: >- Submit a verification for a user with documents provided via presigned URLs. This endpoint is useful when documents are already stored in a cloud storage provider (e.g. AWS S3, Google Cloud Storage) and accepts identity document, residence document, and selfie verification payloads. A verification is a check performed on a user to verify information provided by the user, typically by a third party such as an identity verification provider. Checks are most commonly performed on documents, such as a passport or driver's license, but can also include sanctions or Politically Exposed Person (PEP) checks. ## URL and file requirements URLs must be HTTPS URLs on allowlisted domains, up to 4096 characters. Each redirect target must also use HTTPS and an allowlisted domain. The server follows up to three redirects. The server extracts the decoded filename from the submitted URL path. The filename must be 255 bytes or less, cannot be `.` or `..`, and cannot contain path separators or control characters. It must include an extension matching the detected file content. Downloaded files can be up to 150 MiB (157286400 bytes). The size limit is enforced from the `Content-Length` header and while streaming the response body. Accepted file types are JPEG/JPG, PNG, PDF, MP4/M4V, WebM, and MOV/QuickTime. Passport identity document submissions must omit `back_url`. Identity document submissions must include raw verifier response evidence for KYC verification. Provide either `metadata.verifier_response` or `verifier_response_url`. If `verifier_response_url` is provided, that file is used as raw verifier response evidence instead of `metadata.verifier_response`. `metadata.verified_at` must be a valid date-time. Invalid values are rejected instead of being replaced with the submission time. If file upload or final verification submission fails, files uploaded for that request are discarded. ## Domain allowlisting For security, the domains you use for presigned URLs must be allowlisted before you can use this endpoint. Contact your account manager to configure the allowed domains for your integration. operationId: submitVerificationFromUrl parameters: - in: path name: user_id required: true schema: type: string minLength: 14 maxLength: 42 style: simple example: AA45N8G4MLDYWAR7 description: >- ID of the user the request applies to. For partners operating in the B2B2C model, this is the Sub-User the request is acting on behalf of. requestBody: content: application/json: schema: oneOf: - type: object properties: type: type: string enum: - identity_document metadata: description: Metadata about the verification. type: object properties: identity: description: The identity of the person in the document type: object properties: full_name: description: User's full name type: object properties: first_name: description: User's first name type: string minLength: 1 maxLength: 256 middle_name: description: User's middle name type: - string - 'null' minLength: 1 maxLength: 256 last_name: description: User's last name type: string minLength: 1 maxLength: 256 required: - first_name - last_name birth: description: User birth details. type: object properties: date: description: User's date of birth type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ format: date example: '2023-03-13' required: - date required: - full_name - birth document_type: description: Type of identity document type: string enum: - passport - drivers_license - id_card - residence_card - special_permanent_residence_card document_number: description: >- Number of the document (e.g. driver's license number) type: string minLength: 1 maxLength: 256 issuing_country: description: Country of issuance of the identity document allOf: - $ref: '#/components/schemas/CountryCode' nationality: description: >- Nationality of the identified person according to the document type: - string - 'null' allOf: - $ref: '#/components/schemas/CountryCode' verifier: description: Name of the verification provider. type: string minLength: 1 maxLength: 256 verified_at: description: >- The date and time the verification was completed. Invalid values are rejected. type: string format: date-time example: '2023-03-13T12:34:56Z' verifier_response: description: >- JSON object response from the verifier. Required for identity document submissions unless `verifier_response_url` is provided. type: - object - 'null' additionalProperties: true external_verification_id: description: >- External document id of the verification that can be provided by the partner type: - string - 'null' minLength: 1 maxLength: 256 expiration_date: description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: - string - 'null' pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ format: date example: '2028-03-13' required: - identity - document_type - document_number - issuing_country - verified_at - verifier front_url: description: >- Presigned URL to the front side of the identity document. The filename is extracted from the URL path and must meet the URL and file requirements. type: string minLength: 1 maxLength: 4096 format: uri back_url: description: >- Presigned URL to the back side of the identity document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. Passport submissions must omit this field. type: - string - 'null' minLength: 1 maxLength: 4096 format: uri verifier_response_url: description: >- Presigned URL to the verifier response document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. If provided, this file is used as the raw verifier response evidence instead of `metadata.verifier_response`. type: - string - 'null' minLength: 1 maxLength: 4096 format: uri required: - metadata - type - front_url - type: object properties: type: type: string enum: - residence_document metadata: description: Metadata about the verification. type: object properties: address: description: The address captured in this document type: object properties: city: description: City type: string minLength: 1 maxLength: 128 postal_code: description: Postal code type: string minLength: 1 maxLength: 32 province: description: Province or state type: - string - 'null' minLength: 1 maxLength: 128 country: description: Country allOf: - $ref: '#/components/schemas/CountryCode' line1: description: Address line 1 type: string minLength: 1 maxLength: 256 line2: description: Address line 2 type: - string - 'null' minLength: 1 maxLength: 256 required: - city - country - line1 - postal_code document_type: description: Type of residence verification document type: string enum: - bank_statement - credit_card_statement - employer_letter_or_work_contract - government_issued_document - home_or_rental_insurance - internet_or_cable_bill - mobile_phone_bill - mortgage_statement - official_government_letter - passport_address_page - rental_or_lease_agreement - residence_certificate - social_insurance_payment_receipt - tax_receipt - tax_return - utility_bill - other document_number: description: >- Number of the document (e.g. driver's license number) type: - string - 'null' minLength: 1 maxLength: 256 verifier: description: Name of the verification provider. type: string minLength: 1 maxLength: 256 verified_at: description: >- The date and time the verification was completed. Invalid values are rejected. type: string format: date-time example: '2023-03-13T12:34:56Z' verifier_response: description: JSON object response from the verifier type: - object - 'null' additionalProperties: true external_verification_id: description: >- External document id of the verification that can be provided by the partner type: - string - 'null' minLength: 1 maxLength: 256 expiration_date: description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: - string - 'null' pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ format: date example: '2028-03-13' required: - address - document_type - verified_at - verifier document_url: description: >- Presigned URL to the residence document. The filename is extracted from the URL path and must meet the URL and file requirements. type: string minLength: 1 maxLength: 4096 format: uri verifier_response_url: description: >- Presigned URL to the verifier response document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. If provided, this file is used as the raw verifier response evidence instead of `metadata.verifier_response`. type: - string - 'null' minLength: 1 maxLength: 4096 format: uri required: - metadata - type - document_url - type: object properties: type: type: string enum: - selfie metadata: description: Metadata about the verification. type: object properties: selfie_type: description: Type of selfie type: string enum: - selfie - selfie_capture_video verifier: description: Name of the verification provider. type: string minLength: 1 maxLength: 256 verified_at: description: >- The date and time the verification was completed. Invalid values are rejected. type: string format: date-time example: '2023-03-13T12:34:56Z' verifier_response: description: JSON object response from the verifier type: - object - 'null' additionalProperties: true external_verification_id: description: >- External document id of the verification that can be provided by the partner type: - string - 'null' minLength: 1 maxLength: 256 expiration_date: description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: - string - 'null' pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ format: date example: '2028-03-13' required: - selfie_type - verified_at - verifier selfie_url: description: >- Presigned URL to the selfie. The filename is extracted from the URL path and must meet the URL and file requirements. type: string minLength: 1 maxLength: 4096 format: uri verifier_response_url: description: >- Presigned URL to the verifier response document (optional). The filename is extracted from the URL path and must meet the URL and file requirements. If provided, this file is used as the raw verifier response evidence instead of `metadata.verifier_response`. type: - string - 'null' minLength: 1 maxLength: 4096 format: uri required: - metadata - type - selfie_url examples: identity-document: summary: Identity document value: type: identity_document metadata: identity: full_name: first_name: Alex last_name: Morgan birth: date: '2023-03-13' document_type: passport document_number: A1234567 issuing_country: AD verifier: example verified_at: '2023-03-13T12:34:56Z' verifier_response: status: approved front_url: >- https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256 required: true responses: '200': description: Response content: application/json: schema: type: object properties: data: type: object properties: verification_id: description: Internal ID of the verification. type: string minLength: 1 maxLength: 256 required: - verification_id required: - data example: data: verification_id: ver_01J0M9P2T7K3W2BHJ7T9 examples: created-verification: summary: Created verification value: data: verification_id: ver_01J0M9P2T7K3W2BHJ7T9 headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '501': description: Error response content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/UnavailableError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '504': description: Deadline exceeded content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' security: - ApiKey: [] ApiNonce: [] ApiSign: [] x-codeSamples: - lang: bash label: curl source: >- curl -X POST "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/url" \ -H "API-Key: $PWS_API_KEY" \ -H "API-Nonce: $PWS_API_NONCE" \ -H "API-Sign: $PWS_API_SIGN" \ -H "Content-Type: application/json" \ -d '{ "type": "identity_document", "metadata": { "identity": { "full_name": { "first_name": "Alex", "last_name": "Morgan" }, "birth": { "date": "2023-03-13" } }, "document_type": "passport", "document_number": "A1234567", "issuing_country": "AD", "verifier": "example", "verified_at": "2023-03-13T12:34:56Z", "verifier_response": { "status": "approved" } }, "front_url": "https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256" }' components: schemas: CountryCode: description: ISO 3166-1 alpha-2 country code. type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C minLength: 2 maxLength: 2 example: US BadRequestError: description: Request validation failed or the request could not be processed. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 400 code: type: string enum: - bad_request UnauthenticatedError: description: Authentication credentials are missing, invalid, or not accepted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 401 code: type: string enum: - unauthenticated ForbiddenError: description: The authenticated caller is not allowed to perform this operation. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 403 code: type: string enum: - forbidden ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 500 code: type: string enum: - internal UnimplementedError: description: The operation is not implemented by the upstream service. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 501 code: type: string enum: - unimplemented UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 503 code: type: string enum: - unavailable DeadlineExceededError: description: The upstream service did not complete the request before the deadline. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 504 code: type: string enum: - deadline_exceeded PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri headers: RequestId: description: >- Unique identifier for tracing this request across services. Include in support tickets. schema: type: string format: uuid example: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b RateLimitLimit: description: Total requests allowed in the current window. schema: type: integer example: 1000 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer example: 955 RateLimitReset: description: Unix timestamp (seconds) when the rate-limit window resets. schema: type: integer format: int64 example: 1713182400 StrictTransportSecurity: description: >- Enforces HTTPS for the configured period. Always `max-age=63072000; includeSubDomains; preload`. schema: type: string example: max-age=63072000; includeSubDomains; preload XContentTypeOptions: description: Disables MIME sniffing. Always `nosniff`. schema: type: string enum: - nosniff example: nosniff ContentSecurityPolicy: description: >- Prevents embedding and resource loading. Always `default-src 'none'; frame-ancestors 'none'`. schema: type: string example: default-src 'none'; frame-ancestors 'none' CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store RetryAfter: description: Seconds the client should wait before retrying. schema: type: integer example: 30 securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ````