===============
LIBRARY RULES
===============
From library maintainers:
- Distingue flujos: iframe/widget vs OAuth. No inventes pasos; usa la guía correcta.
- No reintentes errores de credenciales. Reintenta solo casos temporales (p.ej. mantenimiento).
- Si el rango de fechas es grande, anticipa 2FA/OTP y mayor latencia; ajusta expectativas.
### GET /entities/ example with curl and jq
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Fetches the entity catalog with show_only_tested=1 and extracts code, name, and color fields using jq. Uses --fail and --show-error to surface HTTP errors.
```bash
curl --fail --show-error "https://api.wealthreader.com/entities/?show_only_tested=1" \
| jq '.[] | {code, name, color}'
```
--------------------------------
### Example 2 — full response with filters and token recovery
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/wr-conf-widget.md
Full response example with wait_full_response=true, date_from, product_types filter, and token recovery. Redirects to a success page on flow completion. Includes the iframe and loader script.
```html
```
--------------------------------
### Example 2 — register an OAuth domain with error checking (curl)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/domains.md
Registers an OAuth domain using curl and checks the response with jq. The example omits url_callback and tokenize. Exits with code 1 if registration fails.
```bash
RESP=$(curl --silent --show-error --location "https://api.wealthreader.com/domains/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode 'method=add' \
--data-urlencode 'api_key=12345678' \
--data-urlencode 'domain=https://www.example.com/oauth/success.php' \
--data-urlencode 'access_type=oauth')
echo "$RESP" | jq -e '.success == true' \
|| { echo "domain registration failed: $RESP" >&2; exit 1; }
```
--------------------------------
### curl example for /warning-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md
Fetches warning codes in Spanish and outputs code and description for each entry.
```bash
curl --fail --show-error "https://api.wealthreader.com/warning-codes/?lang=es" \
| jq '.[] | {code, description}'
```
--------------------------------
### curl example for POST /user/revoke/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Example curl command to unregister a user from all services. Uses --fail and --show-error to surface HTTP errors. The commented line shows the expected response.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/user/revoke/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=A1B2C3D4" \
--data-urlencode "user_id=12345678A" \
--data-urlencode "service=all"
# {"success": true, "message": "User unregistered successfully"}
```
--------------------------------
### Example 1 — basic registration (curl)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Curl command to register a user with easy-transfer service. Uses --fail and --show-error to surface HTTP errors.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/user/register/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=A1B2C3D4" \
--data-urlencode "user_id=12345678A" \
--data-urlencode "email=sai_banker@singularbank.com" \
--data-urlencode "service=easy-transfer"
```
--------------------------------
### Example response for /error-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md
Verbatim sample response from the spec, showing the structure of a warning-error-codes element.
```json
[{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}]
```
--------------------------------
### 200 OK response example
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md
Example successful response with result code 1 and message 'The IBAN belongs to the indicated holder'. The statistics object contains session and execution time metadata.
```json
{
"success": true,
"result": {
"code": 1,
"message": "The IBAN belongs to the indicated holder"
},
"statistics": { "SESSION": null, "execution_time": 0.958 }
}
```
--------------------------------
### Example 2 — verification with error handling (Python)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md
Python example using requests to verify IBAN ownership. Handles non-200 responses by printing the session ID and raising an error. Checks result code and exits if the IBAN does not belong to the holder.
```python
import requests
r = requests.post("https://api.wealthreader.com/verify/iban-ownership/", data={
"api_key": "12345678",
"iban": "ES4914651234561234567890",
"document_type": "CIF",
"document_number": "B12345678",
"holder_name": "ACME SL",
})
if r.status_code != 200:
body = r.json()
print("SESSION (save for support):", body["statistics"]["SESSION"])
raise SystemExit(f"verification request failed: {body['error']['code']} {body['error']['message']}")
result = r.json()["result"]
print(result["code"], result["message"])
if result["code"] != 1:
# holder mismatch — drive onboarding accordingly
raise SystemExit("IBAN does not belong to the indicated holder")
```
--------------------------------
### POST /tokens/reasign/ — curl example
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md
Example curl command to reassign a token. Uses --fail and --show-error to surface HTTP errors. The response is shown in the comment.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/tokens/reasign/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key_source=12345678" \
--data-urlencode "api_key_target=87654321" \
--data-urlencode "token=FRJ0mHlaqZwLzu"
# {"success": true, "message": "Token successfully reassigned."}
```
--------------------------------
### Example 1 — basic embed
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/wr-conf-widget.md
Basic embed of the Wealth Reader widget with a minimal wr_conf (wait_full_response=false) and a message listener that logs when the flow completes. Includes the iframe and loader script.
```html
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Retrieves the catalog of supported entities. Use this to obtain entity codes for use in other endpoints.
```APIDOC
## [GET] /entities/
### Description
Retrieves the catalog of supported entities. Use this to obtain entity codes for use in other endpoints.
### Method
GET
### Endpoint
https://api.wealthreader.com/entities/
### Parameters
#### Query Parameters
- **show_only_tested** (integer, enum 0/1) - Optional - Default: 0 - Whether to show only tested entities. In production, always use 1.
### Response
#### Success Response (200)
- **code** (string) - Entity code
- **name** (string) - Entity name
- **logo** (string) - Logo URL
- **color** (string) - Color code
- **inputs** (object) - Required input fields: document_type, user, password (each with required and name)
- **statistics** (object) - Statistics data
#### Response Example
```json
[
{
"code": "caixabank",
"name": "CaixaBank",
"logo": "https://...",
"color": "#...",
"inputs": {
"document_type": {"required": true, "name": "Document type"},
"user": {"required": true, "name": "User"},
"password": {"required": true, "name": "Password"}
},
"statistics": {}
}
]
```
### Error Handling
- **400**: Error - Response body contains an `error` object
```
--------------------------------
### Example 2 — registration with error handling (Python)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Python script using requests to register a user. Checks for 401 status (invalid API key) and non-success response, raising SystemExit with the server message.
```python
import requests
r = requests.post("https://api.wealthreader.com/user/register/", data={
"api_key": "A1B2C3D4",
"user_id": "12345678A",
"email": "sai_banker@singularbank.com",
"service": "easy-transfer",
})
if r.status_code == 401:
raise SystemExit("invalid api_key — check credentials, do not retry")
body = r.json()
if not body.get("success"):
raise SystemExit(f"registration failed: {body.get('message')}")
```
--------------------------------
### curl example for /error-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md
Fetches error codes in English and filters for codes between 2000 and 2999, outputting code, description, and how_to_proceed.
```bash
curl --fail --show-error "https://api.wealthreader.com/error-codes/?lang=en" \
| jq '.[] | select(.code >= 2000 and .code < 3000) | {code, description, how_to_proceed}'
```
--------------------------------
### POST /batch/fetch/connection-result/ - Example curl
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md
Calls the connection-result endpoint and pipes the response through jq to extract account balances.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/batch/fetch/connection-result/" \
--header "Content-Type: application/json" \
--data '{"api_key": "12345678", "batch_id": "batch_20250120_a1b2c3d4", "credential_id": "cred_001"}' \
| jq '.payload.accounts[0].balances'
```
--------------------------------
### GET /entities/ signature
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Shows the HTTP GET request format for the entity catalog endpoint. The show_only_tested parameter is optional and defaults to 0; in production, always use 1.
```http
GET https://api.wealthreader.com/entities/?show_only_tested=
```
--------------------------------
### Example 1 — register a widget domain (curl)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/domains.md
Registers a widget domain using curl. The domain must not be an IP address and must not include 'localhost'. Uses access_type=widget and tokenize=1.
```bash
API_KEY='12345678'
DOMAIN='http://desarrollo.cliente.es' # no IP, no "localhost"
URL_CALLBACK='https://desarrollo.cliente.es/hooks/wealthreader'
ACCESS_TYPE='widget'
curl --location "https://api.wealthreader.com/domains/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "method=add" \
--data-urlencode "tokenize=1" \
--data-urlencode "api_key=${API_KEY}" \
--data-urlencode "domain=${DOMAIN}" \
--data-urlencode "url_callback=${URL_CALLBACK}" \
--data-urlencode "access_type=${ACCESS_TYPE}"
```
--------------------------------
### Example 1 — paginated listing (basic) using curl and jq
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md
Curl command to list tokens for a given api_key, paginated, and pipe to jq to extract token, entity_code, and latest_code fields.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/tokens/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=12345678" \
--data-urlencode "page=1" \
| jq '.[] | {token, entity_code, latest_code}'
```
--------------------------------
### cURL Example for /user/check/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Uses curl to call the endpoint and extract the easy-transfer link with jq. Requires api_key and user_id. Fails on HTTP errors due to --fail.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/user/check/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=A1B2C3D4" \
--data-urlencode "user_id=12345678A" \
| jq -r '.links["easy-transfer"]'
```
--------------------------------
### GET /warning-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Retrieves warning codes. The `lang` query parameter specifies the language of the warning messages, with a default of `es`.
```APIDOC
## [GET] /warning-codes/
### Description
Retrieves warning codes. The `lang` query parameter specifies the language of the warning messages, with a default of `es`.
### Method
GET
### Endpoint
/warning-codes/
### Parameters
#### Query Parameters
- **lang** (string) - Optional - Default: `"es"`. Language for warning messages. Enum: `es`, `en`.
### Request Example
```
GET /warning-codes/?lang=es
```
### Response
#### Success Response (200)
- **warning_codes** (array) - List of warning codes.
#### Response Example
```json
{
"warning_codes": []
}
```
```
--------------------------------
### GET /warning-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves a list of warning codes. No authentication required.
```APIDOC
## GET /warning-codes/
### Description
Retrieves a list of warning codes. No authentication required.
### Method
GET
### Endpoint
/warning-codes/
### Parameters
None
### Response
#### Success Response (200)
- Success response body.
#### Error Statuses
- 400 - Bad request
```
--------------------------------
### Callback GET with nonce and code
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md
The auth server redirects to the callback with a GET request containing nonce and code parameters after user authorization. The nonce must match the generated value and the code is used for token exchange.
```http
https://example.com/oauth/success.php
?nonce=7065556651485978744d7669633373686c44427532556d71506170425178724d584738693548365444
&code=1234567890abcdef1234567890abcdef1234567890a
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Retrieves a list of entities. The `show_only_tested` query parameter controls whether only tested entities are returned; in production it is always set to `1`.
```APIDOC
## [GET] /entities/
### Description
Retrieves a list of entities. The `show_only_tested` query parameter controls whether only tested entities are returned; in production it is always set to `1`.
### Method
GET
### Endpoint
/entities/
### Parameters
#### Query Parameters
- **show_only_tested** (integer) - Optional - Default: `0`. Set to `1` to return only tested entities. In production, this is always `1`.
### Request Example
```
GET /entities/?show_only_tested=0
```
### Response
#### Success Response (200)
- **entities** (array) - List of entities.
#### Response Example
```json
{
"entities": []
}
```
```
--------------------------------
### Basic refresh with curl
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Basic refresh example for the POST /entities/ endpoint using curl. Uses mock token MOCKDATA to return anonymized sample data. Includes api_key, code, token, product_types, date_from, and only_balances parameters.
```bash
API_KEY='12345678'
CODE='caixabank'
TOKEN='MOCKDATA' # mock user: returns anonymized sample data
curl --fail --show-error --location "https://api.wealthreader.com/entities/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=${API_KEY}" \
--data-urlencode "code=${CODE}" \
--data-urlencode "token=${TOKEN}" \
--data-urlencode "product_types=accounts,portfolios" \
--data-urlencode "date_from=2024-01-01" \
--data-urlencode "only_balances=false"
```
--------------------------------
### Full backend exchange with verification in Python
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md
Complete Python example for the OAuth flow: generates nonce, state, and code_verifier, then exchanges the code for an access token. Uses requests library and SHA-256 for the challenge.
```python
import hashlib, secrets, requests
# 1. Generate challenge values
nonce = secrets.token_hex(41) # hex
state = secrets.token_hex(41)
code_verifier = secrets.token_hex(41) # hex -> SHA-256 for challenge
challenge_code = hashlib.sha256(code_verifier.encode()).hexdigest()
# 2. Redirect the user to https://oauth.wealthreader.com/oauth2/?... (as above)
# ... user authorizes; callback GET arrives with ?nonce=...&code=...
# 3. Exchange the code
resp = requests.post("https://oauth.wealthreader.com/token/", data={
"grant_type": "authorization_code",
"redirect_uri": "https://example.com/oauth/success.php",
"code": "1234567890abcdef1234567890abcdef1234567890a",
"code_verifier": code_verifier,
})
resp.raise_for_status()
# response contains the bank's data + access token; persist the token
```
--------------------------------
### Example 1 — basic verification (curl)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md
Basic curl command to verify IBAN ownership. Uses --fail and --show-error to surface HTTP errors.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/verify/iban-ownership/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=12345678" \
--data-urlencode "iban=ES4914651234561234567890" \
--data-urlencode "document_type=NIF" \
--data-urlencode "document_number=12345678Z" \
--data-urlencode "holder_name=LUIS GARCIA BAQUERO"
```
--------------------------------
### POST /batch/fetch/statistics/ - Example curl
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md
Calls the statistics endpoint and pipes the response through jq to extract status and connection counts.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/batch/fetch/statistics/" \
--header "Content-Type: application/json" \
--data '{"api_key": "12345678", "batch_id": "batch_20250120_a1b2c3d4"}' \
| jq '{status, ok: .statistics.successful_connections, failed: .statistics.failed_connections}'
```
--------------------------------
### POST /batch/load/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Starts asynchronous multi-connection processing. Returns a 202 with batch ID and estimated completion time, and notifies the provided URL on completion.
```APIDOC
## POST /batch/load/
### Description
Initiates asynchronous multi-connection processing.
### Method
POST
### Endpoint
/batch/load/
### Parameters
#### Request Body
- **connections** (array) - Required - List of connections to process.
- **notification_url** (string) - Optional - URL to notify on completion.
### Response
#### Success Response (202)
Returns an object with `batch_id`, `total_connections`, and `estimated_completion_time`.
```
--------------------------------
### GET /warning-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md
Retrieves the catalog of warning codes. Use this endpoint to interpret the `statistics.warnings[].code` field returned by other API calls.
```APIDOC
## [GET] /warning-codes/
### Description
Retrieves the catalog of warning codes. Use this endpoint to interpret the `statistics.warnings[].code` field returned by other API calls.
### Method
GET
### Endpoint
https://api.wealthreader.com/warning-codes/
### Parameters
#### Query Parameters
- **lang** (string, enum `es`, `en`) - Optional - Response language. Default: `"es"`.
### Request Example
```
GET https://api.wealthreader.com/warning-codes/?lang=es
```
### Response
#### Success Response (200)
- **code** (integer) - Warning code
- **description** (string) - Warning description
- **possible_reasons** (string) - Possible causes of the warning
- **how_to_proceed** (string) - How to act when this warning code is obtained
#### Response Example
```json
[{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}]
```
### Error Handling
| Status | Condition | Body |
|---|---|---|
| 400 | Error | array of `error` |
```
--------------------------------
### GET /error-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Retrieves error codes. The `lang` query parameter specifies the language of the error messages, with a default of `es`.
```APIDOC
## [GET] /error-codes/
### Description
Retrieves error codes. The `lang` query parameter specifies the language of the error messages, with a default of `es`.
### Method
GET
### Endpoint
/error-codes/
### Parameters
#### Query Parameters
- **lang** (string) - Optional - Default: `"es"`. Language for error messages. Enum: `es`, `en`.
### Request Example
```
GET /error-codes/?lang=es
```
### Response
#### Success Response (200)
- **error_codes** (array) - List of error codes.
#### Response Example
```json
{
"error_codes": []
}
```
```
--------------------------------
### GET /error-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md
Retrieves the catalog of error codes. Use this endpoint to interpret the `error-detail.code` field returned by other API calls.
```APIDOC
## [GET] /error-codes/
### Description
Retrieves the catalog of error codes. Use this endpoint to interpret the `error-detail.code` field returned by other API calls.
### Method
GET
### Endpoint
https://api.wealthreader.com/error-codes/
### Parameters
#### Query Parameters
- **lang** (string, enum `es`, `en`) - Optional - Response language. Default: `"es"`.
### Request Example
```
GET https://api.wealthreader.com/error-codes/?lang=en
```
### Response
#### Success Response (200)
- **code** (integer) - Error code
- **description** (string) - Error description
- **possible_reasons** (string) - Possible causes of the error
- **how_to_proceed** (string) - How to act when this error code is obtained
#### Response Example
```json
[{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}]
```
### Error Handling
| Status | Condition | Body |
|---|---|---|
| 400 | Error | array of `error` |
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves the catalog of supported entities with fields needed to render the login form. Use the `show_only_tested` query parameter to filter to tested entities in production.
```APIDOC
## GET /entities/
### Description
Returns the supported-entity catalog with fields needed to render the login form.
### Method
GET
### Endpoint
/entities/
### Parameters
#### Query Parameters
- **show_only_tested** (integer) - Optional - Set to 1 to show only tested entities (default 0; production should use 1).
### Response
#### Success Response (200)
Returns an array of `entities` objects.
```
--------------------------------
### Token exchange with curl
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md
Example curl command for the token exchange. Sends a POST request with form-urlencoded data including grant_type, redirect_uri, code, and code_verifier.
```bash
curl --location --request POST 'https://oauth.wealthreader.com/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://example.com/oauth/success.php' \
--data-urlencode 'code=1234567890abcdef1234567890abcdef1234567890a' \
--data-urlencode 'code_verifier=6e37325953774b514b4f6a553374484d67423656524a4e31584c64327030384b4b4a7452666f506d6b'
```
--------------------------------
### Check User Response JSON
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Example JSON response for a successful check. Contains success flag, registration status, user ID, and single-use access links per aggregation service.
```json
{
"success": true,
"registered": true,
"user_id": "12345",
"links": {
"easy-transfer": "https://singularbank.wealthreader.com/...",
"integra": "https://www.acumulas.com/register?..."
}
}
```
--------------------------------
### GET /entities/category-types/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Retrieves entity category types. The `lang` query parameter specifies the language of the category type names, with a default of `es`.
```APIDOC
## [GET] /entities/category-types/
### Description
Retrieves entity category types. The `lang` query parameter specifies the language of the category type names, with a default of `es`.
### Method
GET
### Endpoint
/entities/category-types/
### Parameters
#### Query Parameters
- **lang** (string) - Optional - Default: `"es"`. Language for category type names. Enum: `es`, `en`.
### Request Example
```
GET /entities/category-types/?lang=es
```
### Response
#### Success Response (200)
- **category_types** (array) - List of category types.
#### Response Example
```json
{
"category_types": []
}
```
```
--------------------------------
### Submit a mixed token/credential batch (curl)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md
Example curl command to submit a batch with two connections: one using a token, the other using user/password. The response is a 202 with batch_id, total_connections, and estimated_completion_time.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/batch/load/" \
--header "Content-Type: application/json" \
--data '{
"api_key": "12345678",
"notification_url": "https://example.com/webhook/batch-complete",
"connections": [
{"credential_id": "cred_001", "code": "santander", "token": "FRJ0mHlaqZwLzu", "only_balances": true},
{"credential_id": "cred_002", "code": "caixabank", "user": "user1", "password": "pass1", "product_types": "accounts,loans"}
]
}'
# 202 {"success": true, "batch_id": "batch_20250120_a1b2c3d4", "total_connections": 2, "estimated_completion_time": "2025-01-20T10:45:00Z"}
```
--------------------------------
### GET https://oauth.wealthreader.com/oauth2/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Redirect endpoint for initiating OAuth authorization. Users are redirected to this URL with the specified query parameters to start the OAuth flow.
```APIDOC
## [GET] https://oauth.wealthreader.com/oauth2/
### Description
Redirect endpoint for initiating OAuth authorization. Users are redirected to this URL with the specified query parameters to start the OAuth flow.
### Method
GET
### Endpoint
https://oauth.wealthreader.com/oauth2/
### Parameters
#### Query Parameters
- **challenge_code** (string) - Required - The PKCE challenge code.
- **code_challenge_method** (string) - Required - The PKCE challenge method (e.g., S256).
- **redirect_uri** (string) - Required - The URI to redirect to after authorization.
- **response_type** (string) - Required - The response type (e.g., code).
- **state** (string) - Required - A state parameter for CSRF protection.
- **nonce** (string) - Required - A nonce parameter.
- **wr_conf** (string) - Required - WealthReader configuration identifier.
### Response
#### Success Response (302)
Redirects to the specified redirect_uri with authorization code and state.
#### Response Example
(Redirect response)
```
--------------------------------
### warning-error-codes
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/types.md
Defines the structure of each element in the responses of `GET /error-codes/` and `GET /warning-codes/`. It contains four required fields: code, description, possible_reasons, and how_to_proceed.
```APIDOC
## warning-error-codes
### Description
Element of GET `/error-codes/` and `/warning-codes/`.
### Fields
- **code** (integer) - Required - Error or warning code
- **description** (string) - Required - Description of the code
- **possible_reasons** (string) - Required - Possible reasons for the code
- **how_to_proceed** (string) - Required - How to proceed
### Example
```json
{"type": "array", "items": {"type": "object", "required": ["code","description","possible_reasons","how_to_proceed"], "properties": {
"code": {"type": "integer"}, "description": {"type": "string"},
"possible_reasons": {"type": "string"}, "how_to_proceed": {"type": "string"}}}}
```
```
--------------------------------
### POST /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Creates a new entity session by providing credentials and optional product schema. Returns account and card data, including PDFs if requested.
```APIDOC
## [POST] /entities/
### Description
Creates a new entity session by providing credentials and optional product schema. Returns account and card data, including PDFs if requested.
### Method
POST
### Endpoint
https://api.wealthreader.com/entities/
### Parameters
#### Request Body
- **api_key** (string) - Required - API key for authentication
- **code** (string) - Required - Entity code (e.g., "caixabank")
- **token** (string) - Required - Session token
- **required_products_schema** (string) - Optional - JSON string specifying per-product options (only_balances, add_pdf_from_uuids, date_from)
- **add_pdf_from_uuids** (string) - Optional - UUID(s) of documents to include as PDFs
### Request Example
```json
{
"api_key": "12345678",
"code": "caixabank",
"token": "FRJ0mHlaqZwLzu",
"required_products_schema": "{\"ACCOUNTS\":{\"0ae4d722b1c82feeafb4b36b2893230444071335\":{\"only_balances\":false,\"add_pdf_from_uuids\":[\"90763109952d4f2ebece8dceca8254078c5384a0\"],\"date_from\":\"2024-04-03\"}},\"CARDS\":{\"957e6f63546f3fecacce80192b6f7436496dc057\":{}}}",
"add_pdf_from_uuids": "90763109952d4f2ebece8dceca8254078c5384a0"
}
```
### Response
#### Success Response (200)
- **payload** (object) - Contains accounts and cards data
- **accounts** (array) - List of accounts with transactions
- **transactions** (array) - List of transactions, each with optional pdf_file (Base64)
#### Response Example
```json
{
"payload": {
"accounts": [
{
"transactions": [
{
"pdf_file": ""
}
]
}
]
}
}
```
### Error Handling
- **Non-200 status**: Response is an array with an error envelope
- **error.code** (integer) - Error code; 2000-2999 indicates login errors (do not retry), others are temporary (retry with backoff)
- **error.message** (string) - Error description
- **statistics.SESSION** (string) - Session identifier for support
```
--------------------------------
### POST /tokens/revoke/ — curl example
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md
Example curl command to revoke a token. Uses --fail and --show-error to surface HTTP errors. The response is shown in the comment.
```bash
curl --fail --show-error --location "https://api.wealthreader.com/tokens/revoke/" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "api_key=12345678" \
--data-urlencode "token=FRJ0mHlaqZwLzu"
# {"success": true, "message": "Token successfully revoked."}
```
--------------------------------
### POST /user/register/ signature (register-user-request)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Exact request body for registering a user. Requires api_key (8 alphanumeric characters), user_id, email, and service (integra or easy-transfer). Content-Type must be application/x-www-form-urlencoded.
```http
POST https://api.wealthreader.com/user/register/
Content-Type: application/x-www-form-urlencoded
api_key= # Authentication key, 8 alphanumeric characters (example: A1B2C3D4)
user_id= # User identification document (example: 12345678A)
email= # User email, used according to service type (format: email)
service= # Service associated with the user: integra | easy-transfer
```
--------------------------------
### GET your callback — authorization response
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md
After the user authorizes, the auth server redirects the client to your callback with a GET containing nonce and code. This callback is used to receive the authorization code for the token exchange.
```APIDOC
## [GET] your callback
### Description
After the user authorizes, the auth server redirects the client to your callback with a GET containing `nonce` and `code`.
### Method
GET
### Endpoint
`https://example.com/oauth/success.php`
### Parameters
#### Query Parameters
- **nonce** (string hex) - Required - Must match the `nonce` you generated (verify it)
- **code** (string) - Required - Authorization code for the token exchange
### Request Example
```
https://example.com/oauth/success.php
?nonce=7065556651485978744d7669633373686c44427532556d71506170425178724d584738693548365444
&code=1234567890abcdef1234567890abcdef1234567890a
```
```
--------------------------------
### POST /tokens/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Creates a token. The `page` parameter in the request body specifies the page number for pagination, with a default of `1`.
```APIDOC
## [POST] /tokens/
### Description
Creates a token. The `page` parameter in the request body specifies the page number for pagination, with a default of `1`.
### Method
POST
### Endpoint
/tokens/
### Parameters
#### Request Body
- **page** (integer) - Optional - Default: `1`. Page number for pagination.
### Request Example
```json
{
"page": 1
}
```
### Response
#### Success Response (200)
- **token** (string) - The generated token.
#### Response Example
```json
{
"token": "string"
}
```
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves a list of entities. No authentication required.
```APIDOC
## GET /entities/
### Description
Retrieves a list of entities. No authentication required.
### Method
GET
### Endpoint
/entities/
### Parameters
None
### Response
#### Success Response (200)
- Success response body.
#### Error Statuses
- 400 - Bad request
```
--------------------------------
### POST /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Creates a new entity. The request body can include the `only_balances` parameter to control whether only balance information is returned. The `product_types` parameter is omitted, so the entity default of `ALL` is used.
```APIDOC
## [POST] /entities/
### Description
Creates a new entity. The request body can include the `only_balances` parameter to control whether only balance information is returned. The `product_types` parameter is omitted, so the entity default of `ALL` is used.
### Method
POST
### Endpoint
/entities/
### Parameters
#### Request Body
- **only_balances** (boolean) - Optional - Default: `false`. If `true`, only balance information is returned.
### Request Example
```json
{
"only_balances": false
}
```
### Response
#### Success Response (200)
- **entity** (object) - The created entity.
#### Response Example
```json
{
"entity": {}
}
```
```
--------------------------------
### GET /error-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves a list of error codes. No authentication required.
```APIDOC
## GET /error-codes/
### Description
Retrieves a list of error codes. No authentication required.
### Method
GET
### Endpoint
/error-codes/
### Parameters
None
### Response
#### Success Response (200)
- Success response body.
#### Error Statuses
- 400 - Bad request
```
--------------------------------
### POST /domains/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md
Adds a domain. The `tokenize` parameter in the request body controls whether tokenization is enabled, with a default of `1` (enabled).
```APIDOC
## [POST] /domains/
### Description
Adds a domain. The `tokenize` parameter in the request body controls whether tokenization is enabled, with a default of `1` (enabled).
### Method
POST
### Endpoint
/domains/
### Parameters
#### Request Body
- **tokenize** (integer) - Optional - Default: `1`. Set to `1` to enable tokenization, `0` to disable.
### Request Example
```json
{
"tokenize": 1
}
```
### Response
#### Success Response (200)
- **domain** (object) - The created domain.
#### Response Example
```json
{
"domain": {}
}
```
```
--------------------------------
### GET /entities/category-types/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves category types for entities. No authentication required.
```APIDOC
## GET /entities/category-types/
### Description
Retrieves category types for entities. No authentication required.
### Method
GET
### Endpoint
/entities/category-types/
### Parameters
None
### Response
#### Success Response (200)
- Success response body.
#### Error Statuses
- 400 - Bad request
```
--------------------------------
### GET /warning-codes/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves the warning-code catalog with the same response shape as `/error-codes/`. Supports language selection.
```APIDOC
## GET /warning-codes/
### Description
Returns the warning-code catalog.
### Method
GET
### Endpoint
/warning-codes/
### Parameters
#### Query Parameters
- **lang** (string) - Optional - Language for the catalog.
### Response
#### Success Response (200)
Returns an array of warning-code objects with fields: `code`, `description`, `possible_reasons`, `how_to_proceed`.
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/errors.md
Retrieves a list of entities. Returns a 400 error on invalid request.
```APIDOC
## [GET] /entities/
### Description
Retrieves a list of entities. Returns a 400 error on invalid request.
### Method
GET
### Endpoint
/entities/
### Response
#### Success Response (200)
- No details provided in source.
#### Error Response (400)
- **error** - Invalid request.
```
--------------------------------
### Advanced per-product schema with PDFs and error handling (Python)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md
Posts to /entities/ with a per-product schema selecting specific accounts/cards by UUID, enabling only_balances, add_pdf_from_uuids, and date_from options. Handles login errors (codes 2000-2999) by not retrying and prints a session ID for support. Requires a valid API key, entity code, and token.
```python
import requests
# required_products_schema selects specific accounts/cards (by uuid) with
# per-product options: only_balances, add_pdf_from_uuids, date_from
schema = json.dumps({
"ACCOUNTS": {
"0ae4d722b1c82feeafb4b36b2893230444071335": {
"only_balances": False,
"add_pdf_from_uuids": ["90763109952d4f2ebece8dceca8254078c5384a0"],
"date_from": "2024-04-03",
}
},
"CARDS": {"957e6f63546f3fecacce80192b6f7436496dc057": {}}
})
r = requests.post("https://api.wealthreader.com/entities/", data={
"api_key": "12345678",
"code": "caixabank",
"token": "FRJ0mHlaqZwLzu",
"required_products_schema": schema,
"add_pdf_from_uuids": "90763109952d4f2ebece8dceca8254078c5384a0",
})
if r.status_code != 200:
body = r.json()[0] # error envelope (array)
code = body["error"]["code"]
print("SESSION (save for support):", body["statistics"]["SESSION"])
if 2000 <= code < 3000: # login family: do NOT retry
raise SystemExit(f"login error: {body['error']['message']}")
raise SystemExit(f"temporary error {code}, retry with backoff")
data = r.json()[0]["payload"]
print(data["accounts"][0]["transactions"][0]["pdf_file"]) # Base64 PDF
```
--------------------------------
### GET /entities/category-types/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md
Retrieves the transaction category catalog. Supports language selection via the `lang` query parameter.
```APIDOC
## GET /entities/category-types/
### Description
Returns the transaction category catalog.
### Method
GET
### Endpoint
/entities/category-types/
### Parameters
#### Query Parameters
- **lang** (string) - Optional - Language for the catalog: `es` (default) or `en`.
### Response
#### Success Response (200)
Returns an array of `category-types` objects.
```
--------------------------------
### register-user-response (200 OK)
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md
Successful response body for POST /user/register/. Returns success flag and message.
```json
{ "success": true, "message": "User registered successfully" }
```
--------------------------------
### GET /entities/
Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/README.md
Retrieves a list of entities associated with the authenticated user. This endpoint returns basic information about each entity.
```APIDOC
## [GET] /entities/
### Description
Retrieves a list of entities associated with the authenticated user.
### Method
GET
### Endpoint
/entities/
### Parameters
#### Query Parameters
- `api_key` (string) - Required - API key for authentication.
- `token` (string) - Required - Token obtained from authentication.
### Request Example
GET /entities/?api_key=your_api_key&token=your_token
### Response
#### Success Response (200)
- `entities` (array) - List of entity objects.
#### Response Example
{
"entities": [
{
"id": "12345",
"name": "John Doe"
}
]
}
```