NAV Navbar
Logo
curl

Introduction

API Production:

"https://api.telleroo.com"

API Sandbox:

"https://sandbox.telleroo.com"

Welcome to Telleroo API documentation! You can use this API for sending payments out through bank transfers - faster payments in the UK and SEPA in the Eurozone.

Overview

How does it work?

Here’s an overview of the structure of the API:

API endpoint Description
/accounts Returns unique ID including current available balance in pence/cents (e.g. 100 equals 1 GBP/EUR).
/recipients/{id} Returns (GET) or deletes (DELETE) a single recipient.
/recipients Retrieves (GET) recipients or creates (POST) a single recipient.
/bank_transfers Creates a bank transfer request to a recipient for a selected account.
/adhoc_bank_transfers Creates a bank transfer request to a adhoc recipient for a selected account.
/transactions Specify start_date and end_date to get a list of your complete account activity, including credits and all transfers.
/transactions/{id} Retrieves all relevant data of a single transaction including transfer status.

Transfer Status

When a bank transfer request is made the following statuses apply to your payment request.

Status Meaning Example
Preparing Payment Payment is being prepared to be sent e.g. Further checks on recipient (KYC)
Payment Sent Payment has been sent to recipients bank account. e.g. Recipient should receive payment unless there is a problem on their side.
Waiting for funds Request successfully created but balance is insufficient. Payment will be made as soon as sufficient funding is in the account. e.g. tried to deliver 50 GBP and the available balance is only 45 GBP. After an additional credit of 5 GBP the request goes to Preparing Payment.
Looking into it We’re looking into this payment. e.g. were checking this payment and will notify you if you need to take any action.
Failed Request initially sent but failed while trying to deliver. e.g. wrong account details such as closed bank account or changed details.

Authentication

Using your login credentials, you can generate unique API key’s required for every API call. Here you can generate or revoke tokens securely on your Telleroo Dashboard:

All API requests are made over HTTPS. To make calls to the API you must add a key named ‘Authorization’ to the HTTP request header containing your Authorization Token. API requests over plain HTTP or without authentication will fail.

Full Access Token

This token allows you full access to all API endpoints. You can also set the approval option:

Transactions Approved - Any bank transfers made will be automatically Approved.

Transaction Approval required - Any bank transfer made will need approve from the Telleroo dashboard.

Recipient Access

This token allows access to recipient endpoint to create, view (censored bank details) and delete recipients.

API Endpoints

Accounts List

curl "https://api.telleroo.com/accounts" \
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "accounts": [
    {
      "id": "7e583a6d-0869-4c62-9f2c-74a75b8c2a75",
      "name": "client account",
      "currency": "GBP",
      "balance": 500,
      "awaiting_funds_balance": 640,
      "awaiting_approval_balance": 100,
      "account_no": "12345678",
      "sort_code": "123456",
      "tag": "UK Marketplace"
    }
  ]
}

This retrieves all bank accounts assigned to your company including a unique ID.

HTTP request

GET https://api.telleroo.com/accounts

Parameter Type Description
Authorization String Your authorization key.

Recipients List

curl "https://api.telleroo.com/recipients" \
  -H Authorization: "your_auth_token" \
  -d page=1 \
  -X GET

The above command returns JSON structured like this:

{
  "recipients": [
    {
      "id": "ff17b231-2bc4-485e-967e-231867e15fd6",
      "name": "John Archer",
      "currency_code": "GBP",
      "account_no": "12345678",
      "sort_code": "123456",
      "legal_type": "PRIVATE"
    },
    {
      "id": "1fdfef97-95b8-4985-917a-5d9ac9d52d35",
      "name": "António Silva",
      "currency_code": "EUR",
      "iban": "12345678901234567",
      "bic": "12345678901",
      "legal_type": "PRIVATE"
    }
  ]
}

Retrieves all recipients under your company. You can use the recipients ID to send bank transfers to.

HTTP request

GET https://api.telleroo.com/recipients

Parameter Type Description Optional
Authorization String Your authorization key.
page Integer Page you want to return. Pagination index starts at 1. optional

Single Recipient

curl "https://api.telleroo.com/recipients/ff17b231-2bc4-485e-967e-231867e15fd6" \
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "recipient": {
    "id": "ff17b231-2bc4-485e-967e-231867e15fd6",
    "name": "John Archer",
    "currency_code": "GBP",
    "account_no": "12345678",
    "sort_code": "123456",
    "legal_type": "PRIVATE"
  }
}

