> ## 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. # Get User > Retrieve a previously created user by their user ID. Returns the user's core profile — its canonical `id`, the partner-supplied `external_reference`, the user `type`, the current `status` (including any required actions that are blocking or pending), the `created_at` timestamp, and the `accounts` associated with the user. Common use cases: - Poll a user's `status` while it's transitioning (for example, after submitting verifications). - Confirm a user exists and retrieve its account IDs before issuing account-scoped calls. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json get /v1/users/{user_id} 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}: get: tags: - Users summary: Get User description: >- Retrieve a previously created user by their user ID. Returns the user's core profile — its canonical `id`, the partner-supplied `external_reference`, the user `type`, the current `status` (including any required actions that are blocking or pending), the `created_at` timestamp, and the `accounts` associated with the user. Common use cases: - Poll a user's `status` while it's transitioning (for example, after submitting verifications). - Confirm a user exists and retrieve its account IDs before issuing account-scoped calls. operationId: getUser parameters: - in: path name: user_id required: true schema: 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. allOf: - $ref: '#/components/schemas/UserId' x-selected-account: true style: simple example: AA45N8G4MLDYWAR7 responses: '200': description: Response content: application/json: schema: type: object properties: data: description: Retrieved user resource. type: object properties: id: description: User ID, also used as the user's canonical identifier. allOf: - $ref: '#/components/schemas/UserId' external_reference: description: >- Optional partner-supplied reference for this user. Typically an identifier in the partner's own system, but any opaque string the partner wants to associate with the user is accepted. type: - string - 'null' type: description: Indicates the type of the user. type: string enum: - individual - corporate status: description: The overall status of the user. oneOf: - type: object properties: state: type: string enum: - ok required_actions: description: >- Actions that are required and have not been completed, but are not blocking. type: array items: oneOf: - type: object properties: action_type: type: string enum: - verification verification_type: description: Type of verification required. type: string enum: - identity - residence - selfie - sanctions_check - pep_check - negative_news_check - tax_id reasons: description: Reason why verification is required. type: array items: anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: description: >- Deadline for completing the verification, if any. type: - string - 'null' format: date-time required: - action_type - verification_type description: Additional verification is required. - type: object properties: action_type: type: string enum: - provide_details details_type: description: Type of details required. oneOf: - description: Terms of service type: object properties: type: type: string enum: - terms_of_service version: description: >- The version of the terms of service that the user has accepted. type: integer format: uint32 minimum: 0 required: - type - version - description: User's full name type: object properties: type: type: string enum: - full_name required: - type - description: User's date of birth type: object properties: type: type: string enum: - date_of_birth required: - type - description: User's city of birth type: object properties: type: type: string enum: - city_of_birth required: - type - description: User's country of birth type: object properties: type: type: string enum: - country_of_birth required: - type - description: User's nationalities type: object properties: type: type: string enum: - nationalities required: - type - description: User's residential address type: object properties: type: type: string enum: - residence required: - type - description: User's phone number type: object properties: type: type: string enum: - phone required: - type - description: User's occupation type: object properties: type: type: string enum: - occupation required: - type - description: User's tax IDs type: object properties: type: type: string enum: - tax_ids required: - type - description: Name of user's employer type: object properties: type: type: string enum: - employer required: - type - description: Client identifier assigned by partner type: object properties: type: type: string enum: - client_identifier required: - type reason: description: Reason why details are required. anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: description: >- Deadline for providing the details, if any. type: - string - 'null' format: date-time required: - action_type - details_type description: Additional details are required. - type: object properties: action_type: type: string enum: - wait wait_reason_code: description: Reason for the wait. type: string required: - action_type - wait_reason_code description: >- User must wait while Payward performs additional checks. description: >- An action that must be completed (or waited for) before the user can use the service. Some actions are blocking and must be completed before the user can use the service, while others are non-blocking and can be completed at any time. Actions can have deadlines, after which the user may be disabled or closed. required: - required_actions - state description: User is active and able to use the service. - type: object properties: state: type: string enum: - disabled reasons: description: Reason codes for why the user is disabled. type: array items: anyOf: - type: string enum: - tos_not_accepted - tos_rejected - missing_required_verifications - missing_required_details - pending_verifications - suspicious_activity - description: A catch-all for other reasons. type: string required_actions: description: >- Required actions that must be completed before the user can use the service again. type: array items: oneOf: - type: object properties: action_type: type: string enum: - verification verification_type: description: Type of verification required. type: string enum: - identity - residence - selfie - sanctions_check - pep_check - negative_news_check - tax_id reasons: description: Reason why verification is required. type: array items: anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: description: >- Deadline for completing the verification, if any. type: - string - 'null' format: date-time required: - action_type - verification_type description: Additional verification is required. - type: object properties: action_type: type: string enum: - provide_details details_type: description: Type of details required. oneOf: - description: Terms of service type: object properties: type: type: string enum: - terms_of_service version: description: >- The version of the terms of service that the user has accepted. type: integer format: uint32 minimum: 0 required: - type - version - description: User's full name type: object properties: type: type: string enum: - full_name required: - type - description: User's date of birth type: object properties: type: type: string enum: - date_of_birth required: - type - description: User's city of birth type: object properties: type: type: string enum: - city_of_birth required: - type - description: User's country of birth type: object properties: type: type: string enum: - country_of_birth required: - type - description: User's nationalities type: object properties: type: type: string enum: - nationalities required: - type - description: User's residential address type: object properties: type: type: string enum: - residence required: - type - description: User's phone number type: object properties: type: type: string enum: - phone required: - type - description: User's occupation type: object properties: type: type: string enum: - occupation required: - type - description: User's tax IDs type: object properties: type: type: string enum: - tax_ids required: - type - description: Name of user's employer type: object properties: type: type: string enum: - employer required: - type - description: Client identifier assigned by partner type: object properties: type: type: string enum: - client_identifier required: - type reason: description: Reason why details are required. anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: description: >- Deadline for providing the details, if any. type: - string - 'null' format: date-time required: - action_type - details_type description: Additional details are required. - type: object properties: action_type: type: string enum: - wait wait_reason_code: description: Reason for the wait. type: string required: - action_type - wait_reason_code description: >- User must wait while Payward performs additional checks. description: >- An action that must be completed (or waited for) before the user can use the service. Some actions are blocking and must be completed before the user can use the service, while others are non-blocking and can be completed at any time. Actions can have deadlines, after which the user may be disabled or closed. required: - required_actions - state description: User is disabled and cannot use the service. - type: object properties: state: type: string enum: - closed reasons: description: Reason codes for why the user is closed. type: array items: anyOf: - type: string enum: - verification_failed - tos_violation - description: A catch-all for other reasons. type: string required: - state description: User is closed and cannot use the service. created_at: description: >- The datetime when the user was created in ISO 8601 format. type: string format: date-time accounts: description: Accounts associated with the 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: - created_at - id - status - type required: - data examples: active-user: summary: Active user with no pending actions value: data: id: AA45N8G4MLDYWAR7 external_reference: partner-customer-12345 type: individual status: state: ok required_actions: [] created_at: '2025-08-12T14:08:00Z' 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' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/UserNotFoundErrorResponse' 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 GET "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7" \ -H "API-Key: $PWS_API_KEY" \ -H "API-Nonce: $PWS_API_NONCE" \ -H "API-Sign: $PWS_API_SIGN" components: schemas: 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 UserNotFoundErrorResponse: description: The requested user does not exist. 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: - 404 code: type: string enum: - user_not_found 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. ````