endpoints.md

API endpoints

Every path of the Wealth Reader API, generated from the OpenAPI 3.0.0 specification (version 8.1.7). The machine-readable source is api-for-ai.yaml.

Base URL: https://api.wealthreader.com/

Requests are application/x-www-form-urlencoded. Reads are synchronous and can take minutes when the institution asks for an extra two-factor step, so use a generous client timeout.

POST /batch/fetch/connection-result/

Get individual result of a specific connection within a batch

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves the result of a specific connection from the batch.

Parameter	Type	Required	Description
api_key	string	yes	Identifies the client in the service
batch_id	string	yes	Batch ID
credential_id	string	yes	Filter by specific credential_id

POST /batch/fetch/statistics/

Get general statistics about batch connections

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves general statistics about the processing result of all connections in a batch.

Parameter	Type	Required	Description
api_key	string	yes	Identifies the client in the service
batch_id	string	yes	Batch ID

POST /batch/load/

Batch connection loading

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Important: To use batch process management on Wealthreader's side, a dedicated environment is required. This endpoint is not available on api.wealthreader.com. The endpoints grouped under the "batch" tag allow processing multiple bank connections asynchronously, unlike the /entities/ method which is synchronous. Ideal for: - Processing large volumes of connections, delegating the process to Wealthreader - Avoiding timeouts on slow connections - Getting a webhook notification per completed credential This method starts asynchronous processing of one or multiple bank connections. Immediately returns a batch_id for tracking. A webhook notification is sent to notification_url for each individual credential as soon as it completes, with the following payload fields: batch_id, credential_id, status, timestamp.

Parameter	Type	Required	Description
api_key	string	yes	Identifies the client in the service
notification_url	string	yes	Webhook URL. A notification is sent to this URL for each individual credential as soon as it completes processing, not only once all connections in the batch are done.
connections	array	yes	List of connections to process

POST /cards/enrollments/

Pre-register the email of an employee

Creates an enrollment request in pending status with a short expiry (ttl_minutes, 20 by default, between 1 and 60) for the employee to confirm by opening the mobile app and entering that email (POST /user-sync-validation/, no contract change for the app). It is idempotent: repeating the call for the same (api_key, email) while it is still pending and not expired returns the same request. If the email is already linked to the calling customer, it returns status "active" directly. If it is already linked to a different customer, it returns 409. Rate limit: at most 60 calls to this endpoint per api_key every 60 seconds, counting every attempt and not only the ones that create a row, checked before anything else so the answers that create nothing (200 already active, 409 linked to another customer, 400) cannot be walked as an enumeration oracle. Exceeding it returns 429 with code rate_limited.

Parameter	Type	Required	Description
api_key	string	yes	API key of the customer.
email	string	yes	Email of the employee to pre-register.
ttl_minutes	integer	no	Minutes the request stays valid before expiring.

GET /cards/enrollments/

Check the status of an enrollment

Read-only status of an enrollment request. It has no side effects on card users, unlike POST /user-sync-validation/, which does confirm. The only write allowed is lazily marking a pending enrollment whose expiry date has already passed as expired.

Parameter	Type	Required	Description
api_key	string	yes	API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.
enrollment_id	string	yes	Identifier returned by POST /cards/enrollments/.

GET /cards/transactions/

Query / backfill real-time card transactions

Returns the real-time card transactions received for the employees linked to this api_key, ordered by ascending id. Meant both for periodic backfill (poll with date_from/date_to and paginate with since_id) and for one-off queries. This is the same transaction object carried by the card_transaction.created webhook.

Parameter	Type	Required	Description
api_key	string	yes	API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.
date_from	string	no	YYYY-MM-DD, on the operation date. Default: today minus 3 days.
date_to	string	no	YYYY-MM-DD, on the operation date. Default: today.
email	string	no	Filters by the email of the employee.
since_id	integer	no	Exclusive cursor on the transaction id, for pagination.
limit	integer	no	Maximum number of transactions to return (500 by default, 1000 max).

POST /cards/webhook/

Register or rotate the real-time cards webhook

Creates or updates the webhook URL of the customer for the card_transaction.created and card_enrollment.confirmed events (see the cards-webhook-delivery schema for the delivery format and signature). On first setup, or when rotate_secret is true, a new webhook_secret (64 hex characters) is generated and returned once; in any other case webhook_secret comes back as null in the response and cannot be retrieved again. webhook_url must always be https:// and must resolve to a publicly routable host: localhost, private, loopback, link-local (including the cloud metadata address), CGNAT, multicast and reserved addresses are rejected, in any notation (hexadecimal, decimal, octal, short dotted or IPv4-mapped IPv6), and so is a hostname that does not resolve at all. The same check runs again right before every delivery, not only at registration: if the host is repointed at an internal address afterwards (DNS rebinding) the delivery is closed as failed with response_excerpt "blocked_host". Sending null in webhook_url disables webhooks for that customer; omitting the field leaves the stored URL untouched, which is how the secret is rotated without changing the URL.

Parameter	Type	Required	Description
api_key	string	yes	API key of the customer.
webhook_url	string	no	https:// URL that will receive the events, on a publicly routable host that resolves in DNS. null disables webhooks; omitting the field leaves the stored URL unchanged.
rotate_secret	boolean	no	When true, generates and returns a new webhook_secret.

POST /domains/

Add a new domain

Adds the association between the domain that will host the widget and the destination webhook. To edit or test your domains, use https://www.wealthreader.com/clients/

