# Overview The Intermediaries API allows Investec intermediaries to: - Get account details, balances, and transactions - Get banks data - Get and create categories - Get client details - Request a forex quote and execute a trade, including bulk trades - Get the details of a trade - Get a list of intermediaries - Get, create, update and delete introducers # Authentication Decide which authentication route you will follow for your integration: - **OAuth 2**: Submit your API request in the context of your API key, client_id and client_secret - **3 Legged OAuth**: Submit your API requests in the context of an authorised user.

OAuth2.0

- Investec API authentication uses **OAuth 2.0 client credentials** (`client_id` and `client_secret`), with the addition of an `x-api-key`. - Log in to Investec Online to get your `client_id` and `client_secret` and to generate your `x-api key` with the scopes you require. **1. Get an access token** - To get an access token, you must exchange your `client_id`, `client_secret` and `x-api key` for the token. ```bash curl --location 'https://openapi.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Authorization: Basic <>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` **Headers explained:** - `x-api-key`: API key generated on Investec Online - `Authorization`: Base64-encoded `client_id:client_secret`. Take your `client_id` and `client_secret` and base64 encode them to provide a value for basic authorization. - `Content-Type`: Indicates the request body format **2. Use the token for all API requests** - Use the access token that you receive in all subsequent API requests - Access tokens are **valid for 30 minutes** and must be refreshed when expired ```bash curl --location 'https://openapi.investec.com/...' \ --header 'Authorization: Bearer <>' ``` **Notes** - Ensure your API key has the required scopes - you can set these when you create the key on Investec Online.

3 legged OAuth

You must be a registered third party to use 3 legged OAuth. You can apply on our Third Parties page.

# Quickstart

View Quickstart (cURL)

