Let's get started
Welcome to Amadeus Hospitality Web Services for Events! This document will walk you through the basics from authenticating with Amadeus Hospitality Web Services (AHWS) to actually retrieving event data. As we guide you through this process it is expected you will have some familiarity with REST, however you do not need to be an expert. Connecting with AHWS can be achieved by even the most inexperienced developers. To start, we will take a look at authentication.
NOTE: Before your first API call, you must register as a AHWS partner and log into the portal.
Events API Tutorial
Authenticate with AHWS
Once you have your Events API credentials (supplied by Amadeus Hospitality) you will be able to use all the APIs outlined in this document. When using the developer console in this documentation, you can simply input your AHWS credentials into "Authentication type" field as "Resource Owner Password":
For a deeper dive on our authentication, check out our authentication guide.
Identify Locations
Want to specify your own values instead of using a Location Id? Check out the Channel Location Code guide.
There are two ways to retrieve location information. The Location/Search API and the Location/Get API. The Location/Search API will provide the entire collection of locations available. In the list of attributes that are returned the Id attribute represents the AHWS LocationId. The AHWS LocationId will be used as an input parameter to the following API calls: FunctionRoom/Search, FunctionRoomGroup/Search, and BookingEvent/DefiniteEventSearch.
https://api.newmarketinc.com/api/Location/Search?subscription-key=<your-subscription-key>
This post will not have any post parameters. The response body will contain a collection of Locations. If the response collection is empty then no locations are available.
Here is an example of what the JSON payload returned will look like:
{
"Name": "Northwest stay Moore Hotel",
"Status": "ACTIVE",
"AddressLine1": "7752 Morton way",
"AddressLine2": null,
"AddressLine3": null,
"City": "Houston",
"Country": "USA",
"CountryCode": "US",
"DistanceTonearestAirport": 10,
"DistanceUnitOfMeasure": "Miles",
"DrivetimeToNearestAirportInMinutes": 15,
"Fax": 1.603.555.5555,
"NearestAirportCode": null,
"Phone": 1.603.556.5555,
"PostalCode": 77025,
"SizeUnitofMeasure": "feet",
"StateProvince": "NH",
"TimeZone": "Eastern Standard Time",
"WebSiteUrl": http: //www.NorthWestStayMooreHotel.com,
"Id": 64O38C9I6000000001RMGQBK6SO3EI2G9H47CD3D"
}
https://api.newmarketinc.com/api/location/ExternalLocationId?subscription-key=<your-subscription-key> https://api.newmarketinc.com/api/location/LocationId?subscription-key=<your-subscription-key>
Using the Location/Search API will always return you a full list of locations. Sometimes you may just need the information for a single location or a small subset of locations. This is what the Location/Get API is for. If you know a specific AHWS LocationId, you can call the Location/Get API to return the detail of that specific location.
The response body will contain specific location data:
[
{
"Name":"Northwest stay Moore Hotel",
"Status":"ACTIVE",
"AddressLine1":"7752 Morton way",
"AddressLine2":null,
"AddressLine3":null,
"City":"Houston",
"Country":"USA",
"CountryCode":"US",
"DistanceTonearestAirport":10,
"DistanceUnitOfMeasure":"Miles",
"DrivetimeToNearestAirportInMinutes":15,
"Fax":1.603.555.5555,
"NearestAirportCode":null,
"Phone":1.603.556.5555,
"PostalCode":77025,
"SizeUnitofMeasure":"feet",
"StateProvince":"NH",
"TimeZone":"Eastern Standard Time",
"WebSiteUrl":http://www.NorthWestStayMooreHotel.com,
"Id":64O38C9I6000000001RMGQBK6SO3EI2G9H47CD3D"
}
]
Both Location/Search and Location/Get APIs return the same fields, so call the API that makes the most sense for your needs.
Identify Function Room Groups
Now that you have the location, you will want to drill into event info. There are a couple ways to access definite events with our APIs. Depending on your needs you may decide to use just FunctionRoomGroup/Search, FunctionRoom/Search or both. Each API has its own strengths. Let's start with FunctionRoomGroup/Search.
https://api.newmarketinc.com/api/functionroomgroup/Search?subscription-key=<your-subscription-key>
The FunctionRoom/Search response includes the FunctionRoomGroupId associated with the room. To obtain a collection of FunctionRoomGroups for a specific location, use the the FunctionRoomGroup/Search API.
The request is a FunctionRoomGroup object. Here is an example.
{
"LocationIds": [
"64O38C9I6000000001RMGQBK6SO3EI2G9H47CD3D"
]
}
Post Parameters:
- ExternalLocationId or LocationId: required. One of these must be included in the request.
- FunctionRoomIds: Optional
- ExternalFunctionRoomIds: Optional
- RecordStatus: Required
- MaxResultCount: Optional, the maximum numbers of records that will be returned in the collection. If this value is not specified in the request, a default value of 50 will be used.
NOTE: Either LocationId or ExternalLocationId can be used as a parameter in the Location Search API. When there is a choice you should always use LocationId.
The Response body will return a collection of FunctionRoomGroups.
[
{
"Id": "00032C1K64OJI00000000HII8SQ2QC9L5KO30C1H""ExternalId": "FRG4-15-0001",
"RecordStatus": "Active",
"FunctionRoomIds": [
null
],
"ExternalFunctionRoomIds": [
null
],
"LocationId": "00OJ0D1H64SG00000004MTI29L942TRQED54UDROED77GKBI",
"ExternalLocationId": "KvBMRAwzsJO7xsNxQr",
"AlternateDescription": null,
"AlternateName": null,
"Description": "This group includes the function rooms on the east wing.",
"Name": "EastWing",
},
{
"Id": "00032C1K64OJI00000000HII8SQ2QC9L5KO30C1J",
"ExternalId": "FRG-15-003",
"RecordStatus": "Active",
"FunctionRoomIds": [
"64O38C9H74000000012J0D1D8P930C1M",
"64O38C9H74000000012J0D1D8P930C1I"
],
"ExternalFunctionRoomIds": [
"E04-FR006",
"E04-FR002"
],
"LocationId": "00OJ0D1H64SG00000004MTI29L942TRQED54UDROED77GKBI",
"ExternalLocationId": "KvBMRAwzsJO7xsNxQr",
"AlternateDescription": null,
"AlternateName": null,
"Description": "This group includes the function rooms on the north wing.",
"Name": "NorthWing"
}
]
In the example above two function room groups are included. One function room group named "EastWing" that is not associated to any function rooms, and one named “NorthWing” that is associated with two function rooms. FunctionRoomGroup/Search is great when you need to return events happening in a specific area of a hotel.
Search for the Location's Function Rooms
https://api.newmarketinc.com/api/functionroom/Search?subscription-key=<your-subscription-key>
Of course you won't always need to call an entire group of function rooms. Sometimes you will just need the details for events happening within a specific function room. You can use the FunctionRoom/Search API to find the function rooms associated with a specific AHWS LocationId.
The request body will be a FunctionRoomSearch object. Here is an example:
{
"LocationIds": [
"64O38C9I6000000001RMGQBK6SO3EI2G9H47CD3D"
]
}
Post Parameters:
- ExternalLocationId or LocationId: required. One of these must be included in the request.
- FunctionRoomGroupIds: Optional, this is a collection of AHWS Function Room Group Ids.
- ExternalFunctionRoomGroupIds: Optional, this is a collection of ExternalFunctionRoomGroupIds.
- RecordStatus: Required
- MaxResultCount: Optional, the maximum numbers of records that will be returned in the collection. If this value is not specified in the request, a default value of 50 will be used.
The response body will return a collection of function room data.
[
{
"ExternalId": "eo4-fr002",
"ExternalCreatedById": "18457",
"ExternalCreatedOn": "2014-10-10T11:05:45-04:00",
"ExternalModifiedById": "1847",
"ExternalModifiedOn": "2014-10-10T11:05:45-04:00",
"CreatedById": "147172",
"CreatedOn": "2014-10-10T10:48:32-04:00",
"ModifiedBy": "147172",
"ModifiedOn": "2014-10-10T11:05:45-04:00",
"Abbreviation": "GR",
"Alias": “GreenRoom”,
"AlternateFunctionRoomName": "Alt Name Green Room",
"Area": 500.0,
"Comments": “”,
"DefaultAdministrativeChargePercentage": null,
"DefaultGratuityPercentage": null,
"DefaultSetupDurationMinutes": 28,
"DefaultTeardownDurationMinutes": 28,
"ExternalBuildingId": null,
"DefaultEventSetupTypeId": “Rounds”,
"ExternalDefaultEventSetupTypeId": “Rounds”,
"ExternalLevelId": 1,
"Height": 12.0,
"ImageUri": null,
"Length": 40,
"MaxAccessHeight": 12,
"MaxAccessWidth": 15,
"MinimumCapacity": 75,
"MultiRoomBlockGroup": "No",
"Sequence": 2,
"WebSiteUrl": “http: //AHWSm.GreenRoom.com”,
"Width": 40,
"LocationId": "64O38C9G7400000001K3COR1DCQ6GPR1C4QMEPRE",
"ExternalLocationId": "H6cAk4HGAa5gGN",
"FunctionRoomType": "StandaloneFunctionRoom",
"Name": "Green Room",
}
]
Retrieve Booking Event Details from AHWS
https://api.newmarketinc.com/api/bookingEvent/DefiniteEventSearch?subscription-key=<your-subscription-key>
Finally now that we have got the location, function room group, and function room information in order we can make a call to get event details. To retrieve the latest BookingEvent data in AHWS, you will need to call the BookingEvent/DefiniteEventSearch API.
The request payload is a DefiniteEventSearch object. Here is an example:
{
"BookingEventDateTimeBegin": "2022-01-01",
"BookingEventDateTimeEnd": "2022-01-08",
"LocationId": "00OJ0D1H64SG00000004MTI29L942TRQED54UDROED77GKBI"
}
Post Parameters:
- BookingEventDateTimeBegin: Required
- BookingEventDateTimeEnd: Required
- LocationId: Required
- ExternalLoctionId: Optional
- BookingId: Optional
- ExternalBookingId: Optional
- FunctionRoomGroupId: Optional
- ExternalFunctionRoomGroupId: Optional
- MaxResultCount: Optional, the maximum numbers of records that will be returned in the collection. If this value is not specified in the request, a default value of 50 will be used.
- IsPosted: Optional
NOTE: For the BookingEvent/DefiniteEventSearch API only 7 days of data will be returned in a single request. Some integrations allow configuration to limit the number of days into the future that results can be returned by the API.
The response body will contain a collection of BookingEvents. If no BookingEvent records meet the search criteria, the collection will be empty. Here is an example of what the JSON payload returned will look like with all of the available attributes; attributes may vary dependent upon the configured integration.
[
{
"ExternalId": "Ingersoll-Rand Corporation",
"AccountName": "Ingersoll-Rand",
"AlternateAccountName": "2014-10-10T11:05:45-04:00",
"AlternateEventClassificationName": null,
"AlternateFunctionRoomName": "Alt Name Gallery",
"BookingPostAs": "Sheriff's Assocaition Reception",
"BookingTypeName": "",
"EndDateTime": "2022-01-02T13:00:00",
"EventClassificationName": "Lunch",
"ExternalAccountId": "4F3-8D74-0002",
"ExternalFunctionRoomId": "E04-FR005",
"FunctionRoomName": "Gallery",
"LocationName": "North Hotel",
"StartDateTime": "2022-01-02T12:00:00",
"AgreedAttendance": 50,
"AlternateName": “Lunch”,
"Description": “”,
"EstimatedAttendance": 50,
"ForecastedAttendance": 42,
"GuaranteedAttendance": 50,
"IsPosted": true,
"Name": "Sheriff's Association Reception Lunch",
"SetAttendance": 50,
"ExternalBookingId": "whit707HPLHv4m_TZ5la",
"ExternalLocationId": "whit707HPLHv4m",
"Id": "00032C1K64P3000000000TR8D5Q3EC1N9184OI3M6HMLUL2Q6LM62NRDD5B48JHK"
}
]
Troubleshooting Guide
Of course, things don’t always go smoothly. Here is some information that may help you in troubleshooting any errors you may encounter.
HTTP Status Codes |
Reason |
|---|---|
| 200 | The server has successfully processed the request. |
| 201 | Created - resource was created. |
| 202 | Accepted - request has been accepted but the resource change has not been applied. |
| 204 | The server successfully processed the request but is returning no content. |
| 400 | The request could not be understood. Please check the response for additional information. |
| 403 | The server understood the request but is not able to fulfill because of insufficient permission. |
| 404 | The requested resource was not found. |
| 500 | The server has encountered a problem, please try again. |
| 503 | The service is temporarily unavailable. If the length of the delay is known a Retry-After header is given. It is recommended that the client delay for this interval before sending another request to the service. If no Retry-After is provided the client should handle as a 500 error. |
Authentication Failure
In the event of an authentication failure, the response body should contain an object looking something like this:
{
"error": "access_denied",
"error_description": "null",
"grant_type": "null",
"error_uri": "null"
}
Please be sure to double check your authentication parameter values and try again.