Currency Converter REST API (JSON & XML) Documentation

Currency Converter API Documentation

This API is part of our FOREX REFERENCE SUITE service

1. What is the Currency Converter API?


This API provides automation capability for converting one currency into another with our Forex Reference Suite service.
It provides an easy way to convert currencies using the latest available conversion rates data.

Designed as a single call REST API, it provides a quick way to integrate accurate currency conversion functionality in your software.
With a single GET or POST request you may calculate any amount from over 23000 currency pairs with accurate up to date exchange rates.

2. Currency Converter API Requests



To perform a currency conversion, our API requires a minimal amount of input parameters. The accepted parameters by the API are listed in the table below:

Field Name Length Type Description
from 3 String 3 letter ISO currency code from which you are converting the amount( usd,eur,gbp ... etc )
to 3 String The ISO code of the destination currency you need to convert into ( usd,eur,gbp ... etc ). Full list of supported currencies
from 3 String 3 letter ISO currency code from which you are converting the amount( usd,eur,gbp ... etc )
amount 10 Integer The amount to convert.
format 5 String Format of the response XML and JSON supported.

*To obtain an API key, please contact us at contact@iban.com or purchase a subscription at our order page

EXAMPLE – Convert 120 USD to EUR
Feel free to use the sample code below to test the API in the most common programming languages.

curl "https://api.iban.com/clients/api/currency/convert/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d from=USD
	-d to=EUR
	-d amount=120
<?php
$curl = curl_init();

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'from'   => 'USD',
	'to' => 'EUR',
	'amount' => 120
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/currency/convert/',
	CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $post
));

$output = curl_exec($curl);
$result = json_decode($output);

print_r($result);

curl_close($curl);
?>
require 'net/http'

uri = URI('https://api.iban.com/clients/api/currency/convert/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","from" => "USD","to" => "EUR", "amount" => 120)

puts res.body
import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','from':'USD','to':'EUR','amount':'120'}

response = requests.post('https://api.iban.com/clients/api/currency/convert/',post_data)
print(response.text)
use LWP::UserAgent;

my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/currency/convert/";

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $from = 'USD';
my $to = 'EUR';
my $amount = 120;


my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');

my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&from=' . $from . '&to=' . $to . '&amount=' . $amount;

$req->content($post_data);

my $resp = $ua->request($req);

if ( $resp->is_success ) {
    my $message = $resp->decoded_content;
	print $message;
}

JAVA

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;


public class ibanapi {

	private final String USER_AGENT = "API Client/1.0";

	public static void main(String[] args) throws Exception {

		ibanapi http = new ibanapi();

		
		System.out.println("\nTesting API - Send API POST request");
		http.sendPost();

	}

	// HTTP POST request
	private void sendPost() throws Exception {

		String url = "https://api.iban.com/clients/api/currency/convert/";
		URL obj = new URL(url);
		HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();

		//add reuqest header
		con.setRequestMethod("POST");
		con.setRequestProperty("User-Agent", USER_AGENT);
		con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");

		String urlParameters = "api_key=[YOUR_API_KEY]&format=json&from=USD&to=EUR&amount=120";

		// Send post request
		con.setDoOutput(true);
		DataOutputStream wr = new DataOutputStream(con.getOutputStream());
		wr.writeBytes(urlParameters);
		wr.flush();
		wr.close();

		int responseCode = con.getResponseCode();
		System.out.println("\nSending 'POST' request to URL : " + url);
		System.out.println("Post parameters : " + urlParameters);
		System.out.println("Response Code : " + responseCode);

		BufferedReader in = new BufferedReader(
		new InputStreamReader(con.getInputStream()));
		String inputLine;
		StringBuffer response = new StringBuffer();

		while ((inputLine = in.readLine()) != null) {
			response.append(inputLine);
		}
		in.close();

		//print result
		System.out.println(response.toString());

	}

}

.NET

public static void Main(string[] args)
		{						
			var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/currency/convert/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&from=USD";
			 postData += "&to=EUR";
			 postData += "&amount=120";
			 
			var data = Encoding.ASCII.GetBytes(postData);
			 
			request.Method = "POST";
			request.ContentType = "application/x-www-form-urlencoded";
			request.ContentLength = data.Length;
			 
			using (var stream = request.GetRequestStream())
			{
			 stream.Write(data, 0, data.Length);
			}
			 
			var response = (HttpWebResponse)request.GetResponse();
			 
			var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
			
			Console.WriteLine(responseString);
			
			Console.Write("Press any key to continue . . . ");
			Console.ReadKey(true);
		}

NODE

var request = require('request');

var headers = {
    'User-Agent':       'CURRENCY CONVERTER API Client/0.0.1',
    'Content-Type':     'application/x-www-form-urlencoded'
}

var options = {
    url: 'https://api.iban.com/clients/api/currency/convert/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'from': 'USD', 'to': 'EUR', 'amount': 120}
}

request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
     
		var data = JSON.parse(body);

		console.log(data.errors);
		
		
		console.log("Rate Updated: " + data.time);
		console.log("Conversion Rate: " + data.rate)
		console.log("120 USD equals " + data.convert_result + " EUR");
		
    }
})


