NAV
Curl

Introduction

Welcome to the Tide API. You can use our API to access Tide API endpoints.

We have language bindings in Curl. You can view code examples in the dark area to the right.

Authentication

Tide implements OAuth 2 to authenticate requests.

OAuth 2

Overview

Tide uses Access Tokens to allow access to the API via OAuth 2. You can obtain an OAuth 2 Access Token by navigating to the below url, either in the web application or through an in-app browser window:

https://api.tide.co/tide-backend/oauth/index.html?redirect_url={url}&client_id={unique_id}

Parameter Type Description
redirect_uri query Required Fully qualified URL to which Authorisation Grants will be delivered to. Grants will be delivered only on successful authorisation by resource owner.
client_id query Required Unique identifier for the requester.

Once the page loads, the user needs to enter the unique email address, which is registered on their Tide account.

Authorisation Grants

On successful authentication Tide will redirect the client to the URI specified in redirect_uri, which was passed into the request above.

An Authorisation Grant Code will be included in the redirect URI. You can use the Authorisation Grant Code to obtain an Access Token.

Authorisation Grants can only be used once off by the client, once used they are expired and cannot be used to issue new Access Tokens.

redirect_url?code={Grant_Code}

Parameter Type Description
code query Optional Authorisation Grant Code which can be exchanged for an Access Token.

Authorisation Grant for Access Token

curl " https://api.tide.co/tide-backend/rest/api/v1/oauth2/tokens?code=HgYp2132jPfTYt332" 

This endpoint can be used to exchange Authorisation Grants for Access Tokens.

HTTP Request

GET https://api.tide.co/tide-backend/rest/api/v1/oauth2/tokens?code={Grant_Code}

Parameter Type Description
code query Required Grant Code received through redirect URL.

Refresh Token for Access Token

curl " https://api.tide.co/tide-backend/rest/api/v1/oauth2/tokens?refresh_token=JKds21ds2jPfdUt332" 

This endpoint can be used to exchange Refresh Tokens for Access Tokens.

HTTP Request

GET https://api.tide.co/tide-backend/rest/api/v1/oauth2/tokens?refresh_token={Refresh_Token}

Parameter Type Description
refresh_token query Required Refresh Token a long living token issued with every Access Token.

Authenticated requests with Access Token

Tide expects the Access Token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {AccessToken}

Companies

curl "GET https://api.tide.co/tide-backend/rest/api/v1/external/companies" 
-H "Authorization: Bearer {AccessToken}"

Example response

[
  {
    "companyId": 123,
    "number": "07654321",
    "name": "Pipes Plumbing Limited",
    "sicCode": "43220",
    "vatNumber": "GB123456789",
    "tradingName": "Pipes Plumbing",
    "registered": true,
    "isoCreatedOn": "2016-08-12T10:54:18+02:00",
    "isoUpdatedOn": "2016-08-12T10:54:18+02:00"
  }
]

This endpoint retrieves a collection of companies with the user.

User is determined from authorization header.

HTTP Request

GET https://api.tide.co/tide-backend/rest/api/v1/external/companies

Accounts

curl " https://api.tide.co/tide-backend/rest/api/v1/external/companies/0/accounts" 
-H "Authorization: Bearer {AccessToken}"

Example response

[
  {
    "accountId": 456,
    "companyId": 123,
    "accountNumber": "01234567",
    "name": "Primary Tide Account",
    "balance": 2345600,
    "availableBalance": 2345600,
    "currencyCode": "GBP",
    "sortCode": "236972",
    "isoCreatedOn": "2016-08-12T10:54:20+02:00",
    "isoUpdatedOn": "2016-08-12T10:54:20+02:00"
  }
]

This endpoint retrieves a collection of company accounts associated with the user.

User is determined from authorization header.

HTTP Request

GET https://api.tide.co/tide-backend/rest/api/v1/external/companies/{company_id}/accounts

Parameter Type default Description
company_id path - Required Tide company id.

Transactions

curl " https://api.tide.co/tide-backend/rest/api/v1/external/accounts/0/transactions"
-H "Authorization: Bearer {AccessToken}"

Example Response

[
  {
    "transactionId": 789,
    "accountId": 456,
    "amount": -120,
    "type": "PYO",
    "txnRef": "T99900112349876",
    "isoTransactionDateTime": "2016-08-12T10:54:20+02:00",
    "isoAppliedDateTime": "2016-08-12T11:00:00+02:00",
    "isoClearedDateTime": "2016-08-12T18:42:21+02:00",
    "maskedPan": null,
    "status": "cleared",
    "description": "Bloggs Supplies ref:inv0123",
    "isoCreatedOn": "2016-08-12T11:00:00+02:00",
    "isoUpdatedOn": "2016-08-12T18:42:21+02:00",
    "categoryId": 345,
    "categoryName": "Equipment",
    "categoryType": "expenditure"
  }
]

This endpoint retrieves a collection of an account’s transactions.

HTTP Request

GET https://api.tide.co/tide-backend/rest/api/v1/external/accounts/{account_id}/transactions

Parameter Type Default Description
account_id path - Required Tide account id.

Transaction Types

Following is a list of balance affecting transaction types currently accessible through the API.

Type Description
PYIFaster Payment In
PYI_REVFaster Payment In Reversal
PYOFaster Payment Out
TRDInter-Account Transfer Out
TRCInter-Account Transfer In
REDCard Payment Out
RED_REVCard Payment Reversal
WTHCash Withdrawal
WTH_REVCash Withdrawal Reversal
REFRefund
REF_REVRefund Reversal
FEEFee
TOPTide Credit
TOP_REVTide Credit Reversal

There are currently some other events that may show as zero value transactions but can safely be ignored. Tide is working on some amendments to the API which will correct this.

Errors

The TIDE API uses the following HTTP error codes:

Error Code Meaning
400 Bad Request – Invalid input request.
401 Unauthorised – Your Access Token has expired, is invalid or has not been provided.
403 Forbidden – You don’t have required permissions to access requested resources.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
406 Not Acceptable – You requested a format that isn’t JSON.
429 Too Many Requests – You have exceeded our limit on the number of requests that can be made per hour.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for system maintenance. Please try again later.