Retrieves single recipient by id in URL path.

HTTP request

GET https://api.telleroo.com/recipients/{id}

Parameter Type Description
Authorization String Your authorization key.

Accepted PRIVATE names examples

Andrew Cookson
Bu Le
James St Peter Johnson

Rejected PRIVATE names examples

Andrew
B Le
Bu L
Mr James
James j2

Accepted BUSINESS names examples

Tokyo Bikes
Andrew ltd
Andrew Kitchen
Tenbells
Bikes 1

Rejected BUSINESS name examples

Andrew (This would fall into common name category)
Charlie (This would fall into common name category)

If the recipient is an individual, legal_type must be set to PRIVATE. This recipients name must contain at least their first and second name of 2 characters each.

The individual name can only contain letters, hyphens, underscores, curved brackets, single quotes, asterisks, commas and dots eg.

Ben Dreamer

If the recipient is a business, legal_type must be set to BUSINESS. Most business names are accepted - but common names can be flagged and rejected. We ask you include the business type after the name to avoid this from happening eg.

Micheal Ltd

Recipient Creation

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "account": {
    "id": "a60f2402-8b7e-4f39-8ddb-d9082b7951ad",
    "name": "Sam Jenkins",
    "currency_code": "GBP",
    "account_no": "12345678",
    "sort_code": "123456",
    "legal_type": "PRIVATE"
  }
}

All bank details added will be validated in both sandbox and production.

Valid sort code and Account Numbers

account_no: 22345678 , 12345678 , 2345678 , 42345678 , 52345678

sort_code: 123456

HTTP request

POST https://api.telleroo.com/recipients

Parameter Type Description
Authorization String Your authorization key.

General parameters

Parameter Type Description Optional
name String Name validations are dependant on legal_type selected. Find detailed information here.
currency_code String The recipient’s account currency code.
legal_type String If recipient a person should be PRIVATE. If recipient a business should be BUSINESS.

UK recipient parameters

Parameter Type Description
account_no String The recipient’s account number.
sort_code String The recipient’s account sort code.

Euro recipient parameters

Parameter Type Description
iban String The recipient’s IBAN.
bic String The recipient’s BIC.

Recipient Validation Errors

When PRIVATE recipient name only has first name

curl "http://api.telleroo.com/recipients" \
  -d name="Sam" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
    "error": {
        "name": [
            "must contain full name of recipient. If you are sending to a business, please use \"business\" legal type"
        ]
    }
}

When PRIVATE recipient contains a special character that’s not allowed

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins!" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
    "error": {
        "name": [
            "can only contain letters, hyphens, underscores, curved brackets, single quotes, asterisks, commas and dots"
        ]
    }
}

When PRIVATE recipient contains 1 letter for each word

curl "http://api.telleroo.com/recipients" \
  -d name="S J" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
    "error": {
        "name": [
            "words must be at least 2 letters long"
        ]
    }
}

When a sort code and account number format and length incorrect

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "account_no": [
      "is not a number",
      "is the wrong length (should be 8 characters)"
    ],
    "sort_code": [
      "is not a number",
      "is the wrong length (should be 6 characters)"
    ]
  }
}

When a sort code is not valid

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="112233" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "sort_code": [
      "could not be validated (please enter a valid sort code)"
    ]
  }
}

When a account number and sort code do not match

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="11223344" \
  -d sort_code="112233" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "base": [
      "account number and sort code do not match"
    ]
  }
}

When a IBAN and BIC length incorrect

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="123a" \
  -d bic="123a" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "iban": [
      "is too short (minimum is 15 characters)"
    ],
    "bic": [
      "length must be 8 or 11"
    ]
  }
}

When a IBAN is not valid

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="111222333444555" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "iban": [
      "Please enter valid IBAN number"
    ]
  }
}

When a IBAN and BIC do not match

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="111222333444555" \
  -d bic="12345678" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST
{
  "error": {
    "iban": [
      "This IBAN is for the wrong country"
    ]
  }
}

When a recipient bank details are not valid we return the following errors. You can trigger these errors in sandbox using the details below:

Invalid sort code

sort_code: 223344