An example usage of the Currency Convert API with a GET request can be found below:

https://api.iban.com/clients/api/currency/convert/?api_key=key&format=xml&from=USD&to=EUR&amount=120

Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format. You can find an sample response in the next section “API Response Structure”

3. Currency Rates API Response

The API response default format is in JSON format ( XML format is also supported ). It is simplified and structured for easy access to all elements:

{  
   "time":"03-21-2019 14:20:02",
   "timestamp":1553178002,
   "from":"USD",
   "to":"BGN",
   "amount":"12.50",
   "rate":1.718,
   "convert_result":21.475
}


A detailed description of the response object fields returned can be seen in the table below:

Field Name Length Type Description
time 19 String This is the time of the latest update of the rates data from our data sources. This field is in human readable format.
timestamp 10 Integer The same time of the latest update of the rates data as 'time'. This field is in Unix Time format
from 3 String The currency ISO code of the currency from which the amount is converted. This is the value submitted by the client to the API.
to 3 String The currency ISO code of the currency to which the amount is converted. This is the value submitted by the client to the API.
amount 10 Integer The amount of currency units being converted. This is the value submitted by the client to the API.
rate 10 Float The conversion rate which was used for the currency conversion.
convert_result 10 Float The result of the conversion.

4. Supported Currencies

This is a list of the supported base currencies which can be submitted to the Exchange Convert API.

