> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rangler.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect accounts and portfolios fields

> Definitions, types, allowed values, and defaults for connect accounts and portfolios.

Use this reference with the endpoint documentation. A required field must be present; a nullable field can still contain `null`. Missing data does not mean zero. See [Field guide](/field-guide) for unit and status conventions.

### `POST /v1/connect/link-tokens`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `Idempotency-Key` | header | string or null | optional | Unique key for safely replaying the same link-token request. Reuse it only with the same request body. |

Request body: [Connect link token create](/fields/connect#connect-link-token-create).

### `POST /v1/connect/token/exchange`

Request body: [Connect public token exchange](/fields/connect#connect-public-token-exchange).

### `GET /v1/connect/institutions`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `products` | query | array of string or null | optional | Connect data products required of the returned institutions. |

### `GET /v1/connect/connections`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/portfolio`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `client_user_id` | query | string | required | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/portfolio/history`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `client_user_id` | query | string | required | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/connections/{connection_id}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `DELETE /v1/connect/connections/{connection_id}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `POST /v1/connect/connections/{connection_id}/refresh`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/connections/{connection_id}/accounts`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/connections/{connection_id}/positions`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |

### `GET /v1/connect/connections/{connection_id}/transactions`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `connection_id` | path | string (uuid) | required | Identifier of the end user's institution connection. |
| `client_user_id` | query | string or null | optional | Your stable end-user identifier used to select that user's authorized connections. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `100`. |
| `cursor` | query | string or null | optional | Opaque next-page cursor returned by the preceding response; pass it unchanged. |

<a id="connect-account-list" />

## Connect account list

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect account](/fields/connect#connect-account-read) | required | Returned records or observations. The item schema defines each element's fields. |

<a id="connect-account-read" />

## Connect account

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `connection_id` | string (uuid) | required | Identifier of the end user's institution connection. |
| `name` | string | required | Display name of the identified resource. |
| `type` | string | required | Institution-reported account or transaction category; values depend on the institution. |
| `subtype` | string or null | optional | Institution-reported account subtype when available. |
| `currency` | string | required | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `current_balance` | string or null | optional | Reported current account balance in currency. |
| `available_balance` | string or null | optional | Reported amount available to withdraw or transact, in currency. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |

<a id="connect-connection-detail" />

## Connect connection detail

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `organization_id` | string (uuid) | required | Identifier of the organization that owns this resource. |
| `institution_id` | string (uuid) | required | Identifier of the connected financial institution. |
| `client_user_id` | string | required | Your stable identifier for the end user. Keep it consistent across link and exchange requests. |
| `environment` | string | required | Key environment: test or live. Allowed values: `test`, `live`. |
| `status` | string | required | Connection state: active permits access, login\_required needs relinking, revoked means consent was withdrawn, and error indicates a connection failure. Allowed values: `active`, `login_required`, `revoked`, `error`. |
| `consent_scopes` | array of string | required | Products or data categories the end user authorized for this connection. |
| `last_synced_at` | string (date-time) or null | optional | Timestamp of the most recent completed data synchronization when available. |
| `revoked_at` | string (date-time) or null | optional | Timestamp when the end user's connection consent was revoked, if applicable. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |
| `institution` | [Connect institution](/fields/connect#connect-institution-read) | required | Institution identity and supported data capabilities. |
| `latest_sync` | [Connect sync run](/fields/connect#connect-sync-run-read) or null | optional | Most recent synchronization run and its outcome. |

<a id="connect-connection-list" />

## Connect connection list

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect connection](/fields/connect#connect-connection-read) | required | Returned records or observations. The item schema defines each element's fields. |

<a id="connect-connection-read" />

## Connect connection

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `organization_id` | string (uuid) | required | Identifier of the organization that owns this resource. |
| `institution_id` | string (uuid) | required | Identifier of the connected financial institution. |
| `client_user_id` | string | required | Your stable identifier for the end user. Keep it consistent across link and exchange requests. |
| `environment` | string | required | Key environment: test or live. Allowed values: `test`, `live`. |
| `status` | string | required | Connection state: active permits access, login\_required needs relinking, revoked means consent was withdrawn, and error indicates a connection failure. Allowed values: `active`, `login_required`, `revoked`, `error`. |
| `consent_scopes` | array of string | required | Products or data categories the end user authorized for this connection. |
| `last_synced_at` | string (date-time) or null | optional | Timestamp of the most recent completed data synchronization when available. |
| `revoked_at` | string (date-time) or null | optional | Timestamp when the end user's connection consent was revoked, if applicable. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |

<a id="connect-credential-field-read" />

## Connect credential field

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `name` | string | required | Machine-readable credential field name to submit during linking. Allowed values: `username`, `password`. |
| `label` | string | required | Human-readable label. Use the associated key or identifier for programmatic matching. |
| `input_type` | string | optional | HTML input type suitable for this credential field. Allowed values: `text`, `email`, `tel`, `password`. Default: `"text"`. |
| `autocomplete` | string or null | optional | Suggested browser autocomplete hint for this credential field. |
| `placeholder` | string or null | optional | Suggested placeholder text for the credential input. |

<a id="connect-currency-total" />

## Connect currency total

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `currency` | string | required | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `amount` | string | required | Monetary amount in the associated currency, in base currency units. |

<a id="connect-institution-read" />

## Connect institution

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `name` | string | required | Display name of the identified resource. |
| `auth_type` | string | required | Authentication method required by the institution's linking flow. |
| `logo_url` | string or null | optional | URL of the resource's logo when available. |
| `supports_accounts` | boolean | required | Whether the institution supports account data. |
| `supports_positions` | boolean | required | Whether the institution supports holdings or position data. |
| `supports_transactions` | boolean | required | Whether the institution supports transaction history. |
| `credential_fields` | array of [Connect credential field](/fields/connect#connect-credential-field-read) | optional | Credential-input definitions required by the institution's linking flow. |

<a id="connect-link-institution-list" />

## Connect link institution list

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect institution](/fields/connect#connect-institution-read) | required | Returned records or observations. The item schema defines each element's fields. |

<a id="connect-link-token-create" />

## Connect link token create

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `client_user_id` | string | required | Your stable identifier for the end user. Keep it consistent across link and exchange requests. |
| `client_name` | string or null | optional | Customer-facing name of your application shown during linking. |
| `products` | array of string | optional | Requested Connect products: accounts, positions, and/or transactions. |
| `institution_ids` | array of string | optional | Institution identifiers allowed for this link token; follow the request schema for defaults. |
| `allowed_origins` | array of string | required | Browser origins permitted to use the link token, including scheme, host, and optional port. |

<a id="connect-link-token-created" />

## Connect link token created

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `link_token` | string | required | Short-lived token used to initialize the linking flow. Treat it as a secret. |
| `link_token_id` | string (uuid) | required | Identifier of the issued link token. |
| `expiration` | string (date-time) | required | Timestamp after which the issued link token cannot be used. |
| `request_id` | string | required | Identifier for tracing this request when contacting support. |

<a id="connect-portfolio-balance-point" />

## Connect portfolio balance point

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `date` | string (date) | required | Calendar date of the observation in YYYY-MM-DD format. |
| `totals` | array of [Connect currency total](/fields/connect#connect-currency-total) | required | Portfolio totals grouped by currency. Different currencies are not added together. |

<a id="connect-portfolio-connection-read" />

## Connect portfolio connection

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `organization_id` | string (uuid) | required | Identifier of the organization that owns this resource. |
| `institution_id` | string (uuid) | required | Identifier of the connected financial institution. |
| `client_user_id` | string | required | Your stable identifier for the end user. Keep it consistent across link and exchange requests. |
| `environment` | string | required | Key environment: test or live. Allowed values: `test`, `live`. |
| `status` | string | required | Connection state: active permits access, login\_required needs relinking, revoked means consent was withdrawn, and error indicates a connection failure. Allowed values: `active`, `login_required`, `revoked`, `error`. |
| `consent_scopes` | array of string | required | Products or data categories the end user authorized for this connection. |
| `last_synced_at` | string (date-time) or null | optional | Timestamp of the most recent completed data synchronization when available. |
| `revoked_at` | string (date-time) or null | optional | Timestamp when the end user's connection consent was revoked, if applicable. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |
| `institution` | [Connect institution](/fields/connect#connect-institution-read) | required | Institution identity and supported data capabilities. |
| `accounts` | array of [Connect account](/fields/connect#connect-account-read) | required | Accounts belonging to this institution connection. |
| `totals` | array of [Connect currency total](/fields/connect#connect-currency-total) | required | Portfolio totals grouped by currency. Different currencies are not added together. |

<a id="connect-portfolio-history-read" />

## Connect portfolio history

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect portfolio balance point](/fields/connect#connect-portfolio-balance-point) | required | Returned records or observations. The item schema defines each element's fields. |

<a id="connect-portfolio-read" />

## Connect portfolio

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `connections` | array of [Connect portfolio connection](/fields/connect#connect-portfolio-connection-read) | required | Institution connections contributing to the end user's portfolio. |
| `totals` | array of [Connect currency total](/fields/connect#connect-currency-total) | required | Portfolio totals grouped by currency. Different currencies are not added together. |

<a id="connect-position-list" />

## Connect position list

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect position](/fields/connect#connect-position-read) | required | Returned records or observations. The item schema defines each element's fields. |

<a id="connect-position-read" />

## Connect position

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `connection_id` | string (uuid) | required | Identifier of the end user's institution connection. |
| `account_id` | string (uuid) or null | optional | Identifier of the institution account associated with the position or transaction. |
| `symbol` | string or null | optional | Trading symbol of the security. |
| `name` | string | required | Display name of the identified resource. |
| `logo_url` | string or null | optional | URL of the resource's logo when available. |
| `quantity` | string or null | optional | Number of security units held in this position. |
| `unit_price` | string or null | optional | Reported price per security unit in currency. |
| `market_value` | string or null | optional | Reported total market value of the position in currency. |
| `currency` | string | required | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `as_of` | string (date-time) or null | optional | Date or timestamp to which the observation applies; follow this field's declared format. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |

<a id="connect-public-token-exchange" />

## Connect public token exchange

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `public_token` | string | required | Short-lived token returned after successful linking, exchanged by your backend. Treat it as a secret. |
| `client_user_id` | string or null | optional | Your stable identifier for the end user. Keep it consistent across link and exchange requests. |

<a id="connect-sync-run-read" />

## Connect sync run

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `connection_id` | string (uuid) | required | Identifier of the end user's institution connection. |
| `status` | string | required | Synchronization outcome: pending means not completed, succeeded means completed successfully, and failed means the run failed. Allowed values: `pending`, `succeeded`, `failed`. |
| `trigger_source` | string | required | Reason or source that initiated the synchronization run. |
| `accounts_count` | integer | required | Number of accounts returned or processed by the synchronization run. |
| `positions_count` | integer | required | Number of positions returned or processed by the synchronization run. |
| `transactions_count` | integer | required | Number of transactions returned or processed by the synchronization run. |
| `error_code` | string or null | optional | Machine-readable synchronization error code when the run failed. |
| `error_message` | string or null | optional | Human-readable synchronization error explanation when the run failed. |
| `started_at` | string (date-time) | required | Timestamp when the synchronization run started. |
| `completed_at` | string (date-time) or null | optional | Timestamp when the synchronization run finished. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |

<a id="connect-transaction-list" />

## Connect transaction list

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Connect transaction](/fields/connect#connect-transaction-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `next_cursor` | string or null | optional | Opaque cursor for the next page. Pass it unchanged as cursor; null means no next page. |

<a id="connect-transaction-read" />

## Connect transaction

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `connection_id` | string (uuid) | required | Identifier of the end user's institution connection. |
| `account_id` | string (uuid) or null | optional | Identifier of the institution account associated with the position or transaction. |
| `type` | string | required | Institution-reported account or transaction category; values depend on the institution. |
| `description` | string | required | Human-readable explanation or source description of this resource. |
| `amount` | string | required | Monetary amount in the associated currency, in base currency units. |
| `currency` | string | required | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `posted_at` | string (date-time) | required | Timestamp when the institution posted the transaction. |
| `created_at` | string (date-time) | required | Timestamp when Rangler created this record; not the source publication time. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.