This Quickstart walks you through making your first successful API call to the Investec Intermediaries API endpoints. We will use the sandbox to do this. To go live in production, you will need an approved intermediary relationship with Investec. By the end of this guide, you will: - Authenticate using OAuth 2.0 client credentials and an x-api key - Retrieve an intermediaryId - Request an FX quote. **Before you start** Make sure you have the following: - You have enrolled for Investec Developer on Investec Online (not required if using Sandbox). - You have your client_id and client_secret from Investec Online and have created an API key (see Sandbox section for sandbox keys) - An API client such as Postman, cURL, or your own application code **Headers you will use on (almost) every call**: - **Authorization**: Bearer - **intermediaryId**: (required for most endpoints, you fetch it first) - **Content-Type**: application/json **Step 1: Get an access token (sandbox)** Sandbox: https://openapisandbox.investec.com. - To authenticate in the Sandbox environment, you are provided with a `client_id`, `client_secret`, and `x-api-key`. - The `client_id` and `client_secret` are combined and Base64 encoded to create the value used in the Authorization header as `Basic {base64_value}` — this encoded value is provided for you. - The `x-api-key` is sent as a separate header, and the request will return an `access_token`. - Sandbox credentials are available below in the Sandbox section. **Token request** ```bash curl --location 'https://openapisandbox.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic <>' \ --data-urlencode 'grant_type=client_credentials' ``` **What this does** - Authenticates your application - Returns a short-lived access token called a bearer token (valid for 30 minutes) - Confirms your credentials and API key are valid **Successful response example** ```json { "access_token": "qwertyuiop123456789", "token_type": "Bearer", "expires_in": 1799, "scope": "accounts" } ``` **Step 2: Get your intermediary profile** Retrieve the intermediary record (intermediaryId) under which you are authorised to operate under. You will use this ID in all subsequent requests along with your access token. **Request** ```bash curl --location 'https://openapisandbox.investec.com/za/ifi/v1/intermediaries' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' ``` **Response** ```json { "data": [ { "defaultIntermediaryId": 6937640749677390111, "intermediaryId": 8490342074772361992, "intermediaryType": "2", "intermediaryTypeCode": "3", "intermediaryTypeDescription": "consequatur", "intermediaryName": "Makayla Gutkowski", "intermediaryCapabilityTypeId": "9", "intermediaryCapabilityTypeName": "AdminAccess" } ] } ``` **Step 3: Request an FX quote** Request a quote for a currency pair. Populate only **buyCurrencyAmount** or **sellCurrencyAmount**, never both. The system calculates the other side automatically. **Request** ```bash curl --location 'https://openapisandbox.investec.com/za/ifi/v1/fx/quote' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'intermediaryId: 123456' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "tier": "TIER_1", "requestId": "qs-quote-0001", "currencyPairs": [ { "currencyPair": "USDZAR", "buyCurrency": "USD", "sellCurrency": "ZAR", "buyCurrencyAmount": 10000.0, "sellCurrencyAmount": null, "tenor": "SP" } ] } ``` **Response** ```json { "data": { "channel": "circuit global", "tier": "Tier 3", "source": "IFI", "clientId": "541867890", "counterparty": "solid state Profit-focused", "requestId": "gkie3hp8xn", "timeToLive": 5.72412487595921, "requestDateTime": "7/11/2025 8:42:20 PM", "currencyPairs": [ { "currencyPair": "AUDZAR", "buyCurrency": "ZAR", "sellCurrency": "AUD", "buyCurrencyAmount": 3.53, "sellCurrencyAmount": 59.53, "tenor": "TODAY", "expiryTime": "5/9/2026 2:34:52 AM", "rateId": "137b07f3-5308-8bd3-ff6b-cf8552dd0bcf", "side": "A", "clientRate": 0.6656, "maxClientRate": 0.5976, "settlementDate": "2027-02-21" }, { "currencyPair": "AUDZAR", "buyCurrency": "ZAR", "sellCurrency": "AUD", "buyCurrencyAmount": 64.57, "sellCurrencyAmount": 92.79, "tenor": "TODAY", "expiryTime": "8/26/2026 10:20:12 PM", "rateId": "aa1e1855-f395-e884-c22d-76ed95c3b582", "side": "A", "clientRate": 0.7, "maxClientRate": 0.6348, "settlementDate": "2026-05-21" }, { "currencyPair": "AUDZAR", "buyCurrency": "ZAR", "sellCurrency": "AUD", "buyCurrencyAmount": 57.27, "sellCurrencyAmount": 43.69, "tenor": "TODAY", "expiryTime": "2/1/2027 8:17:37 AM", "rateId": "9e617e64-7d07-07c4-727e-9c64e47f3241", "side": "A", "clientRate": 0.0212, "maxClientRate": 0.1425, "settlementDate": "2027-01-22" }, { "currencyPair": "AUDZAR", "buyCurrency": "ZAR", "sellCurrency": "AUD", "buyCurrencyAmount": 69.92, "sellCurrencyAmount": 13.82, "tenor": "TODAY", "expiryTime": "11/9/2026 3:39:12 PM", "rateId": "828a567a-dde8-6022-fd96-b038784d59cb", "side": "A", "clientRate": 0.5279, "maxClientRate": 0.5303, "settlementDate": "2026-07-30" }, { "currencyPair": "AUDZAR", "buyCurrency": "ZAR", "sellCurrency": "AUD", "buyCurrencyAmount": 95.67, "sellCurrencyAmount": 55.69, "tenor": "TODAY", "expiryTime": "7/26/2026 7:11:33 PM", "rateId": "7452bf5d-760f-59eb-bf16-334bd36e8179", "side": "A", "clientRate": 0.1683, "maxClientRate": 0.3753, "settlementDate": "2027-01-09" } ] }, "links": { "self": "https://openapisandbox.investec.com/za/ifi/v1/fx/quote" }, "meta": { "totalPages": 1 } } ``` The response includes: - rateId — required to accept the quote - clientRate — base rate - maxClientRate — maximum allowed client rate - expiryTime — quote validity. # Sandbox

Sandbox access

**Base API URL**: https://openapisandbox.investec.com - To authenticate in the Sandbox environment, you are provided with a **client_id**, **client_secret**, and **x-api-key**. - The client_id and client_secret are combined and **Base64 encoded** to create the value used in the Authorization header as Basic {base64_value} — this encoded value is provided below for you. - The x-api-key is sent as a separate header, and the request will return an **access_token**. - Follow the Quickstart(cURL) instructions to get going using the Sandbox **Sandbox credentials** | Field | Value | |-------|--------| | client_id | `3SWvHA3qXmnA25WAuaKGgz0Ou4bqWfrN` | | client_secret | `FUIK0AZiIWNffGGo` | | x-api-key | `M1NXdkhBM3FYbW5BMjVXQXVhS0dnejBPdTRicVdmck46YVc1MlpYTjBaV010ZW1FdGFXWnBMV0ZqWTI5MWJuUnpMV2x1ZG1WemRHVmpNMnh2WVMxellXNWtZbTk0`| | Authorization | Basic `M1NXdkhBM3FYbW5BMjVXQXVhS0dnenBPdTRicVdmck46RlVJSzBBWmlJV05mZkdHbw==`| # Additional guides