Currency CodeNumberCurrency NameRegion
AED784United Arab Emirates DirhamUNITED ARAB EMIRATES
AFN971AfghaniAFGHANISTAN
ALL008Albanian LekALBANIA
AMD051Armenian DramARMENIA
ANG532Netherlands Antillean GuilderCURACAO
AOA973Angolan KwanzaANGOLA
ARS032Argentine PesoARGENTINA
AUD036Australian DollarAUSTRALIA
AWG533Aruban FlorinARUBA
AZN944Azerbaijanian ManatAZERBAIJAN
BAM977Convertible MarkBOSNIA AND HERZEGOVINA
BBD052Barbados DollarBARBADOS
BDT050Bangladeshi TakaBANGLADESH
BGN975Bulgarian LevBULGARIA
BHD048Bahraini DinarBAHRAIN
BIF108Burundi FrancBURUNDI
BMD060Bermudian DollarBERMUDA
BND096Brunei DollarBRUNEI DARUSSALAM
BOB068BolivianoBOLIVIA
BRL986Brazilian RealBRAZIL
BSD044Bahamian DollarBAHAMAS (THE)
BTN064Bhutanese NgultrumBHUTAN
BWP072Botswanan PulaBOTSWANA
BYR974Belarussian RubleBELARUS
BZD084Belize DollarBELIZE
CAD124Canadian DollarCANADA
CDF976Congolese FrancCONGO
CHF756Swiss FrancSWITZERLAND
CLP152Chilean PesoCHILE
CNY156Yuan RenminbiCHINA
COP170Colombian PesoCOLOMBIA
CRC188Costa Rican ColonCOSTA RICA
CUP192Cuban PesoCUBA
CVE132Cabo Verde EscudoCABO VERDE
CZK203Czech KorunaCZECH REPUBLIC (THE)
DJF262Djibouti FrancDJIBOUTI
DKK208Danish KroneDENMARK
DOP214Dominican PesoDOMINICAN REPUBLIC (THE)
DZD012Algerian DinarALGERIA
EGP818Egyptian PoundEGYPT
ERN232Eritrean NakfaERITREA
ETB230Ethiopian BirrETHIOPIA
EUR978EuroEUROPEAN UNION
FJD242Fiji DollarFIJI
FKP238Falkland Islands PoundFALKLAND ISLANDS
GBP826Pound SterlingGUERNSEY
GEL981Georgian LariGEORGIA
GHS936Ghana CediGHANA
GIP292Gibraltar PoundGIBRALTAR
GMD270Gambian DalasiGAMBIA (THE)
GNF324Guinea FrancGUINEA
GTQ320Guatemalan QuetzalGUATEMALA
GYD328Guyana DollarGUYANA
HKD344Hong Kong DollarHONG KONG
HNL340Honduran LempiraHONDURAS
HRK191Croatian KunaCROATIA
HTG332Haitian GourdeHAITI
HUF348Hungarian ForintHUNGARY
IDR360Indonesian RupiahINDONESIA
ILS376New Israeli SheqelISRAEL
INR356Indian RupeeINDIA
IQD368Iraqi DinarIRAQ
IRR364Iranian RialIRAN (ISLAMIC REPUBLIC OF)
ISK352Iceland KronaICELAND
JMD388Jamaican DollarJAMAICA
JOD400Jordanian DinarJORDAN
JPY392Japanese YenJAPAN
KES404Kenyan ShillingKENYA
KGS417Kyrgystani SomKYRGYZSTAN
KHR116Cambodian RielCAMBODIA
KMF174Comoro FrancCOMOROS (THE)
KPW408North Korean WonKOREA (THE DEMOCRATIC PEOPLE'S REPUBLIC OF)
KRW410South Korean WonKOREA (THE REPUBLIC OF)
KWD414Kuwaiti DinarKUWAIT
KYD136Cayman Islands DollarCAYMAN ISLANDS (THE)
KZT398Kazakhstani TengeKAZAKHSTAN
LAK418Laotian KipLAO PEOPLE'S DEMOCRATIC REPUBLIC (THE)
LBP422Lebanese PoundLEBANON
LKR144Sri Lanka RupeeSRI LANKA
LRD430Liberian DollarLIBERIA
LSL426Lesotho LotiLESOTHO
LYD434Libyan DinarLIBYA
MAD504Moroccan DirhamMOROCCO
MDL498Moldovan LeuMOLDOVA (THE REPUBLIC OF)
MGA969Malagasy AriaryMADAGASCAR
MKD807Macedonian DenarMACEDONIA
MMK104Myanma KyatMYANMAR
MNT496Mongolian TugrikMONGOLIA
MOP446Macanese PatacaMACAO
MUR480Mauritius RupeeMAURITIUS
MVR462Maldivian RufiyaaMALDIVES
MWK454Malawian KwachaMALAWI
MXN484Mexican PesoMEXICO
MYR458Malaysian RinggitMALAYSIA
MZN943Mozambique MeticalMOZAMBIQUE
NAD516Namibia DollarNAMIBIA
NGN566Nigerian NairaNIGERIA
NIO558Cordoba OroNICARAGUA
NOK578Norwegian KroneNORWAY
NPR524Nepalese RupeeNEPAL
NZD554New Zealand DollarNEW ZEALAND
OMR512Rial OmaniOMAN
PAB590Panamanian BalboaPANAMA
PEN604Peruvian Nuevo SolPERU
PGK598Papua KinaPAPUA NEW GUINEA
PHP608Philippine PesoPHILIPPINES (THE)
PKR586Pakistan RupeePAKISTAN
PLN985Polish ZlotyPOLAND
PYG600Paraguayan GuaraniPARAGUAY
QAR634Qatari RialQATAR
RON946Romanian LeuROMANIA
RSD941Serbian DinarSERBIA
RUB643Russian RubleRUSSIAN FEDERATION (THE)
RWF646Rwanda FrancRWANDA
SAR682Saudi RiyalSAUDI ARABIA
SBD090Solomon Islands DollarSOLOMON ISLANDS
SCR690Seychelles RupeeSEYCHELLES
SDG938Sudanese PoundSUDAN (THE)
SEK752Swedish KronaSWEDEN
SGD702Singapore DollarSINGAPORE
SHP654Saint Helena PoundSAINT HELENA, ASCENSION AND TRISTAN DA CUNHA
SLL694LeoneSIERRA LEONE
SOS706Somali ShillingSOMALIA
SRD968Surinam DollarSURINAME
SVC222El Salvador ColonEL SALVADOR
SYP760Syrian PoundSYRIAN ARAB REPUBLIC
SZL748Swazi LilangeniSWAZILAND
THB764Thai BahtTHAILAND
TJS972Tajikistani SomoniTAJIKISTAN
TMT934Turkmenistan New ManatTURKMENISTAN
TND788Tunisian DinarTUNISIA
TOP776Tongan PaʻangaTONGA
TRY949Turkish LiraTURKEY
TTD780Trinidad and Tobago DollarTRINIDAD AND TOBAGO
TWD901New Taiwan DollarTAIWAN (PROVINCE OF CHINA)
TZS834Tanzanian ShillingTANZANIA, UNITED REPUBLIC OF
UAH980Ukrainian HryvniaUKRAINE
UGX800Uganda ShillingUGANDA
USD840US DollarUNITED STATES OF AMERICA
UYU858Peso UruguayoURUGUAY
UZS860Uzbekistan SumUZBEKISTAN
VEF937Venezuelan BolivarVENEZUELA (BOLIVARIAN REPUBLIC OF)
VND704Vietnamese DongVIET NAM
VUV548Vanuatu VatuVANUATU
WST882Samoan TalaSAMOA
XAF950CFA Franc BEACCENTRAL AFRICAN
XCD951East Caribbean DollarEASTERN CARIBBEAN STATES
XDR960SDR (Special Drawing Right)INTERNATIONAL MONETARY FUND (IMF)
XOF952CFA Franc BCEAOWEST AFRICAN
XPF953CFP FrancFRENCH COLONIES OF THE PACIFIC
YER886Yemeni RialYEMEN
ZAR710South African RandSOUTH AFRICA
ZMW967Zambian KwachaZAMBIA
ZWL932Zimbabwe DollarZIMBABWE

5. Currency Convert API errors

Upon an error, the API will return one of the following 'error' responses.

Status Code Type Description Solution
401 Account Error API Key is invalid You need to supply a valid API key. Your API key can be found in your Client Area -> API Access section.
402 Account Error Subscription expired You need to renew your membership. This can be done from your Client Area -> My Services section.
406 Account Error No queries available Your account ran out of available credits. You need to refill your account by purchasing a new package.
403 Account Error You have no access to this API Your account has no access to this service, you need to purchase a plan for this service from your Client Area -> Purchase Plans section.
405 Account Error IP Address not allowed You had enabled the IP restriction in your Client Area -> Account -> Security Section. You need to allow the IP address of the computer/server making the request in your access list.
407 Input Validation Failed FROM currency not supported You have submitted an invalid currency code as an input parameter. The supported currencies are available above in Section 4: Supported Currencies
408 Input Validation Failed TO currency not supported You have submitted an invalid currency code as an input parameter. The supported currencies are available above in Section 4: Supported Currencies
409 Input Validation Failed Invalid amount You have submitted an invalid amount for conversion. Accepted values are 1 to 99999999999
400 Input Validation Failed Bad Request ( Missing required parameters: api_key, currency ) You have not submitted all parameters required for retrieving currency exchange rate data.
500 Server Error Internal Server Error. Contact Support. An unexpected error occurred in our system. This error is caused by a problem on our end. Please contact our support if you encounter this error.