# Overview This collection of API endpoints enables you to access data and perform actions on your Investec Private Bank account, whether for **personal or business use**. With these APIs, you can: - Retrieve a list of your accounts - Check account balances - Get your transaction history - Get a list of your Investec Online Banking profiles - Access your list of beneficiaries - Make payments to beneficiaries - Get details on who is a listed authoriser and the authorisation period (typically for business payments) - Transfer funds between accounts - Download PDF documents such as account statements and tax certificates # Authentication

View Authentication details

- 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.

# Quickstarts

View Quickstart (cURL)

This Quickstart walks you through making your first successful API call to the Private Bank API endpoints. By the end of this guide, you will: - Authenticate using OAuth 2.0 client credentials and your x-api key - Call the Get Accounts endpoint - Receive an HTTP 200 OK response with a list of your accounts linked to your Investec Private Bank profile. **Before you start** Make sure you have the following: - An **Investec Private Individual** or **Private Business** account or optionally use the Sandbox - 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](#Sandbox) section for sandbox keys) - API key scopes include at least “accounts” (not required for Sandbox) - An API client such as Postman, Curl or your own application code. **Choose your environment** You can make your first call in either sandbox or production. The flow is identical. The Sandbox API will return mock data, and all actions can be run multiple times. Keep in mind that the sandbox is stateless and therefore, for example, balances won’t be updated when transfers are made in the sandbox. **Sandbox** Use this for development and testing. **Base API URL**: https://openapisandbox.investec.com **Production** Use this when you are ready to connect to your live account data. **Base API URL**:https://openapi.investec.com **Step 1: Get an access token** All Private Bank APIs use OAuth 2.0 with the client credentials grant type. The client_id and client_secret are combined and Base64 encoded to create the value used in the Authorization header as Basic {base64_value}. You must include: - HTTP Basic Auth (client_id:client_secret) - Your x-api key **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 accounts** Now that you have a token, you can call the Private Bank API accounts endpoint. **Sandbox** https://openapisandbox.investec.com/za/pb/v1/accounts **Production** https://openapi.investec.com/za/pb/v1/accounts **Request example** ```bash curl --location 'https://openapisandbox.investec.com/za/pb/v1/accounts' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <>' ``` **What a successful call looks like (HTTP 200 OK)** If everything is set up correctly, you will receive HTTP 200 OK and a JSON response containing your accounts. **Successful response example** ```json { "data": { "accounts": [ { "accountId": "123456789", "accountNumber": "1234567890", "accountName": "Primary Private Bank Account", "referenceName": "Main Account", "productName": "Private Bank Cheque", "kycCompliant": true, "profileId": "ABCDEF" } ] }, "links": { "self": "https://openapisandbox.investec.com/za/pb/v1/accounts" }, "meta": { "totalPages": 1 } } ``` This confirms that your authentication flow is working, your API key has the correct scopes, and you can successfully access Private Bank account data. **Step 3: How to debug your first call** **Common issues on a first call** | Issue | Guidance | |-------|----------| | Token request fails | Ensure you are using HTTP Basic Auth and that the x-api-key is included | | 401 response | Check that your credentials are correct | | 403 response | Confirm your API key includes the `accounts` scope |

View Quickstart (Postman)

[Open the collection in Postman](https://www.postman.com/investec-open-api/workspace/programmable-banking/collection/26868804-00260d55-0009-42ee-b148-d439992e64ff?action=share&creator=26868804) [Run in Postman](https://god.gw.postman.com/run-collection/26868804-00260d55-0009-42ee-b148-d439992e64ff?action=collection%2Ffork&collection-url=entityId%3D26868804-00260d55-0009-42ee-b148-d439992e64ff%26entityType%3Dcollection%26workspaceId%3D905c2bab-81a1-4297-8b70-2456c776a7a0) The instructions below will guide you through the process of authenticating and getting your accounts in Postman. Before you start, **fork** the appropriate collection, and work on the fork now available in My Workspace. **1. Authenticate** 1. Head over to the **Variables** tab to set your environment variables 2. Insert your client ID, client secret, and x-api key. 3. Navigate to the Auth folder, and the POST Authentication query (URL: https://openapi.investec.com/identity/v2/oauth2/token). - Under **Authorization**: The Auth type is set to Basic Auth - Under **Headers**: Your headers include the x-api-key header which uses the key you just filled in. - Under **Body**: In the request body, the grant-type field has the value client_credentials 4. Hit send on the request. In response to your client id, secret and x-api-key, the endpoint will respond with a secure token, called a bearer token, and the period for which the token is valid (30 minutes). Navigate back to the Variables table and **paste your token into the token field**. **2. Get your accounts** 1. Navigate to the Accounts folder and the GET Accounts query 2. Hit Send to make a call to the Account Information API endpoint (no additional parameters need to be set). The JSON response will include all your accounts, and each account has a unique ID (accountId) that you will use when transacting against it.

# 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**. - The sandbox has the following scopes: - accounts - Account information - balances - Account balance information - transactions - Transaction history - transfers - Inter account transfer - beneficiarypayments - Beneficiary payments - documents - pdf statements and tax certificates. - Follow the [Quickstart](#Quickstart(cURL)) instructions to get going using the Sandbox **Sandbox credentials** | Field | Value | |-------|--------| | client_id | `yAxzQRFX97vOcyQAwluEU6H6ePxMA5eY` | | client_secret | `4dY0PjEYqoBrZ99r` | | x-api-key | `eUF4elFSRlg5N3ZPY3lRQXdsdUVVNkg2ZVB4TUE1ZVk6YVc1MlpYTjBaV010ZW1FdGNHSXRZV05qYjNWdWRITXRjMkZ1WkdKdmVBPT0=`| | Authorization | Basic `eUF4elFSRlg5N3ZPY3lRQXdsdUVVNkg2ZVB4TUE1ZVk6NGRZMFBqRVlxb0JyWjk5cg==`| # Release notes

Description of API changes

2026-05-06 - **Deprecation**: Removed the Transfer Multiple V1 endpoint from the documentation. 2024-11-07 - **Enhancement**: Added an additional pending transactions endpoint `/za/pb/v1/accounts/{accountId}/pending-transactions` - **Enhancement**: Added support for `?includePending=true` - **Enhancement**: Added a uuid property to the transactions endpoint - **Enhancement**: Added approved beneficiaries with `"beneficiaryType": "INVESTECAPPROVED"` 2023-09-07 - **Enhancement**: Added payment initiation requiring authorisation 2023-08-24 - **Enhancement**: Added document retrieval - **Enhancement**: Added more balances to the Balance endpoint 2023-05-29 - **Enhancement**: Updated response codes returned 2023-03-05 - **Enhancement**: Added a sandbox environment 2022-11-25 - **Enhancement**: Included inter account transfers v2 - **Enhancement**: Included beneficiary payments - **Enhancement**: Included beneficiaries - **Enhancement**: Included beneficiary categories 2022-02-21 - **Enhancement**: Included inter account transfers 2021-10-01 - **Fix**: Running balance displays correctly for negative values 2020-11-13 - **Enhancement**: Added transaction type filter 2020-11-10 - **Enhancement**: Added postedOrder and transactionType 2020-09-08 - **Fix**: Implemented CORS and multi User-Agent support 2020-07-21 - **Enhancement**: Added transactionDate and date range filtering