Account Number and Sort code do not match

account_no: 11111111

sort_code: 522127

Invalid IBAN

iban: 111222333444555

Recipient Deletion

curl "http://api.telleroo.com/recipients/4314d582-491c-443d-84f4-51324dfb26b5aec" \
  -H Authorization: "your_auth_token" \
  -X DELETE

The above command returns JSON structured like this:

no content

HTTP request

DELETE https://api.telleroo.com/recipients/{id}

Parameter Type Description
Authorization String Your authorization key.

Url parameters

Parameter Type Description
id String The recipient’s unique ID.

Bank Transfers

curl "https://api.telleroo.com/adhoc_bank_transfers" \
  -H Authorization="your_auth_token" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d332d604" \
  -d amount=100 \
  -d currency_code="GBP" \
  -d recipient_name="Wayne Rooney" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d reference="PayslipDec16" \
  -d legal_type="BUSINESS" \
  -d tag="Payroll" \
  -d reconciliation="f9q3408rh3" \
  -d idempotent_key="12343" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-02T12:15:22.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "14296335-e230-42ef-8de8-2b7a459026",
    "status": "Preparing Payment",
    "status_info": "Creating payment request.",
    "reconciliation": "f9q3408rh3",
    "reference": "PayslipDec16",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Payroll",
    "end_balance": 2200,
    "idempotent_key": "12343",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

You can create a bank transfer request from a selected account to any bank account. Depending on the currency assigned to your account this creates a faster payment (GBP) or a SEPA direct credit transfer (EUR).

HTTP request

POST https://api.telleroo.com/adhoc_bank_transfers

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
account_id String The source account’s ID.
amount Integer The amount to be transferred in pence/cents (100 equals 1 GBP/EUR).
currency_code String The currency code used for this transaction. Only transaction requests in the same currency of the originating account are allowed.
recipient_name String Name validations are dependant on legal_type selected. Find detailed information here.
account_no/iban Integer The recipient’s bank account number (8-digits) if account currency is GBP. The recipient’s IBAN (max 34-chars) if account currency is EUR.
sort_code/bic Integer The recipient’s sort code (6-digits) if account currency is GBP. The recipient’s BIC (8-chars or 11-chars) if account currency is EUR.
legal_type String If recipient a person should be PRIVATE. If recipient a business should be BUSINESS.
idempotent_key String Unique key for each transaction. optional
reference String External payment reference visible to recipient. optional
tag String Optional field to group payments into custom categories. optional
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id). optional

Bank Transfers to Recipient ID

curl "https://api.telleroo.com/bank_transfers" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d332d604" \
  -d amount=100 \
  -d currency_code="GBP" \
  -d recipient_id="ff17b231-2bc4-485e-967e-231867e15fd6" \
  -d reference="PayslipDec16" \
  -d tag="Payroll" \
  -d reconciliation="f9q3408rh3" \
  -d idempotent_key="2130948" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-02T12:15:22.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "ff17b231-2bc4-485e-967e-231867e15fd6",
    "status": "Preparing Payment",
    "status_info": "Creating payment request",
    "reconciliation": "f9q3408rh3",
    "reference": "PayslipDec16",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Payroll",
    "end_balance": 2100,
    "idempotent_key": "2130948",
    "created_at": "2017-3-08T13:15:32.237Z",
    "updated_at": "2017-3-08T13:15:32.237Z"
  }
}

You can create a bank transfer request from a selected account to a recipient account. Depending on the currency assigned to your account this creates a faster payment (GBP) or a SEPA direct credit transfer (EUR).

HTTP request

POST https://api.telleroo.com/bank_transfers

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
account_id String The source account’s Universally Unique Identifier.
amount Integer The amount to be transferred in pence/cents (100 equals 1 GBP/EUR).
currency_code String The currency code used for this transaction. Only transaction requests in the same currency of the originating account are allowed.
recipient_id String The recipient’s Universally Unique Identifier.
reference String External payment reference visible to recipient. optional
tag String Optional field to group payments into custom categories. optional
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id). optional
idempotent_key String Unique key for each transaction. optional

Bank Transfer Cancelling

curl "http://api.telleroo.com/bank_transfers/842963c5-e230-42ef-8de8-2b7a459026" \
  -H Authorization: "your_auth_token" \
  -X DELETE