Parameter	Type	Required	Description
method	string	yes	Method to execute.
api_key	string	yes	User's API key.
domain	string	yes	Domain to add.
url_callback	string	yes	URL for callback.
tokenize	string	yes	Controls whether the widget initiates a tokenization flow: * 1 - The user authenticates with the financial institution (login, consent, 2FA if required) and a reusable token is returned for future queries * 0 - No tokenization is performed. The previously obtained token value must be included in the request

POST /entities/

Retrieves financial assets and their composition details

Retrieves financial assets and details of their composition including investment portfolios (stocks, funds, bonds, pension plans, alternative investments, crypto), credit cards, insurance, and loans. Includes ownership information for each asset as well as unique identifiers that facilitate data processing. It is possible to obtain Mock data. Check with the technical team on how to do this.

Parameter	Type	Required	Description
api_key	string	no	Identifies the client in the service
code	string	no	Name of the entity. The complete list is available with GET
token	string	no	Identifies the custodied credential. The flow by which the token has been obtained is described in the 'Widget Integration Guide' document. The following Mock users are available: MOCKDATA, OK response; MOCKOTP, response with OTP challenge; MOCKLOGINKO, response with login error
product_types	string	no	List of product types from which information is to be retrieved. Accepts multiple values separated by commas.
only_balances	boolean	no	Indicates whether to obtain only the balances of the products instead of all available information. Default value: false.
fetch_transaction_details	boolean	no	Indicates whether extended transaction details should be retrieved when the entity connector supports it. IMPORTANT: Enabling it implies performing one or more additional navigations per transaction to enrich the returned information. This will inevitably and significantly increase the execution time. The number of additional navigations grows with the volume of transactions. It is recommended to enable it only when you are certain that a level of detail beyond the one returned by default is required. The retrieved details are inserted into the additional_info key at the level of each transaction. The use of this parameter requires a dedicated environment.
date_from	string	no	Date from which transactions are requested, in YYYY-MM-DD format. Must be a date before today.
date_to	string	no	This only applies to restricting by future dates for products loan and confirming, in YYYY-MM-DD format. The date must be later than today
required_products_schema	string	no	Required products schema. Indicates the accounts or cards from which data is desired, with additional configurations.
add_pdf_from_uuids	string	no	Accepts transaction uuids separated by commas. Parameter that is only taken into account if product_types is ALL or includes accounts. Adds the PDF document associated with each of the requested bank transactions.
otp_method	string	no	Selects which second-factor delivery channel to use when the API returned error code 2017 or 20171 (multiple OTP methods available). Call again with the same session identifier from that response and set this form field to the exact value of the otp_method property from one object in statistics.otpMethods (not the array index). Omit on the first credential-based request; send after the end user chooses a method. The example value below is illustrative only—always copy the string returned in statistics.otpMethods for your entity (wording may be OTP_SMS ****1234, SMS *****1234, or another label depending on the bank).

GET /entities/

Retrieves the list of supported entities

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves the list of supported entities and the information needed to draw the entity's login form.

Parameter	Type	Required	Description
show_only_tested	integer	no	Indicates whether to show only tested entities. Default value is 0. In production environments, always use 1.

GET /entities/category-types/

List of transaction types

Parameter	Type	Required	Description
lang	string	no	Response language

GET /error-codes/

List of error codes

List of error codes. Pay special attention to the fact that not all error codes should receive the same treatment from your application. For an incorrect password error, you should not retry the call with the same parameters, but for an error indicating that the entity is under maintenance, you can retry. Request a technical session with our team to resolve any questions about error management.

Parameter	Type	Required	Description
lang	string	no	Response language

POST /tokens/

Query tokens associated with an api_key

Use this method to query all tokens linked to a specific api_key. Results are returned in blocks of 500 tokens per page.

Parameter	Type	Required	Description
api_key	string	no	api_key to identify the client in the service
page	number	no	Specify the page number you want to retrieve. Each page contains up to 500 tokens. If not provided, the default value is 1.

POST /tokens/reasign/

Reassign a token to a different api_key

This method allows reassigning a token from one api_key to another.

Parameter	Type	Required	Description
api_key_source	string	no	api_key from which to reassign the token.
api_key_target	string	no	api_key to which to reassign the token.
token	string	no	Token to be reassigned.

POST /tokens/revoke/

Revoke a token

This method allows revoking an existing token to disauthorize future API access requests.

Parameter	Type	Required	Description
api_key	string	no	Identifies the client in the service
token	string	no	Token to be revoked.

POST /user/check/

Check user registration status

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Checks if a user is registered in the Easytransfer or Acumulas system and returns the unique access link for the user.

POST /user/register/

Register a new user

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. This endpoint allows registering a user either on the portfolio transfer platform, Easytransfer, or on the reporting tool, Acumulas, based on a unique identifier.

POST /user/revoke/

Revoke a previously registered user

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. This endpoint allows unregistering a user from the Easytransfer or Acumulas platform service.

POST /verify/iban-ownership/

Verify bank account ownership via IBAN

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Allows verifying whether a natural or legal person is the holder of a specific bank account using the IBAN and the identification data of the alleged holder. It requires an api_key with the IBAN_OWNERSHIP product authorized. The initial request is sent with api_key, iban, document_type, document_number and holder_name. If the result returns status PENDING, the verification can be queried again by sending only api_key and session. NO_RESPONSE is a final error result: to retry, a new verification must be started without session.

GET /warning-codes/

List of warning codes

List of warning codes.

Parameter	Type	Required	Description
lang	string	no	Response language