Bulk Trading

Request multiple FX quotes and execute multiple trades simultaneously. **Overview** Bulk trading allows you to request multiple FX quotes and execute multiple trades, significantly improving efficiency for high-volume operations. The following is important to note regarding bulk trading: 1. Some trades can succeed, while others fail (partial success) 2. All quotes in a batch use the same rate timestamp 3. Credit checks are performed on cumulative limits, not on individual trade values. Grouping is done by account, currency pair, and tenor. **Account grouping** Trades are grouped by account number. Different accounts have independent limit checks. **Currency pair** Limits apply per currency pair. EURUSD and GBPUSD have separate limit calculations. **Tenor-specific** Different limits apply for today, tom, and spot trades. Each tenor has independent limit checks. **Example** If you submit 5 trades — 3 × EURUSD spot and 2 × EURUSD today for the same account — the system will check cumulative limits for: - Account-123 + EURUSD + spot = 3 trades cumulative - Account-123 + EURUSD + today = 2 trades cumulative **Error handling** - Credit limit exceeded: Cumulative exposure exceeds limits for a specific grouping. - Rate expiry: One or more rates expired during batch processing. - Invalid account: Account number validation failed. - Settlement issues: Settlement date conflicts or holidays. **Best practices** - Always validate account numbers before bulk submission - Monitor cumulative exposures by grouping criteria - Handle partial batch failures gracefully - Log detailed error responses for debugging

Critical fields and rules

| Field | Rule | |------|------| | tier | Static value provided by Investec to denote the tier. Defaults to Tier_1 for intermediaries. | | request_id | Unique id per rate request. Reusable for trade booking. No duplicate trades. | | buy_amount / sell_amount | Populate only one side. The system calculates the other automatically. | | tenor | Use null for earliest available. The system rolls today → tom → spot automatically. | | rate_id | Taken from the quote response. Required to book trades against specific rates. | | counterparty_client_rate | 4 decimals, non-inverted. Must exceed client_rate and remain below max_client_rate. | | account_number | Required for cash trades. Optional for credit facility trades. |

Troubleshooting

Common issues, their causes, and how to resolve them. **500 Internal Server Error** **Cause** Request formatting issues, not data problems. There is a known issue with counterparty validation failures. **Solutions** - Verify counterparty_id exact format - Check JSON payload structure and field types - Log the complete error response for support analysis - Test with known working counterparties first --- **Quote Expired Error** **Cause** Exceeded the 10-second response window. **Solutions** - Optimise your margin calculation logic - Pre-calculate margins where possible - Monitor expires_at timestamps (UTC) - Request a new quote if expired --- **Insufficient Funds Error** **Cause** Account balance is too low for a cash-backed trade. **Solutions** - Check account balance before trading - Switch to a credit facility if available - Configure auto-default to credit - Fund the account or increase the credit line --- **Authentication Errors** **Cause** Token issues or insufficient scopes. **Solutions** - Verify the token has trading and settlements scopes - Check token expiration - Use separate tokens for trading vs settlements if required - Refresh OAuth2 tokens as needed --- **Rate Precision and Margin Errors** **Cause** Invalid client rate format or margin calculation. **Solutions** - Use 4 decimal places for most currencies and 2 for JPY - Ensure client_rate includes VAT in the margin - Check the rate does not exceed the max_client_rate cap - Validate the margin calculation: TOC rate + margin (incl. VAT) --- **Settlement Date Issues** **Cause** Cutoff times or unsupported tenors. **Solutions** - Check cutoff times via the /forex/tenors endpoint - Same-day trades auto-adjust to the next available settlement - Only T, T+1, and spot are currently supported - Forward contracts (1M, 3M) are coming soon

# Release Notes

Description of API changes

2025-12-05 * **Release**: Forex Bulk Trades Enablement 2024-10-01 * **Release**: Added forex capabilities 2023-04-04 * **Release**: First release