The above command returns JSON structured like this:

no content

HTTP request

DELETE https://api.telleroo.com/bank_transfers/{id}

Parameter Type Description
Authorization String Your authorization key.

Url parameters

Parameter Type Description
id String The bank transfer’s unique ID.

Idempotent Key

When a idempotent key is reused on a different bank transfer

curl "https://api.telleroo.com/bank_transfers" \
  -d amount=100 \
  -d recipient_name="Payee name" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d idempotent_key="984q3h8f" \
  -d reference="payout rooney" \
  -d tag="manutd" \
  -d reconciliation="9487r2q8hr" \
  -H Authorization: "your_auth_token" \
  -X POST

To avoid incorrect duplication of bank transfers, we use the idempotent key.

If the same idempotent key gets used twice we will return an error.

{
  "error": {
    "idempotent_key": [
      "has already been taken"
    ]
  }
}

Create User

Create a user to approve transactions

curl "https://api.telleroo.com/users" \
  -d email="sam@test.com"
  -d phone_number_country_code=44 \
  -d phone_number=75473829403 \
  -d password="Str0ng_pa**w0d" \
  -H Authorization: "your_auth_token" \
  -X POST

If you would like authorization to use this endpoint, please get in contact with us

Creates a unapproved user who will receive SMS’s when a transaction approval request is created.

{
    "user": {
        "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
        "email": "sam@test.com",
        "status": "initialized"
    }
}

Single User

Returns a single User

curl "https://api.telleroo.com/users/b357b7fe-2ea5-49a7-828c-76a0850d771d" \
  -H Authorization: "your_auth_token" \
  -X GET

If you would like authorization to use this endpoint, please get in contact with us

Get a single transaction approval request.

The above command returns JSON structured like this:

{
    "user": {
        "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
        "email": "sam@test.com",
        "status": "initialized"
    }
}

Users list

Returns all users

curl "https://api.telleroo.com/users" \
  -H Authorization: "your_auth_token" \
  -X GET

If you would like authorization to use this endpoint, please get in contact with us

Get all users and there current status.

The above command returns JSON structured like this:

{
    "users": [
        {
            "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
            "email": "sam@test.com",
            "status": "initialized"
        },
        {
            "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
            "email": "ben@test.com",
            "status": "approved"
        }
    ]
}

User Deletion

curl "http://api.telleroo.com/users/b357b7fe-2ea5-49a7-828c-76a0850d771d" \
  -H Authorization: "your_auth_token" \
  -X DELETE

If you would like authorization to use this endpoint, please get in contact with us

Deletes a user.

The above command returns JSON structured like this:

no content

Transactions List

curl "https://api.telleroo.com/transactions" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d3d60264" \
  -d start_date="2016-10-02" \
  -d end_date="2016-10-02" \
  -d status="preparing_payment" \
  -d page=1 \
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "transactions": [
    {
      "id": "842963c5-e230-42ef-8de8-2b7a459026",
      "processed_at": "2016-12-01T12:15:23.486Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": "1000",
      "sender_name": "Daryl Oates",
      "status": "Preparing Payment",
      "status_info": "Creating payment request",
      "reconciliation": "3456yujk",
      "reference": "Funding Telleroo",
      "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
      "tag": "Sponsoring",
      "end_balance": 1560,
      "created_at": "2016-12-01T12:15:22.486Z",
      "updated_at": "2016-12-01T12:15:22.486Z"
    },
    {
      "id": "842963c5-e230-42ef-8de8-2b7a459026",
      "processed_at": "2016-12-01T12:15:23.486Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": "100",
      "recipient_id": "122963c5-e230-42ef-8de8-327459026",
      "status": "Preparing Payment",
      "status_info": "Creating payment request",
      "reconciliation": "f9q3408rh3",
      "reference": "Withdrawal Telleroo",
      "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
      "tag": "Manutd",
      "end_balance": 1460,
      "idempotent_key": "6130348",
      "created_at": "2016-12-01T12:15:22.486Z",
      "updated_at": "2016-12-01T12:15:22.486Z"
    }
  ]
}

Specify start_date and end_date to get a list of all transactions including credits and debits for the selected bank account. This also returns failed transfers.

HTTP request

