Getting Started

Welcome to Fourth's API documentation! This page provides guidance on integrating with Fourth's REST APIs. To discover all the possible ways to integrate, please see Integration Options.

Request credentials

We highly recommend that your first step is requesting credentials.

Live credentials

API credentials are linked to customer accounts. Therefore, you must ask your mutual Fourth customers to request credentials for your use. Credentials can take 2 to 4 weeks to provision.
Customers using our Fourth Inventory for Hotels (Adaco) solution generate the API credentials themselves. Instructions on how customers can do this are on the guide pages for each of these APIs.

Test credentials

With our test environments, you can use a separate set of test credentials. You can request these directly from your Fourth integration consultant.

Request host details

We do not currently show our production or test host locations. Therefore, before you can begin you will also need to contact Fourth to get the host details for the APIs you wish to use.

Customers using our Fourth Inventory for Hotels (Adaco) solution may have their own unique hosts.

Read the documentation

This website holds all our guides and OpenAPI references for our publically-accessible REST APIs. If you are interested in extending an API or need further help, don't hesitate to get in touch. Some API solutions are only available after discussion with our integration team.

Understand authentication

Our APIs use either OAuth 2.0 or Basic authentication.

Using OAuth 2.0

For information about using OAuth 2.0, see our dedicated page: Authenticating with OAuth.

Using Basic authentication

To use Basic authentication, you must include your Fourth username and password in the request header. The username and password must be joined with a colon inbetween; for example:

• exampleUsername:examplePassword

You then need to base 64 encode this string (into the UTF-8 character set). For example, exampleUsername:examplePassword becomes:

• ZXhhbXBsZVVzZXJuYW1lOmV4YW1wbGVQYXNzd29yZA==

Add this to the Authorization header as Basic encoded-string:

GET /{customerName}Service/WebApi/ExchangeRates  HTTP/1.1
Host: instance.example.com
Authorization: Basic ZXhhbXBsZVVzZXJuYW1lOmV4YW1wbGVQYXNzd29yZA==

Test your integration

Test with Swagger

Most of our REST APIs have Swagger endpoints that allow you to view the documentation and test requests. These are reached through the endpoint:

• [ROOT]/{path}/swagger/ui/index

Swagger has the option to test API calls; however, to do so you need to authenticate your requests. This is possible for some our APIs by selecting the ! icon for the request method:

The test interface of APIs that require OAUTH, such as the Tasks or Notifications API, may also accept Basic authentication from the Swagger UI.

Understand the response from Fourth

Fourth uses standard HTTP response codes to indicate whether a request was successful.

Create a retry strategy

If you receive a 500-599 response, then you should retry your request using a truncated backoff strategy; for example:

• 1 minute > 2 minutes > 4 minutes > 8 minutes > 15 minutes > 30 minutes > 1 hour > 2 hours > etc...

Please retry requests no more than once a minute. Get in contact with Fourth if the issue is ongoing.

If you do not receive a response, them you will need to consider how you want to respond based on the API:

• If you are sending a push notification through the Tasks API or Notifications API, you may want to restrict your retries so that you do not keep sending the same message through to a user.
• For other APIs, if the API request is not idempotent, (for example, some POST requests will create new resources with each request) you may decide to not retry the request automatically. Please check each APIs behavour when integrating.