NAV Navbar
shell ruby python javascript
  • Introduction
  • Authentication
  • Accounts
  • Portfolio
  • Cash Statements
  • Transactions
  • Errors
  • Introduction

    The AJ Bell API currently offers read-only access to portfolio and investment information for authenticated account holders of our AJ Bell Youinvest platform.

    Future enhancements will include support for AJ Bell Investcentre and some transactional capabilities, such as account opening.

    If you've visited this API documentation directly, please take the time to review how we work with developers on our main ajbell.io website.

    Authentication

    AJBell's API's are built on the oAuth2 authorisation protocol. You will need to register your service with AJ Bell to gain access to these API's. We will require the return URL your service will be using to process the authentication code - this endpoint must be served under SSL. During your development phase we will provide access to test customer data.

    client return URL: https://acme.com/myaccounts

    Once registered you will receive the following information which must be kept secret to your organisation:

    client id: acmeClientId

    client secret: secret

    token: mysecrettoken

    Step 1 - Obtain redirect URL

    To establish our mutual customer is comfortable with giving your service access to their details we need them to login on our system. Call this endpoint to determine where the user should be redirected to.

    To obtain redirect URL, use this code:

    
    
    
    
    # With shell, you can just pass the correct header with each request
    curl "https://www.ajbell.io/v1.0.0/ajbyi/authorisation/get-authentication-url"
      -H "oAuthClientId: acmeClientId"
      -H "signature: MYCHECKSUMTOCHECKONRETURN"
      -H "redirectURI: https://acme.com/myaccounts"
    
    
    

    Make sure to replace all values with your values.

    Step 2 - Redirect client to URL

    Using the response from step 1 you will need to redirect the client to the AJ Bell login form.

    Response from step 1

    {
      "host": "openbanking.youinvest2.co.uk",
      "basePath": "/login?state=wqeqweqw&redirect_uri=https%3A%2F%2Fopenbanking.youinvest2.co.uk%2Facme%2Fauthenticate",
      "schemas": [
        {
          "schema": "https"
        }
      ]
    }
    

    Step 3 - Security token generation

    Once the customer has successfully authenticated we will re-direct them to the URL you specified when you were set up. There will also be two GET parameters passed.

    1. code (required for step 4)
    2. state (same signature passed in for step 1. This should be validated)

    Using the code receive we can now retrieve the API token.

    To obtain security token:

    
    
    
    
    # With shell, you can just pass the correct header with each request
    curl "https://www.ajbell.io/v1.0.0/ajbyi/authorisation/get-authentication-token"
    
      -H "authenticatedCode: myauthcode"
      -H "oAuthClientId: acmeClientId"
      -H "oAuthSecret:  secret"
      -H "redirectURI: https://acme.com/myaccounts"
    
    
    

    Make sure to replace all values with your values.

    Response from step 3

    {
      "authorization": "5888249c808d5f3a8997043f3ab95321d23c5c60",
      "expires": 2592000,
      "type": "Bearer",
      "scope": "readonly"
    }
    

    Accounts

    Get all accounts

    
    
    
    
    curl "https://www.ajbell.io/v1.0.0/ajbyi/accounts"
      -H "partnerToken: mysecrettoken"
      -H "oAuthToken: 5888249c808d5f3a8997043f3ab95321d23c5c60"
    
    
    

    The above command returns JSON structured like this:

    [
      {
        "name": "Mrs T Smith",
        "holdingValuation": 100000,
        "id": "A12345I",
        "state": "active",
        "totalValuation": 200000,
        "currencyCode": "GBP",
        "productType": "dealing",
        "cashValuation": 100000
      }
    ]
    

    This endpoint retrieves all accounts belonging to the customer.

    accountRef is always prefixed with an 'A' followed by 5 alphanumeric characters after which the account type is specified by one of 'D' (dealing), 'S' (sipp), 'I' (ISA) or 'L' (life-time ISA). Account types however can be identified more easily from 'productType'.

    HTTP Request

    GET https://www.ajbell.io/v1.0.0/ajbyi/accounts

    Header Parameters

    Parameter Description
    partnerToken The token set up during onboarding.
    oAuthToken Token obtained via authentication process.

    Portfolio

    Get portfolio for given account

    
    
    
    
    curl "https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/portfolio
    "
      -H "partnerToken: mysecrettoken"
      -H "oAuthToken: 5888249c808d5f3a8997043f3ab95321d23c5c60"
    
    
    

    The above command returns JSON structured like this:

    {
      "holdings": [
        {
          "priceCurrency": "GBP",
          "cost": 4.1,
          "quantity": 27,
          "valueCurrency": "GBP",
          "price": 2.3195,
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "changeValue": 58.53,
          "changePercentage": 1427.5609756,
          "value": 62.63,
          "dayChangePercentage": -2.5010509
        },
        {
          "priceCurrency": "GBP",
          "cost": 4.1,
          "quantity": 27,
          "valueCurrency": "GBP",
          "price": 2.3195,
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "changeValue": 58.53,
          "changePercentage": 1427.5609756,
          "value": 62.63,
          "dayChangePercentage": -2.5010509
        }
      ],
      "account": {
        "name": "Mrs T Smith",
        "holdingValuation": 100000,
        "id": "A12345I",
        "state": "active",
        "totalValuation": 200000,
        "currencyCode": "GBP",
        "productType": "dealing",
        "cashValuation": 100000
      }
    }
    

    A portfolio represents the cash and investments held within a specific account. If a customer holds multiple accounts with us you will need to request this method for each account held if updating by batch jobs; or call the portfolio method for the account being viewed if making real-time requests from your service.

    Prices are a minimum of 15 minutes delayed during market hours.

    HTTP Request

    GET https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/portfolio

    Header Parameters

    Parameter Description
    partnerToken The token set up during onboarding.
    oAuthToken Token obtained via authentication process.

    Path Parameters

    Parameter Description
    accountRef The id of the account e.g. A12345I

    Cash Statements

    Get cash statements for given account

    
    
    
    
    curl "https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/cash-statement
    "
      -H "partnerToken: mysecrettoken"
      -H "oAuthToken: 5888249c808d5f3a8997043f3ab95321d23c5c60"
    
    
    

    The above command returns JSON structured like this:

    {
      "fromDate": "2000-01-23T04:56:07.000+00:00",
      "cashTransactions": [
        {
          "reference": "44614C85343",
          "dateTime": "2000-01-23T04:56:07.000+00:00",
          "amount": -9.99,
          "balance": 10000,
          "description": "Purchase 627 KENMARE RESOURCES EUR0.06",
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "type": "purchase",
          "amountCurrencyCode": "GBP",
          "balanceCurrency": "GBP"
        },
        {
          "reference": "44614C85343",
          "dateTime": "2000-01-23T04:56:07.000+00:00",
          "amount": -9.99,
          "balance": 10000,
          "description": "Purchase 627 KENMARE RESOURCES EUR0.06",
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "type": "purchase",
          "amountCurrencyCode": "GBP",
          "balanceCurrency": "GBP"
        }
      ],
      "toDate": "2000-01-23T04:56:07.000+00:00",
      "account": {
        "name": "Mrs T Smith",
        "holdingValuation": 100000,
        "id": "A12121A",
        "state": "active",
        "totalValuation": 200000,
        "currencyCode": "GBP",
        "productType": "dealing",
        "cashValuation": 100000
      }
    }
    

    This endpoint retrieves cash statement for given account. A cash statement displays all entries relevant to the account where the cash balance was impacted. The sale of an investment, a dividend payment or a cash deposit for example.

    HTTP Request

    GET https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/cash-statement

    Header Parameters

    Parameter Description
    partnerToken The token set up during onboarding.
    oAuthToken Token obtained via authentication process.

    Path Parameters

    Parameter Description
    accountRef The id of the account e.g. A12345I

    Query Parameters

    Parameter Default Description
    fromDate Month ago Statements from date (expected format)
    toDate Today Statements to date (expected format)

    Transactions

    Get transactions for given account

    
    
    
    
    curl "https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/transactions"
      -H "partnerToken: mysecrettoken"
      -H "oAuthToken: 5888249c808d5f3a8997043f3ab95321d23c5c60"
    
    
    

    The above command returns JSON structured like this:

    {
      "fromDate": "2000-01-23T04:56:07.000+00:00",
      "toDate": "2000-01-23T04:56:07.000+00:00",
      "transactions": [
        {
          "reference": "44614C85343",
          "dateTime": "2000-01-23T04:56:07.000+00:00",
          "costCurrencyCode": "GBP",
          "quantity": 40,
          "cost": -9.99,
          "description": "Purchase 627 KENMARE RESOURCES EUR0.06",
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "type": "purchase"
        },
        {
          "reference": "44614C85343",
          "dateTime": "2000-01-23T04:56:07.000+00:00",
          "costCurrencyCode": "GBP",
          "quantity": 40,
          "cost": -9.99,
          "description": "Purchase 627 KENMARE RESOURCES EUR0.06",
          "instrument": {
            "market": "LSE",
            "symbol": "VOD",
            "instrumentType": "share",
            "name": "Vodafone Group PLC",
            "currencyCode": "GBX",
            "isin": "GB00BH4HKS39"
          },
          "type": "purchase"
        }
      ],
      "account": {
        "name": "Mrs T Smith",
        "holdingValuation": 100000,
        "id": "A12121A",
        "state": "active",
        "totalValuation": 200000,
        "currencyCode": "GBP",
        "productType": "dealing",
        "cashValuation": 100000
      }
    }
    

    This endpoint retrieves transactions for given account. Transactions include buys and sells, the outcome of corporate action events such as stock splits, dividend reinvestments for example.

    HTTP Request

    GET https://www.ajbell.io/v1.0.0/ajbyi/accounts/A12345I/transactions

    Header Parameters

    Parameter Description
    partnerToken The token set up during onboarding.
    oAuthToken Token obtained via authentication process.

    Path Parameters

    Parameter Description
    accountRef The id of the account e.g. A12345I

    Query Parameters

    Parameter Default Description
    fromDate Month ago Transactions from date (expected format)
    toDate Today Transactions to date (expected format)

    Errors

    The API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    405 Method Not Allowed -- You tried to access API with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.