GET https://api.telleroo.com/transactions

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
account_id String The account’s Universally Unique Identifier.
start_date String Enter starting date (FORMAT: YYYY-MM-DD).
end_date String Enter end date (FORMAT: YYYY-MM-DD).
status String Filter by payment statuses. Find status keys in table below. optional
page Integer Page you want to return. Pagination index starts at 1. optional

Status Filter Keys

Status Key to Use
Payment Sent payment_sent
Preparing Payment preparing_payment
On Hold on_hold
Waiting for approval waiting_for_approval
Waiting for funds waiting_for_funds
Looking into it looking_into_it
Credit credited
Failed failed
Cancelled cancelled

Response Properties

Properties Description
id Universally Unique Identifier given back after every transfer request.
processed_at Exact time when transfer has been placed.
transaction_type Shows account has been credited or debited.
currency_code Denominated currency used in the transaction.
amount Transaction amount in pence (100 equals 1 GBP/EUR).
recipient_id Third party account holder Universally Unique Identifier if a transaction is a debit.
sender_name Name of the sender if transaction is a credit.
status Real-time status of the transfer request.
status_info Additional info on payment status including failure reason.
reconciliation Optional parameter that can be used to save custom data (e.g. User_id).
reference External payment reference visible to recipient.
account_id Account Universally Unique Identifier that the transaction is associated with.
tag Optional field that can be used to group payments into custom categories.
end_balance End balance in pence or cents after the value is credited/deducted from the account.
idempotent_key Unique key for each transactions.
created_at Exact time when bank transfer request was created.
updated_at Exact time of the last transfer update.

Pagination

curl "https://api.telleroo.com/transactions" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d3d60264" \
  -d start_date="2016-10-02" \
  -d end_date="2016-10-02" \
  -d page=1 \
  -H Authorization: "your_auth_token" \
  -X GET

Transactions use pagination to return 40 objects per request ordered by processed_at date. Use the page parameter to return each page.

Single Transaction

curl "https://api.telleroo.com/transactions/842963c5-e230-42ef-8de8-2b7a459026" \
  -H Authorization: "your_auth_token"
  -X GET

The above command returns JSON structured like this:

