Issuing a USD Account

This flow applies to new live personal USD requests for enabled organisations. Existing accounts, historical pending requests, business accounts, and other currencies keep their existing routes.

1. Prepare

Use an API key for the person's organisation and environment, and configure your receiver for Inquiry Events and Issuance Events.

Create or reuse a person who meets the USD requirements: basic KYC, primary ID, contact/address details, background information, identity evidence, and proof of address. Further verification may still be required.

2. Request the account

curl --request POST \
  --url 'https://api.useoval.com/bank_account' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "person_id": "PERSON_ID",
    "label": "Personal USD account",
    "currency": "USD",
    "autosweep_enabled": false
  }'

Replace the placeholders. This example disables autosweep; enabling it requires a USD settlement wallet. See Create Bank Account.

201 means processing has started. Save data.id and show a pending state; bank details may be null. If the result is uncertain, list accounts before retrying. An existing active or pending USD account can prevent another request.

3. Handle RFIs

curl --request GET \
  --url 'https://api.useoval.com/inquiry_request?account_id=ACCOUNT_ID&page=1&per_page=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'accept: application/json'

Use the saved account ID and follow pagination. Results may include person-owned inquiries with account_id: null; identify each by its own id.

Type	Action
`standard`	Show `query` and submit one response. It remains pending for review.
`link`	Open the returned link; completion is confirmed asynchronously.
Expired/unavailable hosted link	Refresh, then check status and link.

After an uncertain response submission, check response history; repeat submissions return 409.

Listen for inquiry_request.created, inquiry_request.updated, and inquiry_request.answered. More RFIs may follow; an empty list or completed inquiry does not mean the account is active. See RFI handling.

4. Confirm the outcome

State/event	Action
`pending`	Show processing or the outstanding RFI.
`account.created` / `active`	Fetch the account and display its returned bank details and supported rails.
`account.issuance.failed` / `failed`	Show the failure; do not automatically create a replacement.

Only show funding instructions for an active account. Use its returned beneficiary and routing details. A timeout is not a rejection; contact support with the account ID if progress is unresolved.

Deduplicate inquiry events by data.event_id and reconcile delayed or missed events through fetch/list endpoints. Refresh state when the user returns.

Before going live, complete Testing Account Issuance.