> ## 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.

# Create User

> Create a new user in the Payward system.

When retrying user creation, send the same `external_reference` for the same partner user. Payward uses this value to avoid creating duplicate users. Retry responses are generated from the latest available user state, not replayed from the original request.

Returns the created `id` and the `accounts` associated with the user.



## OpenAPI

````yaml /api-reference/openapi_v3_pws.json post /v1/users
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:
    post:
      tags:
        - Users
      summary: Create User
      description: >-
        Create a new user in the Payward system.


        When retrying user creation, send the same `external_reference` for the
        same partner user. Payward uses this value to avoid creating duplicate
        users. Retry responses are generated from the latest available user
        state, not replayed from the original request.


        Returns the created `id` and the `accounts` associated with the user.
      operationId: createUser
      requestBody:
        content:
          application/json:
            schema:
              description: Request to create a new user.
              type: object
              properties:
                email:
                  description: The email associated with the user.
                  type: string
                  maxLength: 254
                  format: email
                external_reference:
                  description: >-
                    Stable partner-supplied reference for this user. Must be
                    unique within your partner account. Reuse the same value
                    only for the same user, including create retries.
                  type: string
                  minLength: 1
                  maxLength: 256
                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's place and date of birth.
                  type: object
                  properties:
                    date:
                      description: User's date of birth
                      type: string
                      format: date
                    city:
                      description: User's city of birth
                      type:
                        - string
                        - 'null'
                      minLength: 1
                      maxLength: 128
                    country:
                      description: User's country of birth
                      allOf:
                        - $ref: '#/components/schemas/CountryCode'
                  required:
                    - date
                residence:
                  description: User's residential address
                  type: object
                  properties:
                    line1:
                      description: Address line 1
                      type: string
                      minLength: 1
                      maxLength: 256
                    line2:
                      description: Address line 2
                      type:
                        - string
                        - 'null'
                      minLength: 1
                      maxLength: 256
                    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'
                  required:
                    - city
                    - country
                    - line1
                    - postal_code
                phone:
                  description: Phone number in E.164 format
                  type: string
                  pattern: ^\+?[1-9]\d{1,14}$
                  minLength: 1
                  maxLength: 16
                nationalities:
                  description: User's nationalities
                  type: array
                  items:
                    $ref: '#/components/schemas/CountryCode'
                occupation:
                  description: User's occupation
                  type: string
                  enum:
                    - agriculture
                    - business_management
                    - computers_and_it
                    - construction
                    - education
                    - finance
                    - government
                    - healthcare
                    - hospitality
                    - manufacturing
                    - marketing
                    - media
                    - other
                    - science
                    - self_employed
                    - student
                    - transportation
                    - unemployed
                    - employed
                employer_name:
                  description: Name of user's employer
                  type:
                    - string
                    - 'null'
                  minLength: 1
                  maxLength: 256
                tax_ids:
                  description: User's tax ID
                  type:
                    - array
                    - 'null'
                  items:
                    description: User tax identifier.
                    type: object
                    properties:
                      id:
                        description: Taxpayer identifier
                        type: string
                        minLength: 1
                        maxLength: 128
                      issuing_country:
                        description: Country issuing the tax ID
                        allOf:
                          - $ref: '#/components/schemas/CountryCode'
                    required:
                      - id
                      - issuing_country
                client_identifier:
                  description: Identifier assigned by the partner platform
                  oneOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - concat
                        value:
                          type: string
                          minLength: 1
                          maxLength: 128
                        calculated_at:
                          type: string
                          format: date-time
                      required:
                        - calculated_at
                        - type
                        - value
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - passport
                        value:
                          type: string
                          minLength: 1
                          maxLength: 128
                      required:
                        - type
                        - value
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - national_id
                        value:
                          type: string
                          minLength: 1
                          maxLength: 128
                      required:
                        - type
                        - value
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - tax_id
                        value:
                          type: string
                          minLength: 1
                          maxLength: 128
                      required:
                        - type
                        - value
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - lei
                        value:
                          type: string
                          minLength: 1
                          maxLength: 128
                      required:
                        - type
                        - value
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - unknown
                      required:
                        - type
                language:
                  description: >-
                    The user's preferred language, as an [ISO 639-1] language
                    code. If not provided, the user's language will be set to
                    the default language for their country.


                    [ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1
                  type:
                    - string
                    - 'null'
                  pattern: ^[a-z]{2}$
              required:
                - email
                - external_reference
                - full_name
                - birth
                - residence
                - phone
                - nationalities
                - occupation
            examples:
              create-individual-user:
                summary: Create an individual user
                value:
                  email: alex.morgan@example.com
                  external_reference: partner-customer-9001
                  full_name:
                    first_name: Alex
                    last_name: Morgan
                  birth:
                    date: '1990-04-15'
                    city: San Francisco
                    country: US
                  residence:
                    line1: 1 Market St
                    city: San Francisco
                    postal_code: '94103'
                    country: US
                  phone: '+14155550110'
                  nationalities:
                    - US
                  occupation: computers_and_it
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Created user payload.
                    type: object
                    properties:
                      id:
                        description: >-
                          User ID of the newly created user, also used as its
                          canonical identifier.
                        allOf:
                          - $ref: '#/components/schemas/UserId'
                      accounts:
                        description: Accounts associated with the created user.
                        type: array
                        items:
                          description: Account associated with a user.
                          type: object
                          properties:
                            id:
                              description: Public account identifier.
                              type: string
                              minLength: 1
                              maxLength: 42
                            name:
                              description: Account display name.
                              type: string
                              minLength: 1
                              maxLength: 256
                          required:
                            - id
                            - name
                    required:
                      - id
                required:
                  - data
              examples:
                created-user:
                  summary: Created user and accounts
                  value:
                    data:
                      id: AA45N8G4MLDYWAR7
                      accounts:
                        - id: WX6VJUKWKKPBQE36
                          name: main
                        - id: WC9RDEFHPSGLXRVX
                          name: secondary
          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 failed
          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: Permission denied
          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: Operation not implemented
          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" \
              -H "API-Key: $PWS_API_KEY" \
              -H "API-Nonce: $PWS_API_NONCE" \
              -H "API-Sign: $PWS_API_SIGN" \
              -H "Content-Type: application/json" \
              -d '{
                "email": "alex.morgan@example.com",
                "external_reference": "partner-customer-9001",
                "full_name": {"first_name": "Alex", "last_name": "Morgan"},
                "birth": {"date": "1990-04-15", "city": "San Francisco", "country": "US"},
                "residence": {"line1": "1 Market St", "city": "San Francisco", "postal_code": "94103", "country": "US"},
                "phone": "+14155550110",
                "nationalities": ["US"],
                "occupation": "computers_and_it"
              }'
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
    UserId:
      type: string
      description: Canonical identifier for a user in the Payward public API.
      minLength: 14
      maxLength: 42
    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.

````