{
  "transaction": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-01T12:15:23.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "442663c5-e230-32ef-8de8-1b7a459026",
    "status": "Preparing Payment",
    "status_info": "Creating payment request",
    "reconciliation": "f9q3408rh3",
    "reference": "Withdrawal Telleroo",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Manutd",
    "end_balance": 2200,
    "idempotent_key": "6130348",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

Retrieves a single transaction including the transfer status.

HTTP request

GET https://api.telleroo.com/transactions/{id}

Parameter Type Description
Authorization String Your authorization key.

URL parameters

Parameter Type Description
id String The transaction’s Universally Unique Identifier to retrieve the related transaction details.

Create Company

curl "https://api.telleroo.com/companies" \
-H Authorization="your_auth_token" \
-H content-type="application/json" \
-d first_name="Andrew" \
-d last_name="Thompson" \
-d email="andrew@test.com"
-d company_name="Test Company" \
-d company_type="ltd" \
-d companies_house_number=1234234 \
-d sector="Testing" \
-d business_address="11 London Road, London, E1 LON" \
-d gbp_account=true \
-d eur_account=true \
-d sent_webhook_url="https://webhook.test/test" \
-d error_webhook_url="https://webhook.test/test" \
-d credit_webhook_url="https://webhook.test/test" \
-d token_name="Rspec Token" \
-d webhook_token="Telleroo-test-123" \
-d users:
  {
    email='user_one@test.com' \
    phone_number_country_code=44 \
    phone_number=712345678 \
  }
-d shareholders:
  [
    {
      name="Andrew Benson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
      identity='https://www.example.com/passport.jpg' \
    },
    {
      name="Ben Andreson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    }
  ],
-d directors:
  [
    {
      name="Andrew Benson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    },
    {
      name="Ben Andreson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    }
  ]
  -X POST

If you would like authorization to use this endpoint, please get in contact with us

The above command returns JSON structured like this:

{
  "company": {
    "id": "7ab52fce-93d4-469b-b949-a54265bc8350",
    "name": "Migeroo",
    "email": "admin-miguel@telleroo.com",
    "settings": {
      "sent_webhook_url": "https://requestb.in/xae3j8xa",
      "error_webhook_url": "https://requestb.in/xae3j8xa",
      "credit_webhook_url": "https://requestb.in/xae3j8xa",
      "webhook_token": "Telleroo-test-123"
    },
    "tokens": [
      {
        "name": "Rspec Token",
        "value": "Token-here"
      }
    ]
  }
}

If your interested in this endpoint please get in contact with us to unlock

Setup company for verification.

HTTP request

GET https://api.telleroo.com/companies

Parameter Type Description
Authorization String Your authorization key.

Main parameters

Parameter Type Description
first_name String First name of Main User
last_name String Last name of Main User
email String Email address of Main User
company_name String Name of company
company_type String Company type eg. Ltd
companies_house_number String Company type eg. Ltd
sector String Company sector e.g catering
business_address String Company registered address
gbp_account Boolean Setup GBP account
eur_account Boolean Setup EUR account
sent_webhook_url String URL of sent webhook
error_webhook_url String URL of error webhook
credit_webhook_url String URL of credit webhook
token_name String Name of Auth token
webhook_token String More info here

User parameters

Admin user for account.

Parameter Type Description
email String Admin user email
phone_number_country_code String Country code of phone (44 or 1)
phone_number String Phone number of admin user

Shareholders parameters

Information for shareholders who own more than 25% of the company.

Must provide passport copy of one shareholder

Parameter Type Description
name String Full name
dob String Date of Birth (DD/MM/YYYY)
residence String City of residence
identity String URL to driving licence or passport

Director parameters

Information for directors who own more than 25% of the company.

Parameter Type Description
name String Full name
dob String Date of Birth (DD/MM/YYYY)
residence String City of residence

Sandbox API Endpoints

Endpoints that are only available on sandbox.

Send Bank Transfer

curl "https://api.telleroo.com/transaction_send" \
  -H Authorization="your_auth_token" \
  -d id="b58584f7-7924-4022-bbb5-9ab3cb36ae3b" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
      "id": "b58584f7-7924-4022-bbb5-9ab3cb36ae3b",
      "processed_at": "2018-06-14T14:37:28Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": 100,
      "recipient_id": "b577ebe2-b3ca-48cd-8a74-b36359ad1883",
      "status": "Payment Sent",
      "status_info": "Your payment has been sent to the recipients bank",
      "reconciliation": null,
      "reference": null,
      "account_id": "15fa5095-d3cb-4df5-b5ac-87f14c4a4327",
      "tag": null,
      "end_balance": 4325596,
      "idempotent_key": null,
      "created_at": "2018-06-14T14:37:28Z",
      "updated_at": "2018-06-14T14:37:38Z"
  }
}

This endpoint allows you to move a transaction from preparing payment to sent on sandbox.

HTTP request

POST https://api.telleroo.com/transaction_send

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
id String Transaction Id

Fail Bank Transfer

curl "https://api.telleroo.com/transaction_fail" \
  -H Authorization="your_auth_token" \
  -d id="b58584f7-7924-4022-bbb5-9ab3cb36ae3b" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
      "id": "b58584f7-7924-4022-bbb5-9ab3cb36ae3b",
      "processed_at": "2018-06-14T14:37:28Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": 100,
      "recipient_id": "bf57ebe2-b3ca-48cd-8a74-b36359ad1883",
      "status": "Failed",
      "status_info": "Transaction failed",
      "reconciliation": null,
      "reference": null,
      "account_id": "15fa5095-d3cb-4df5-b5ac-87f14c4a4327",
      "tag": null,
      "end_balance": null,
      "idempotent_key": null,
      "created_at": "2018-06-14T14:37:28Z",
      "updated_at": "2018-06-14T14:38:50Z"
  }
}

This endpoint allows you to move a transaction from payment sent to failed on sandbox.

HTTP request

POST https://api.telleroo.com/transaction_fail

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
id String Transaction Id

2-Step Approvals

This allows you to integrate 2-step sms verification for payments into your software.

Approval workflow:

  1. Request transaction approval

    This returns all payments under awaiting approval and triggers a sms to authorised users.

  2. Receive SMS

    Sends sms with either bulk amount of all payments under awaiting approval or of individual payments to authoriser including approval code.

  3. Approve payments

    Extract returned approval id and paste received sms code to the transaction approval response endpoint.

Approval Request List

