Adaco Exchange Rate API Guide

Introduction

This API enables you to create and update corporate exchange rates in one or more properties within a customer's Adaco instance.

This API receives POST requests. If you need Fourth to instead fetch the data, you will need our Fourth Connect team to create an interface between this API and the relevant other data source (or API). Customers can request this by contacting their Fourth customer success manager.

Quick Facts

Integration type HTTP REST with JSON
Authentication Basic Authentication
Availability Purchase to Pay and Inventory - Hotel customers
Testing Test environment is available on request
More information See the Reference 

Get Access

Before integrating, you’ll need to set up a new user account in Fourth with access rights to the API. 

Requests to the ExchangeRates resource is not restricted by property. This enables you to create and update exchange rates for properties in which the user account is not present.

Step 1: create a user group

Create a user group for accessing the API within one of the Fourth properties — we recommend the central purchasing property where there is one.

For security, we also recommend that you limit the user group to access to just the “Exchange Rate API”. The setting for this is within the user group's Property > API Access sub-section. The group only needs the Edit access right selected for the Exchange Rate API.

Screenshot showing settings location

Step 2: create a user account

In the same property, create a user account. Assign it to the API user group.

Updating by property

To update an exchange rate for all properties at once, leave the AdacoProperties array blank:

  {
    "AdacoProperties": [ ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  }

To update specific properties, include their property number (or property identifier) in the AdacoProperties array. You can find these values in the Fourth UI. 

Property number in Adaco UI

Duplicates in the request

Your request can include multiple updates for the same currency exchange and properties. The updates are applied in read order. For example, this request sets the exchange rate for USD to EUR for all properties, then for just property 121 updates this rate:

  {
    "AdacoProperties": [ ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  },
  {
    "AdacoProperties": [ "121" ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.6
   }

Currency conversion

Fourth converts the FromCurrency to the ToCurrency using the supplied Rate.

For example:

"FromCurrency": "EUR", 
"ToCurrency": "USD", 
"Rate": 1.25

Would result in 100 euros being converted to 125 US dollars.

However, once received, the exchange rate you provide is also used to convert currency in the opposite direction. This means that if you provide an EUR to USD conversion, this also automatically creates the USD to EUR rate (in this example, to 0.80).

You cannot have separate exchange rates for the different directions; if you provide both directions, then value of the last received exchange rate is used for to calculate both directions.

Request header

For all requests, you must provide your authentication details using Basic authentication in the header. Example header:

GET /{customerName}Service/WebApi/ExchangeRates  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Field Description
Authorization Your Exchange Rate API username and password, separated by a colon, and then base64 encoded. Your ID and password are case-sensitive. 
Content-Type The data format you are using for POST request. Options are: application/json, text/json.

Resources path

The path for ExchangeRates requests is:

<ROOT>/{customerName}Service/WebApi/ExchangeRates

You need to put your customerName in the URL path — this is the same name in the URL that you currently use to log into Fourth Purchase to Pay and Inventory. You also need to add "Service" to the name; e.g. "acmeService".

Response to requests

Successful requests

Successfully submitted requests receive an HTTP 200 OK response. The response body contains an object that mirrors your original request's body, but with an additional status value. You must use this value to determine whether each exchange rate was successfully created or updated.

When you submit an array of exchange rates, objects with valid data are updated, while those with invalid data are ignored. See the example below.

Status messages

Status Description

Exchange Rate updated

All data was correct and the exchange rate was updated in for the specified properties.

The list of properties contains invalid numbers/identifiers: [invalid property]. The rate was not updated.

One (or more) of the AdacoProperties is not a valid property number within the Adaco site.

The rate is not updated in any of the specified properties.

\“From Currency\” and \“To Currency\” should be different, exchange rate not updated.

The currency code for both FromCurrency and ToCurrency is the same. You cannot convert a currency into itself.
Currency code [currency code] does not exist, exchange rate not updated The currency code specified for either FromCurrency or ToCurrency is not a valid ISO 4217 currency code.

Unsuccessful requests

Requests that failed submission receive an HTTP 400-599 response, with an error message in the response body.

Example request and response

This example request is accepted by Fourth, however, note that:

  • The first object in the array is a valid example.
  • The second object has an invalid property (99999).
  • The third object specifies the same currency it is trying to replace.
  • The fourth object has invalid country codes. 

This means that only the data in the first object is applied to the specified properties.

[
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5
  },
  {
    "AdacoProperties": [ "121", "99999" ],
    "FromCurrency": "USD",
    "ToCurrency": "GBP",
    "Rate": 1.50
  },
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "USD",
    "ToCurrency": "USD",
    "Rate": 1.6
  },
  {
    "AdacoProperties": [ "121", "126" ],
    "FromCurrency": "US$",
    "ToCurrency": "GPP",
    "Rate": 1.6
  }
]

The above request results in the following response.

{
  {
    "FromCurrency": "USD",
    "ToCurrency": "EUR",
    "Rate": 1.5,
    "Status": "Exchange Rate updated",
    "AdacoProperties": [ "121", "126" ]
  },
  {
    "FromCurrency": "USD",
    "ToCurrency": "GBP",
    "Rate": 1.5,
    "Status": "The list of properties contains invalid numbers/identifiers: 99999. The rate was not updated.",
    "AdacoProperties": [ "121", "99999" ]
  },
  {
    "FromCurrency": "USD",
    "ToCurrency": "USD",
    "Rate": 1.6,
    "Status": "\"From Currency\" and \"To Currency\" should be different, exchange rate not updated",
    "AdacoProperties": [ "121", "126" ]
  },
  {
    "FromCurrency": "US$",
    "ToCurrency": "GPP",
    "Rate": 1.6,
    "Status": "Currency code US$ does not exist, exchange rate not updated",
    "AdacoProperties": [ "121", "126" ]
  }