curl "https://api.telleroo.com/approval_requests" \
  -d type="transaction"
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
    "transaction_approvals": [
        {
            "id": "e900fb11-f18f-435b-9e5b-aff0af784191",
            "status": "requested",
            "type": "TransactionApproval",
            "target_id": null,
            "end_time": "2018-09-11T18:57:34Z",
            "created_at": "2018-09-11T15:10:04Z",
            "updated_at": "2018-09-11T15:10:04Z"
        },
        {
            "id": "e900fb11-f18f-435b-9e5b-aff0af784192",
            "status": "requested",
            "type": "TransactionApproval",
            "target_id": null,
            "end_time": "2018-09-11T18:57:34Z",
            "created_at": "2018-09-11T15:10:04Z",
            "updated_at": "2018-09-11T15:10:04Z"
        }
    ]
}

List of transactions or user approvals that have been requested.

HTTP request

GET https://api.telleroo.com/approval_requests

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
type String The approval type must be transaction or user

Request Bulk Approval

curl "https://api.telleroo.com/approval_requests" \
  -d type="transaction"
  -d end_time="2017-10-30T18:57:34" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "requested",
        "end_time": "2017-10-30T18:57:34Z",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            },
            {
                "id": "9f2ef1a4-49f8-4d70-98ab-f6c2b4d3a31f",
                "amount": 129
            },
            {
                "id": "eeae9b3a-d772-4add-b573-6588eb9becb0",
                "amount": 5000
            },
            {
                "id": "29808cfc-a70e-49bc-bff0-0f3fccc7bc43",
                "amount": 9
            }
        ]
    }
}

Requesting approval for transactions created before a certain date/time

This returns all payments under awaiting approval before a certain point in time and triggers a sms to authorised users containing then approval code and the total amount to be approved.

HTTP request

POST https://api.telleroo.com/approval_requests

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
type String The approval type. On this case always `transaction
end_time String Point in time (FORMAT: yyyy-mm-ddTh:m:s).

Request Single Approval

curl "https://api.telleroo.com/approval_requests" \
  -d type="transaction"
  -d target_id="ca12635e-3c33-421b-ad80-86923fb0cf5c" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "requested",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z",
        "target_id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            }
        ]
    }
}

Requesting approval for a single specific transaction

Sending a transaction approval request will SMS all users who are allowed to approve transactions an approval code and the amount being approved.

When requested it will return a summary of the approval request including the transaction you’ve requested to approve.

HTTP request

POST https://api.telleroo.com/approval_requests

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
type String The approval type. On this case always transaction
target_id String The transaction id

Approve Request

curl "https://api.telleroo.com/approval_responses" \
  -d id="5e03d7e5-0b37-4648-8c01-3f658bfcdc3c" \
  -d code="123456" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "approved",
        "end_time": "2017-10-30T18:57:34Z",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T17:06:45Z",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            },
            {
                "id": "9f2ef1a4-49f8-4d70-98ab-f6c2b4d3a31f",
                "amount": 129
            },
            {
                "id": "eeae9b3a-d772-4add-b573-6588eb9becb0",
                "amount": 5000
            },
            {
                "id": "29808cfc-a70e-49bc-bff0-0f3fccc7bc43",
                "amount": 9
            }
        ]
    }
}

Sending approval code with approval ID

To approve the requested transactions we expect you to enter the code sent by SMS and the approval ID.

You are only allowed to try three different codes before the approval request is rejected.

HTTP request

POST https://api.telleroo.com/approval_responses

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
id String The approval request id.
code String The approval code included in the SMS.

User Approval Request

Requests approval for a user creation

curl "https://api.telleroo.com/approval_requests" \
  -d type="user"
  -d target_id="e1042121-c25a-41b5-9181-db30c4d7957d" \
  -H Authorization: "your_auth_token" \
  -X POST

Only required if token used requires users to be approved

Sending a user approval request will SMS all users who are allowed to approve users a code.

When requested it will return a summary of the approval request including the user you’ve requested to approve.

{
    "user_approval": {
        "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
        "status": "requested",
        "target_id": "e1042121-c25a-41b5-9181-db30c4d7957d",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z"
    }
}

User Approval Response

Sending approval code with approval ID

curl "https://api.telleroo.com/approval_responses" \
  -d id="2a5ac05a-4d76-4824-a5c4-40be37fb2430" \
  -d code="123456" \
  -H Authorization: "your_auth_token" \
  -X POST

To approve the requested user we expect you to enter the code sent by SMS and the approval ID.

You are only allowed to try three different codes before the approval request is rejected.

{
    "user_approval": {
        "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
        "status": "approved",
        "target_id": "e1042121-c25a-41b5-9181-db30c4d7957d",
        "created_at": "2017-11-14T12:01:25Z",
        "updated_at": "2017-11-14T12:07:53Z"
    }
}

API versions

If no version is selected, the request will default to our latest version. If you want to use a specific version use, Accept in the header.

curl "https://api.telleroo.com/accounts" \
  -H Authorization: "your_auth_token" \
  -H Accept: "application/vnd.telleroo.v1" \
  -X GET

The API version you choose influences the request parameters format and the JSON responses you get.

When we change the API in a non backwards compatible way, we warn you in advance so that you have time to set the version you want to use until you decide to upgrade.

Webhooks

Webhooks are configured on Telleroo dashboard under webhook settings. Click on Update Webhook URLs to save the entered URLs for receiving notifications through webhooks. Telleroo comes with three webhook types, sent, credits and failed transactions. A POST call to the URL you provided will be made when any of the supported events are triggered.

The urls provided must include the protocol (http|https), a hostname (example.com) and optionally a file name (credit.php).

Valid url example: https://example.com/credit

Invalid url example: example.com/credit

Webhook Authenticity Token

In the header of the webhook post you will find your webhook authenticity token:

  "Authenticity-Token":"YOUR-WEBHOOK-TOKEN-HERE"

Your webhook authenticity token is chosen by you, so you can identify that the webhook post is coming from Telleroo by looking at the header.

Webhooks authenticity tokens are configured on Telleroo dashboard under webhook settings.

Credit Notification Webhook

Credit Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "New Credit",
    "transaction_id": "129633c5-a230-32ef-7de8-2b7a459161",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 100,
    "currency_code": "GBP",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "sender_name": "Daryl Oates",
    "reference": "Funding Telleroo",
    "end_balance": 2300,
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

When a credit is received, we will post details to your defined URL.

e.g. When you topup your account, funds arrive trigging the webhook.

Failed Transaction Webhook

Failed Transaction Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Failed Payment",
    "transaction_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 5000,
    "currency_code": "GBP",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Withdrawal Telleroo",
    "tag": "",
    "reconciliation": "",
    "status_info": "Transaction failed",
    "end_balance": 2300,
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

When a payment fails, we will post details to your defined URL.

e.g. A sent payment bounces back, triggering the webhook.

Sent Transaction Webhook

Sent Transaction Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Sent Payment",
    "transaction_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 5000,
    "currency_code": "GBP",
    "recipient_id": "638633c5-d120-15fa-9ee5-7c6a348266",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Withdrawal Telleroo",
    "end_balance": 2300,
    "idempotent_key": "418633c5-1120-45fa-9ee5-1c6a348232",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

When a payment is sent, we will post details to your defined URL.

e.g. A payment is sent from the account, triggering the webhook.

Company Approved Webhook

Company Approved Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Company Approved",
    "company_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "company_name": "Test Company One"
  }
}

This webhook is only available if you have the create company endpoint unlocked

When a company has been approved by our compliance team and is ready to use, the webhook will be sent.

e.g. A requested company is been approved and is ready to use.

Errors

HTTP response codes

The Telleroo API uses conventional HTTP response codes to indicate errors, and includes more detailed information on the exact nature of an error in the HTTP response.

In general, error codes are separated in three different ranges. The 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missing, etc.), and codes in the 5xx range indicate an error on Telleroo’s end (these are rare).

Code Meaning
200 OK – Request successful.
204 No content – When deletion successful no content returned.
422 Unprocessable entity – Your request could not be accepted as invalid parameters used.
404 Not Found – The requested resource or endpoint doesn’t exist.
409 Conflict – When you have already created this resource with the same idempotent key.
429 Too Many Requests – Too many requests hit our API too quickly. We recommend to reducing the number of requests sent.
500, 503, 504 Server Errors – Something went wrong on our end. Please try again later.

Authentication errors

Errors related to authentication are standard errors but also contain extra information. Specifically, they contain the error key with the following value:

invalid credentials The supplied auth_token is invalid or has expired.