AwardWallet Email Parsing API
Introduction
Email Parsing API allows you to extract structured information from an unstructured email. Specifically, you can extract travel itineraries from virtually any travel provider using this REST API. The email parser API can automatically process incoming emails, it will extract data from incoming emails and using webhook integrations send the resulting structured data to your endpoint. The main benefit of this email scraping technology is that you can import travel reservations that belong to your users regardless of how these reservations were booked.
Technically here is what happens under the hood: when an email is received for parsing it gets put into a queue for processing, email workers grab emails out of that queue and send them for parsing. The actual process of parsing consists of applying tens of thousands of regular expressions against a given email until the right parser is found and the required data attributes are extracted from that email. Some of our clients have asked us: "What is the difference between email parsing and email scraping?" and the answer is: there is no difference, email scraping (or parsing), just like web scraping means retrieving structured format from unstructured text, be that a web page or body of an email. There are usually two ways to do that: (1) to run regular expressions against that body of text or (2) run XPath queries if the text body has proper HTML formatting.
With AwardWallet Email Parsing API you can send any travel itinerary or reservation to our endpoint and the parse API will extract the data and return the reservation data in a structured format (JSON) for your consumption. Parsing is done automatically and takes just a few seconds.
We support thousands of email formats (click to view the AwardWallet’s list of emails supported for parsing) and we have a dedicated team of developers who constantly work on improving the API by adding new parsers to support new email formats.
If you have an email reservation and want to do a quick test you can upload the .eml file or copy-paste the raw content of the email via our example test page. You should see the parsing results immediately after submitting the request at the bottom of the page.
For production mode, the API is designed to work asynchronously. Here is the workflow diagram explaining what happens to an email once it is received by the API:
At a high level, here is how the API works:
-
You submit an email message for parsing, and specify your
callbackUrl
(must be registered with us prior to using the API) in your request. Our API will respond with aqueued
status. At this point you don’t know if your message was parsed or not. -
Your message will be processed by an automated parser. Shortly, typically within seconds, you will receive a response to your
callbackUrl
, with one of thestatus
codes (which are described below). In most cases, you should get asuccess
code and the results of the parsing will be returned to you in that callback response. For testing, instead of receiving the results to your callback URL, you may simply call the/getResults/{requestID}
method to see the results. -
If you get a
review
status - you should expect a subsequent callback with eithersuccess
,invalid
,restricted
orskipped
status. At this point we are not able to guarantee any time range for manual review process. -
Typically, the emails that you send to us are stored on the AwardWallet’s servers for two weeks (in the Amazon AWS cloud). After that, the emails are permanently deleted from our servers. If it so happens that there will be emails in the
review
status at the two-week mark we will also send you a response to yourcallbackUrl
with a status oftimeout
at the time when we purge the emails. -
Every method that we make available as part of this API can be invoked through two endpoints, the ones that have the
-eu
in the URL point to our EU infrastructure, where all the data processing happens inside EU. The other one points to the servers hosted in the US. -
You could use swagger schema to generate your API clients.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "X-Authentication: userapikey"
Every API call needs to be authenticated with an API authentication token. This token is passed in the "X-Authentication" field with the https request header. The token is formed by concatinating the API username and API password with a ":" symbol. You need to contact us to get your API credentials.
X-Authentication: YourUserName:YourPassword
Email Parsing
Submit Email for Parsing
/parseEmail
is going to be your main method that you are going to be calling to work with this API. This is where you will be sending your emails with travel reservations.
Request Example
{
"callbackUrl": "https://yoursite.com/receiver",
"email": "X-Mailgun: Yes From: test@email.com ...",
"userData": "any text",
"returnEmail": "headers"
}
Request
POST https://service.awardwallet.com/email/json/v2/parseEmail
POST https://email-eu.awardwallet.com/email/json/v2/parseEmail
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
string | true | Full email source, including MIME headers and MIME body |
|
callbackUrl |
string | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | true | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
userData |
string | false | Any text. We will return this text in the response field untouched. You can send your internal message id, or any other data. It can also be used for troubleshooting with our support team as you can reference that value so that we can easily identify the email you are inquiring about. |
Response Example
{
"apiVersion": 2,
"status": "queued",
"errorMessage": "",
"requestIds": [
"fcb4e6c917e3d832fh365df0a821b7dc"
]
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
apiVersion |
int | true | The version of the API being used |
status |
string | true | The status of the request. Can have one of two values:
|
errorMessage |
string | false | If you get an error in the |
requestIds |
array | true | Collection of request IDs, which can be used to retrieve the parsing results using the |
Get Email Parsing Results
Whenever you are testing or troubleshooting our API it may be inconvenient to work with a callbackurl to analyze the results. For this reason, you can simply call this method to get the parsing results for any given email that you sent to us in the last two weeks.
Request
GET https://service.awardwallet.com/email/json/v2/getResults/{requestId}
GET https://email-eu.awardwallet.com/email/json/v2/getResults/{requestId}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
requestId | string | true | You need to get the requestId from the |
Response Example
{
"apiVersion": 2,
"requestId": "7405fa3688970a6329a375c82384bd4a",
"status": "success",
"statusMessage": null,
"rejectMethod": null,
"missingFields": null,
"providerCode": "expedia",
"itineraries": [
{
"travelAgency": {
"providerInfo": {
"code": "expedia",
"name": "Expedia.com",
"accountNumbers": [
{
"number": "EXP-11298",
"masked": false
}
],
"earnedRewards": "1 booking"
},
"confirmationNumbers": [
{
"number": "J3HND-8776",
"description": "Trip Locator",
"isPrimary": null
}
],
"phoneNumbers": [
{
"description": "Help Desk",
"number": "+1-44-EXPEDIA"
}
]
},
"pricingInfo": null,
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "delta",
"name": "Delta Air Lines",
"accountNumbers": [
{
"number": "1234****",
"masked": true
},
{
"number": "4321****",
"masked": true
}
],
"earnedRewards": "300 award miles"
},
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"airportCode": "LAX",
"terminal": "A",
"name": "Los Angeles International Airport",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "LAX",
"addressLine": "1 World Way",
"city": "Los Angeles",
"stateName": "California",
"countryName": "United States",
"postalCode": "90045",
"lat": 33.9415889,
"lng": -118.40853,
"timezone": -25200
}
},
"arrival": {
"airportCode": "SFO",
"terminal": "2",
"name": "San Francisco International Airport",
"localDateTime": "2030-01-01T15:00:00",
"address": {
"text": "SFO",
"addressLine": "San Francisco International Airport",
"city": "San Francisco",
"stateName": "California",
"countryName": "United States",
"postalCode": null,
"lat": 37.615215,
"lng": -122.389881,
"timezone": -25200
}
},
"marketingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"flightNumber": "0013",
"confirmationNumber": "MRTG67",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"isCodeshare": true
},
"operatingCarrier": {
"airline": {
"name": "British Airways",
"iata": "BA",
"icao": "BAW"
},
"flightNumber": "5566",
"confirmationNumber": "CARR23",
"phoneNumbers": [
{
"description": null,
"number": "+1-718-335-7070"
}
]
},
"wetleaseCarrier": {
"name": "Sky Express",
"iata": null,
"icao": null
},
"seats": [
"3E",
"3F"
],
"aircraft": {
"iataCode": "7M7",
"name": "Boeing 737MAX 7 Passenger",
"turboProp": false,
"jet": true,
"wideBody": false,
"regional": false
},
"traveledMiles": "300mi",
"cabin": "Coach",
"bookingCode": "CL",
"duration": "1h30min",
"meal": "Snacks",
"smoking": false,
"status": "Confirmed",
"stops": 0,
"flightStatsMethodUsed": "ScheduleByFlight"
},
{
"departure": {
"airportCode": "SFO",
"terminal": "2",
"name": "San Francisco International Airport",
"localDateTime": "2030-01-05T06:00:00",
"address": {
"text": "SFO",
"addressLine": "San Francisco International Airport",
"city": "San Francisco",
"stateName": "California",
"countryName": "United States",
"postalCode": null,
"lat": 37.615215,
"lng": -122.389881,
"timezone": -25200
}
},
"arrival": {
"airportCode": "LAX",
"terminal": "A",
"name": "Los Angeles International Airport",
"localDateTime": "2030-01-05T07:30:00",
"address": {
"text": "LAX",
"addressLine": "1 World Way",
"city": "Los Angeles",
"stateName": "California",
"countryName": "United States",
"postalCode": "90045",
"lat": 33.9415889,
"lng": -118.40853,
"timezone": -25200
}
},
"marketingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"flightNumber": "0014",
"confirmationNumber": "MRTG67",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"isCodeshare": true
},
"operatingCarrier": {
"airline": {
"name": "British Airways",
"iata": "BA",
"icao": "BAW"
},
"flightNumber": "9009",
"confirmationNumber": "CARR23",
"phoneNumbers": [
{
"description": null,
"number": "+1-718-335-7070"
}
]
},
"wetleaseCarrier": null,
"seats": [
"1B",
"1C"
],
"aircraft": {
"iataCode": "7M7",
"name": "Boeing 737MAX 7 Passenger",
"turboProp": false,
"jet": true,
"wideBody": false,
"regional": false
},
"traveledMiles": "300mi",
"cabin": "First class",
"bookingCode": "I",
"duration": "1h30min",
"meal": "Snacks",
"smoking": null,
"status": "Confirmed",
"stops": null,
"flightStatsMethodUsed": "ScheduleByAirport"
}
],
"issuingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"confirmationNumber": "ISSD12",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"ticketNumbers": [
{
"number": "006 123321",
"masked": false
},
{
"number": "006 456654",
"masked": false
}
]
},
"type": "flight"
},
{
"travelAgency": {
"providerInfo": {
"code": "expedia",
"name": "Expedia.com",
"accountNumbers": [
{
"number": "EXP-11298",
"masked": false
}
],
"earnedRewards": "1 booking"
},
"confirmationNumbers": [
{
"number": "J3HND-8776",
"description": "Trip Locator",
"isPrimary": null
}
],
"phoneNumbers": [
{
"description": "Help Desk",
"number": "+1-44-EXPEDIA"
}
]
},
"pricingInfo": null,
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "spg",
"name": "Starwood Hotels",
"accountNumbers": [
{
"number": "xxxxxx345",
"masked": true
}
],
"earnedRewards": "4 nights"
},
"confirmationNumbers": [
{
"number": "1122334455",
"description": "Confirmation number",
"isPrimary": true
},
{
"number": "887756",
"description": "Reference",
"isPrimary": false
}
],
"hotelName": "Sheraton Philadelphia Downtown Hotel",
"chainName": null,
"address": {
"text": "201 North 17th Street, Philadelphia, Pennsylvania 19103 United States",
"addressLine": "201 North 17th Street",
"city": "Philadelphia",
"stateName": "Pennsylvania",
"countryName": "United States",
"postalCode": "19103",
"lat": 39.9569828,
"lng": -75.1674669,
"timezone": -14400
},
"checkInDate": "2030-01-01T13:30:00",
"checkOutDate": "2030-01-05T12:00:00",
"phone": "+1-22-3333",
"fax": "+1-66-77899",
"guests": [
{
"name": "John D.",
"full": false
},
{
"name": "Jane D.",
"full": false
}
],
"guestCount": 2,
"kidsCount": 3,
"roomsCount": 1,
"cancellationPolicy": "Cancellation is free prior to check-in",
"rooms": [
{
"type": "King bed",
"description": "Traditional, TV, free wi-fi",
"rate": "30$/night",
"rateType": "King bed"
}
],
"type": "hotelReservation"
}
],
"loyaltyAccount": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"fromProvider": false,
"metadata": {
"from": {
"name": null,
"email": "agency@test.awardwallet.com"
},
"to": [
{
"name": null,
"email": "plans@awardwallet.com"
}
],
"cc": [
],
"subject": "Composite reservation",
"receivedDateTime": "2017-06-27T15:35:37",
"userEmail": "agency@test.awardwallet.com",
"nested": false,
"mailboxId": null
},
"nestedEmailMetadata": null,
"parsingMethod": "auto",
"flightStatsMethodsUsed": [
{
"name": "ScheduleByFlight",
"count": 1
},
{
"name": "ScheduleByAirport",
"count": 1
}
],
"userData": "any text",
"email": null
}
Response
Parse result
Parameter | Type | Required | Description |
---|---|---|---|
apiVersion |
string | true | Version of the API being used. |
requestId |
string | true | RequestID that corresponds to this email. |
status |
string | true | Status of the parsing results. The possible values are: success - The email was successfully parsed queued - The email is sitting in the queue, waiting to be processed by the parser you can call this method again in a few seconds or you can wait to receive the results to the invalid - It was determined that this email does not contain a valid travel itinerary or reservation. See the review - The automated parsers failed to parse this email, at this point the message is going to be placed into the manual queue for someone at AwardWallet to check it and decide if we should adjust a parser and re-run it again through the parsing process. You should not expect successful parsing results quickly (in under 1 hour) as someone manually has to review the email and adjust the parsers. restricted - This is a restricted provider that AwardWallet is not allowed to parse at this point. skipped - This email was reviewed and we determined that this is an itinerary and for one reason or another we did not parse this reservation. This email was not counted against your license count. timeout - We were not able to review this email in a timely fashion, thus we don’t know if this is a valid reservation or not. This email was purged from our queue automatically and was not counted against your license count. |
statusMessage |
string | false | If you get |
rejectMethod |
string | false | This field indicates the reason why our system determined that an email does not contain a valid travel reservation in it. The possible values are: auto - The system automatically (using built-in filters) determined that the email does not contain a valid itinerary. manual - This email was reviewed by our support staff and it was determined that it does not contain a valid travel reservation. incomplete - This email might contain a travel reservation, but some required fields are missing from it. |
missingFields |
array | false | If the |
providerCode |
string | false | Alpha-numeric value with no spaces that uniquely identifies any given provider within the AwardWallet interface. |
fromProvider |
boolean | false | Indicates if this email was sent directly by the provider as opposed to the user forwarding that message. |
object | false | If the email contains loyalty information (i.e. account balance, account number, elite status, etc.) like a monthly statement, then we will return all that loyalty information in this object. We typically do this for United, Delta and Southwest statements. |
|
array | false | An array of all itineraries parsed out of the email |
|
string | false | Returns the email headers, the entire email, or nothing at all, depending on the value of |
|
object | true | Some email headers and other metadata will be returned in this object. If you need to get the full headers, please set the |
|
object | false | Same as the |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
parsingMethod |
string | false | The method of parsing that was used. There are two possible values: auto - for automatically parsed emails manual – for emails that were parsed manually by the AwardWallet team |
array | false | If we needed to call FlightStats to retrieve some fields that are required and are missing in the email all such FlightStats calls will be listed in this array. |
|
userData |
string | false | Returns whatever text you sent (as is) in the |
FlightStats Methods Used
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | The name of the FlightStats API method that was called during the parsing. Here are the possible values:
|
count |
integer | true | Number of calls made to this method. |
Pricing Info
Parameter | Type | Required | Description |
---|---|---|---|
total |
number | false | Total cost of the reservation including all taxes and fees. |
cost |
number | false | Cost of the reservation before taxes. |
discount |
number | false | Total amount of discounts, if any. |
spentAwards |
string | false | Frequent flier miles, points, or other kinds or bonuses spent on this reservation. |
currencyCode |
string | false | Currency code as gathered from the website. I.e. |
array | false | Various fees associated with the reservation. |
Fee
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | Fee description. |
charge |
number | true | Fee amount. |
Email Metadata
Parameter | Type | Required | Description |
---|---|---|---|
object | false | The sender’s name (if exists) and the email address of the sender. |
|
array | false | An array of email recipients listed in the |
|
array | false | An array of email recipients listed in the |
|
subject |
string | false | Email subject. |
receivedDateTime |
string | false | Date and time when the email was received in the mailbox in the |
nested |
boolean | false | Set to ‘true’ if this email was received as an attachment to another email, that was actually submitted, and ‘false’ otherwise. |
userEmail |
string | false | Presumable email address of the actual end user. This email address may be parsed from the email headers (from, to, cc) or from the email body. |
mailboxId |
integer | false | Filled in with mailbox id, if this message was downloaded from mailbox added with /mailboxes/ api |
Email Address
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | false | The name that is associated with the email address. |
string | true | The actual email address. |
Loyalty Information
If the email is a monthly loyalty account statement (meaning it contains loyalty account information such as account balance, account number, elite status, etc.), then we will return all that loyalty information in this object. We typically do this for United, Delta, and Southwest statements.
Parameter | Type | Required | Description |
---|---|---|---|
balance |
double | false | Loyalty account balance, i.e. how many miles or points the user has. |
balanceDate |
string | false | In some cases, the statement email may have a balance date (basically stating that this was the balance as of some specific date). If we see such a date it will be returned in this field. |
expirationDate |
string | false | Account balance expiration date |
login |
string | false | Loyalty account username. If the |
login2 |
string | false | Additional login value. A common example would be a country that the loyalty program supports. |
loginMask |
string | false | This field indicates if the |
number |
string | false | Account number. If the |
numberMask |
string | false | This field indicates if the |
isMember |
boolean | false | This flag indicates that the email does not have any loyalty account attributes in it; however, it confirms that the user is a member of that loyalty program. |
array | false | We gather as much data as possible from any given account on top of the main attributes like the account balance and its expiration date. These secondary properties will be available in this array. |
|
array | false | Email may contain account transaction history. If that is the case the actual account transactions will be returned in this array. Please note that we only support specific formats for specific providers, if you wish to use this feature you would need to contact our support team to better understand which email formats are supported. |
History Row
Unfortunately, most providers present their history differently, as much as we want to unify this information it doesn’t seem to be possible, so when presenting a single history row, we define each field separately with three values as described below.
Parameter | Type | Required | Description |
---|---|---|---|
array | false | History fields as described below. |
History Field
Think of a single row of data that describes a historical transaction. fields
are the individual values that comprise that transaction. Instead of just providing you with a text value we provide you with an array of metadata that define what this value is.
Parameter | Type | Required | Description |
---|---|---|---|
code |
string | false | We have four predefined field codes; they are: PostingDate – date-time value of the transaction Description – text value of the transaction description Miles – the number of miles added or subtracted from the account Info – any other column that we see as part of the history on the prover’s website. |
name |
string | false | User-friendly name of the field, i.e. “Posting Date” that you can show as the column heading to your end users. |
value |
string | false | The actual field value, such as "10,000" |
Property
In case if the email contains a loyalty account statement that we are able to parse, the individual loyalty account properties will be returned in this array.
Parameter | Type | Required | Description |
---|---|---|---|
code |
string | false | This is a short, alphanumeric codename do describe this attribute. |
name |
string | false | User friendly name of the property such as “Account number”. You can display this to your end users. |
kind |
string | false | Type of property, the possible values are: 0 - Basic property 1 - Account number 3 - Elite Status 4 - Lifetime points 7 - Points / miles earned year-to-date (YTD). 8 - Segments earned year-to-date (YTD). 12 - Name of the account holder, as listed on the account. 13 - Date of the last account activity. 101 - Login information 102 - Partial login information if it was masked in the email 103 - Partial account number if it was masked in the email |
value |
string | false | The actual property value, such as “Silver” |
List providers
In addition to travel itineraries, we are able to retrieve loyalty information, such as loyalty account balance, elite status and expiration by parsing data out of email account statements for a select number of loyalty programs. All of the programs that we support and the properties we are able to retrieve are listed using this method.
Request
GET https://service.awardwallet.com/email/json/v2/providers/list
GET https://email-eu.awardwallet.com/email/json/v2/providers/list
Response Example
{
"apiVersion": 2,
"list": [
{
"code": "delta",
"displayName": "Delta Air Lines (SkyMiles)",
"shortName": "Delta Air Lines",
"supportedLanguages": [
"en",
"es",
"de",
"zh",
"ja",
"ko",
"pt",
"it",
"fr"
],
"supportedFormatCount": 32,
"properties": [
{
"code": "Level",
"name": "Membership Level",
"kind": "3"
},
{
"code": "Login",
"name": "Login",
"kind": "101"
}
],
"historyColumns": [
{
"code": "PostingDate",
"name": "Posting Date",
"kind": "0"
},
{
"code": "Description",
"name": "Description",
"kind": "0"
},
{
"code": "Info",
"name": "Miles",
"kind": "0"
}
]
},
{
"code": "mileageplus",
"displayName": "United Airlines (Mileage Plus)",
"shortName": "United",
"supportedLanguages": [
"en",
"es",
"pt",
"zh",
"ja",
"fr",
"de"
],
"supportedFormatCount": 64,
"properties": [
{
"code": "EliteMiles",
"name": "YTD Premier Miles",
"kind": "7"
},
{
"code": "EliteSegments",
"name": "YTD Premier Segments",
"kind": "8"
}
],
"historyColumns": [
{
"code": "PostingDate",
"name": "Activity Date",
"kind": "0"
},
{
"code": "Description",
"name": "Description",
"kind": "0"
}
]
}
]
}
Response
Providers
Parameter | Type | Required | Description |
---|---|---|---|
code |
string | true | Alpha-numeric value with no spaces that uniquely identifies any given provider. |
displayName |
string | true | User friendly display name of the provider. Typically includes both the company name and the name of the loyalty program, i.e. Delta Air Lines (SkyMiles). |
shortName |
string | false | Shortened display name of the provider. |
supportedLanguages |
array | false | Array of ISO 639-1 2-letter language codes which are supported for email parsing for this provider |
supportedFormatCount |
integer | false | Estimated number of email formats supported for email parsing for this provider |
array | false | Array of account properties (secondary attributes) that we may gather from email account statements. |
|
array | false | Array of account transaction history columns that we may gather from emails. |
Properties
Parameter | Type | Required | Description |
---|---|---|---|
code |
string | true | Property code name. Can only have English numbers and letters with no spaces. |
name |
string | true | User friendly name of a property such as “Account number”. You can display this to your end users. |
kind |
string | true | Type of property, the possible values are: 0 - Basic property 1 - Account number 3 - Elite Status 4 - Lifetime points 7 - Points / miles earned year-to-date (YTD). 8 - Segments earned year-to-date (YTD). 12 - Name of the account holder, as listed on the account. 13 - Date of the last account activity. 101 - Login information 102 - Partial login information if it was masked in the email 103 - Partial account number if it was masked in the email |
Email Scanner
Detect Mailbox Type
We support scanning mailboxes via 4 different methods:
- IMAP Protocol
- Google API
- Microsoft API
- Yahoo API
- Aol API
Since both Google and Microsoft APIs support custom domains (for businesses) you can’t easily tell if a specific email address is managed by either Google Apps or Microsoft Office 365 cloud services. This call will perform the necessary queries to determine if this mailbox is managed by either Google or Microsoft. If it is not, then you need to connect this type of mailbox via the IMAP protocol.
Request
GET https://service.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}
GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
string | true | Any email address to be tested. This email doesn’t need to be already added to AwardWallet. |
Response Example
{
"type": "microsoft"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
type |
string | true | Tells you how this mailbox should be connected. Can be one of the options: |
Connect via IMAP
Request Example
{
"login": "JohnSmith@yahoo.com",
"password": "SecretPassword1234",
"host": "imap.mail.yahoo.com",
"port": 993,
"secure": true,
"startFrom": "2018-07-05",
"listen": true,
"callbackUrl": "http://company.com/api/email/itinerary-receiver",
"userData": "Testing the mailbox scanner API",
"tags": [
"test",
"userid_1234"
],
"onProgress": {
"callbackUrl": "http://company.com/api/email/progress-receiver"
}
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/imap
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/imap
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
host |
string | false | The IMAP address of the server where we should establish connection. If you omit this parameter we will attempt to detect the IMAP server address automatically for this specific mailbox. |
port |
integer | false | The IMAP server port. If you omit this parameter we will try to detect the port automatically. |
login |
string | true | The IMAP server login, in most cases it will be the email address. |
password |
string | true | The IMAP account password. |
secure |
boolean | false | Set to |
Response Example
{
"state": "connecting",
"id": 3473,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"userData": "Testing the mailbox scanner API",
"tags": [
"test",
"userid_1234"
],
"login": "JohnSmith@yahoo.com",
"type": "imap"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
host |
string | true | The IMAP address of the server where mailbox is hosted. |
login |
string | true | The IMAP server login to connect to the mailbox. In most cases it should be the email address. |
secure |
boolean | false | Shows the value (true or false) for connection type that you passed to us when adding the mailbox. If it was not set then it is true by default. |
Sample MailboxProgressEvent
{
"event": "state_change",
"mailbox": {
"id": 3474,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"callbackUrl": "https://some.example.host/results",
"returnEmail": "none",
"onProgress": {
"callbackUrl": "https://some.example.host/progress"
},
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
],
"state": "connecting",
"email": "john@gmail.com",
"type": "google"
}
}
MailboxProgressEvent
Notification about mailbox scannining progress
Parameter | Type | Required | Description |
---|---|---|---|
event |
string | true | Type of event |
object | true | Mailbox information |
Mailbox information
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
Example of Callback Data
[
{
"type": "state_change",
"mailbox": {
"state": "scanning",
"id": 1234,
"creationDate": "2018-08-01T10:09:49+0000",
"startFrom": "2018-07-16",
"listen": true,
"tags": [
"test",
"userid_1234"
],
"email": "john@gmail.com",
"type": "google"
}
},
{
"type": "state_change",
"mailbox": {
"state": "listening",
"id": 1234,
"creationDate": "2018-04-03T20:09:49+0000",
"startFrom": "2018-02-10",
"listen": true,
"tags": [
"test",
"userid_456"
],
"email": "john@gmail.com",
"type": "google"
}
}
]
OnProgress
This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting
, listening
, error
, etc).
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | If the All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks, we expect to receive code 200. If we get anything another than code 200, we will keep re-trying to send you the response. The page itself can be empty as long as we get code 200. |
Connect via Google API
This method should be used to connect any Google mailbox, not just the @gmail.com
mailboxes but also any mailboxes hosted by Google Apps. In case you are unsure if a given mailbox is hosted by Google you can call the /mailboxes/detect-type/{email}
method.
This method utilizes native Google API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:
If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with Google API this way you will get your own googleClientId
, googleClientSecret
, and googlePubSubTopic
. You need to provide those values to our support so that we can have your account updated.
Here are the rough steps that you need to take to create your own verified Google app:
-
Go to the Google Cloud Dashboard: https://console.cloud.google.com/apis/dashboard and create a new project if you don’t already have one:
-
-
-
Under the API dashboard you need to enable the Gmail API:
-
-
Next you need to create API credentials to be used with this API:
-
-
-
-
Finally grab the credentials file here:
-
You can send this client_id.json to our support or just send us the client_id and the client_secret
-
Next you need to verify the app you just created.
-
Once you met the prerequisites outlined in the article mentioned above you are ready to submit the OAuth Developer Verification Form
-
-
Then you need to enable the Pub/Sub API as follows:
-
-
Once it has been enabled you need to create a Pub/Sub Topic. You should also review the Google’s documentation on this subject matter:
-
-
-
After the Pub/Sub topic has been created you need to create a subscription:
-
-
-
If you have not yet verified your domain, you would need to do that:
-
-
The easiest way to verify the domain would be to do it via the CNAME records:
You would need to give us the CNAME records to add:
Once set up, you should verify your domain ownership and you should get a confirmation from Google that it worked:
-
-
At the end of it you should see at least one Pub/Sub topic subscription enabled:
-
-
Finally, you need to set up Pub/Sub Topic permissions:
-
Make the gmail-api-push@system.gserviceaccount.com
account Pub/Sub Publisher:
here is what it should look like:
This is it, after you finish these steps you should be all set to get access to Gmail accounts.
Request Example
{
"email": "john@gmail.com",
"accessToken": "abcd",
"refreshToken": "efgh",
"startFrom": "2017-06-01",
"listen": true,
"callbackUrl": "https://api.yoursite.com/callback",
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
]
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/google
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/google
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
string | true | The email address of the mailbox |
|
accessToken |
string | true | The |
refreshToken |
string | true | The |
Response Example
{
"state": "connecting",
"id": 3474,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
],
"login": "john@gmail.com",
"type": "google",
"callbackUrl": "https://some.example.host/url1"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
string | true | The email address of the mailbox that was added as part of the request. |
Connect via Microsoft API
This method should be used to connect any Micosoft mailbox, not just the @live.com
, @hotmail.com
, or @outlook.com
mailboxes but also any mailboxes hosted by Microsoft Office 365. In case you are unsure if a given mailbox is hosted by Microsoft you can call the /mailboxes/detect-type/{email}
method.
This method utilizes the native Microsoft API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:
If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with the Microsoft API this way you will get your own Microsoft Client Id and Microsoft Client Secret. You need to provide those values to our support so that we can have your account updated.
Here are the steps that you need to take to create your own verified Microsoft app. Fisrt, login with your Microsoft account and create a new app if you have not already done so:
You don’t really need to do the guided setup, unless you want to:
Next, generate a new password for your application:
Make sure you safely copy the password, you will need to provide this password to our support in order to allow us to scan your user’s mailboxes:
Then, you need to add a platform, you should select “Web” as the platform:
For the Redirect URLs, you should put https://service.awardwallet.com/email/v2/mailboxes/auth/callback
we will handle the response to update this mailbox connection and then will redirect the user to the redirectUrl
that you specified in the /mailboxes/start-auth
request. You can set the logout URL to be whatever you like on your domain. If you don’t wish to have AwardWallet listed in the Redirect URL you can set that to be your domain, i.e. https://yourdoamin.com/email/callback and then proxy requests sent to this URL to our callback URL. In the end your settings should looks something like this:
For Microsoft Graph Permissions please add profile
and User.Read
:
Then set the rest of the application profile attributes:
Request Example
{
"email": "john@hotmail.com",
"accessToken": "wxyz",
"refreshToken": "hijk",
"startFrom": "2017-06-01",
"listen": true,
"callbackUrl": "https://api.yoursite.com/callback",
"userData": "Testing the connection via the Microsoft API",
"tags": [
"test",
"userid_1234"
]
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/microsoft
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/microsoft
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
string | true | The email address of the mailbox |
|
accessToken |
string | true | The |
refreshToken |
string | true | The |
Response Example
{
"state": "connecting",
"id": 3472,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"userData": "Testing the connection via the Microsoft API",
"tags": [
"test",
"userid_1234"
],
"login": "john@hotmail.com",
"type": "microsoft"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
string | true | The email address of the mailbox that was added as part of the request. |
Connect via Yahoo API
This method is used to connect a Yahoo! mailbox. In order to be able to use this method you need to get approved by
Verizon Media Mail API
(mail-api @ verizonmedia.com) once approved you will be able to create an app under your Yahoo! developer account:
https://developer.yahoo.com/apps/ If you wish to use our /mailboxes/start-auth
method then you should use the following
redirect URI: https://awardwallet.com/mailboxes/callback/oauth/yahoo and for permissions, you need to request
Mail - Read
and
Profiles - Read Public Extended
as follows:
Request Example
{
"email": "john@yahoo.com",
"accessToken": "wxyz",
"refreshToken": "hijk",
"startFrom": "2017-06-01",
"listen": true,
"callbackUrl": "https://api.yoursite.com/callback",
"userData": "Testing the connection via the Yahoo API",
"tags": [
"test",
"userid_1234"
]
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/yahoo
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/yahoo
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
string | true | The email address of the mailbox |
|
accessToken |
string | true | The |
refreshToken |
string | true | The |
Response Example
{
"state": "connecting",
"id": 3472,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"userData": "Testing the connection via the Yahoo API",
"tags": [
"test",
"userid_1234"
],
"login": "john@yahoo.com",
"type": "yahoo"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
string | true | The email address of the mailbox that was added as part of the request. |
Connect via Aol API
This method is used to connect a Aol mailbox. In order to be able to use this method you need to get approved by
Verizon Media Mail API
(mail-api @ verizonmedia.com) once approved you will be able to create an app under your Yahoo! developer account:
https://developer.yahoo.com/apps/ If you wish to use our /mailboxes/start-auth
method then you should use the following
redirect URI: https://awardwallet.com/mailboxes/callback/oauth/aol and for permissions, you need to request
email
and
`mail-r
Request Example
{
"email": "john@aol.com",
"accessToken": "wxyz",
"refreshToken": "hijk",
"startFrom": "2017-06-01",
"listen": true,
"callbackUrl": "https://api.yoursite.com/callback",
"userData": "Testing the connection via the Aol API",
"tags": [
"test",
"userid_1234"
]
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/connect/aol
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/connect/aol
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
string | true | The email address of the mailbox |
|
accessToken |
string | true | The |
refreshToken |
string | true | The |
Response Example
{
"state": "connecting",
"id": 3472,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"userData": "Testing the connection via the Aol API",
"tags": [
"test",
"userid_1234"
],
"login": "john@aol.com",
"type": "aol"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
string | true | The email address of the mailbox that was added as part of the request. |
Begin Authentication
Use this method to begin authenticating your user against Google, Microsoft or Yahoo APIs. This method will return a code (valid for 1 hour), that you will then use to redirect your user.
Request Example
{
"startFrom": "2018-07-16",
"listen": true,
"callbackUrl": "http://mycompany.com/api/email/receiver/",
"userData": "userID: 1234",
"tags": [
"test",
"userid_1234"
],
"provider": "google",
"redirectUrl": "http://mycompany.com/emailscanner/welcome/"
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/start-auth
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/start-auth
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | true | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
listen |
boolean | false | If you want our API to listen for new incoming emails going forward you must set this attribute to |
provider |
string | true | Mailbox provider, against which you wish to authenticate. Can be one of the values: |
redirectUrl |
string | true | Upon authentication we will return the user to this URL. We will also pass the following GET parameters in URL |
intermediateRedirectUrl |
string | false | Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint |
host |
string | false | Optional host name which you would set up on your end as a CNAME record pointing to service.awardwallet.com. You only need to do this if you wish to hide a redirect to service.awardwallet.com as part of your users' authentication process. You then need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. |
Response Example
"33bdffdcef607e625agpxe3d470b0d9cbc752184"
Response
The code that you will need to pass into the user OAuth redirect, i.e. when you send your user to https://service.awardwallet.com/email/v2/mailboxes/auth/{code}
for authentication.
Update Authentication
This method can be used to update any given mailbox that we already have connected. You need to pass the mailboxId
in the URL and the rest of the parameters described below as JSON payload. Please note that there is nothing stopping the user from authenticating a different mailbox. In that case, instead of updating the mailboxId
that you provided, we will create a new mailbox connecting for the new email address.
Request Example
{
"startFrom": "2018-07-16",
"redirectUrl": "http://mycompany.com/emailscanner/welcome/"
}
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}/update-auth
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/{mailboxId}/update-auth
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
startFrom |
date | false | When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the |
redirectUrl |
string | true | Upon authentication we will return the user to this URL. We will also pass the following GET parameters in URL |
intermediateRedirectUrl |
string | false | Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint |
host |
string | false | Optional host name which you would set up on your end as a CNAME record pointing to service.awardwallet.com. You only need to do this if you wish to hide a redirect to service.awardwallet.com as part of your users' authentication process. You then need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. |
Response Example
"33bdffdcef607e625agpxe3d470b0d9cbc752184"
Response
The code that you will need to pass into the user OAuth redirect, i.e. when you send your user to https://service.awardwallet.com/email/v2/mailboxes/auth/{code}
for authentication.
User OAuth Redirect
This method can be used to authenticate your users against Google, Microsoft, or Yahoo OAuth APIs. This is not a method you need to call from your servers, instead you need to send your users (via browser) to this URL, it will, then redirect your users to either Google or Microsoft automatically for authentication. After authentication you can see this mailbox being connected to your account via the List Mailboxes (/mailboxes/
) method.
After the authentication completes, the user will be redirected to the redirectUrl, specified in /mailboxes/start-auth
method. You will then receive the following parameters in the URL:
- state:
error
orsuccess
. - errorCode and errorMessage: Technical details about the error. You should not display these fields to the end user, they are designed more for support and troubleshooting purposes.
- mailboxId - You will receive this field in case of a successful connection. You could use this field to call the
Get Mailbox Info
(/mailboxes/{mailboxId}
) method.
Request
GET https://service.awardwallet.com/email/v2/mailboxes/auth/{code}
GET https://email-eu.awardwallet.com/email/v2/mailboxes/auth/{code}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
code |
string | true | This is the code that you got from the |
Get Mailbox Info
Get information about a specific mailbox that was added to our mailbox scanner.
Request
GET https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}
GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/{mailboxId}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
mailboxId | integer | true | This is the ID that you received from either one of the following methods: List Mailboxes ( |
Response Example
{
"id": 3474,
"creationDate": "2018-08-31T21:48:55+0000",
"startFrom": "2018-07-05",
"listen": true,
"callbackUrl": "https://some.example.host/results",
"returnEmail": "none",
"onProgress": {
"callbackUrl": "https://some.example.host/progress"
},
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
],
"state": "connecting",
"email": "john@gmail.com",
"type": "google"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
Update Mailbox Info
This method allows you to update the settings of any given mailbox. You can use it to update mailbox tags for example or if you need to re-authenticate a mailbox you can use this call to provide us with a new access and refresh tokens. Please note that the mailboxId is passed as a GET parameter while the request
object is passed as JSON in the payload.
Request Example
{
"userData": "some new user data",
"tags": [
"test2",
"userid_1236"
],
"onProgress": {
"callbackUrl": "https://some.example.host/new-progress-url"
},
"access_token": "xxx",
"referesh_token": "yyy",
"returnEmail": "none"
}
Request
PUT https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}
PUT https://email-eu.awardwallet.com/email/json/v2/mailboxes/{mailboxId}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
mailboxId | integer | true | This is the ID that you received from either one of the following methods: List Mailboxes ( |
request |
object | true | You need to pass this object as JSON in the payload body. It can be one of the two structures already defined in this documentation: |
Response Example
{
"state": "listening",
"id": 1234,
"creationDate": "2018-08-03T20:09:49+0000",
"startFrom": "2018-07-16",
"listen": true,
"userData": "some new user data",
"tags": [
"test2",
"userid_1236"
],
"email": "john@gmail.com",
"type": "google",
"callbackUrl": "https://some.example.host/url1"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
id |
string | true | The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the |
type |
string | true | The type of the established connection. Could be one of values: |
state |
string | true | The current state of the mailbox, there are 5 options:
|
errorCode |
string | false | If the
|
errorMessage |
string | false | If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter. |
creationDate |
string | true | Date and time in UTC when this mailbox was added for scanning. |
startFrom |
string | false | If the startFrom parameter was passed in the request it will be returned here. |
listen |
boolean | false | Shows the value ( |
Update IMAP Mailbox Request
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
host |
string | false | The IMAP address of the server where we should establish connection. If you omit this parameter we will attempt to detect the IMAP server address automatically for this specific mailbox. |
port |
integer | false | The IMAP server port. If you omit this parameter we will try to detect the port automatically. |
login |
string | false | The IMAP server login, in most cases it will be the email address. |
password |
string | false | The IMAP account password. |
secure |
boolean | false | Set to |
Update OAuth (google, microsoft, yahoo) Mailbox Request
Parameter | Type | Required | Description |
---|---|---|---|
callbackUrl |
uri | false | All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is Content-type: 'application/json' where When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx. If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx. If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the |
returnEmail |
string | false | Indicates whether we should include the original email source in the response or not. There are three possible values:
|
object | false | This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as |
|
userData |
string | false | Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end. |
tags |
array | false | This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes |
accessToken |
string | false | The |
refreshToken |
string | false | The |
List Mailboxes
List all the mailboxes you have aded to the scanner. You can filter the results by tags. To do that, Separate the tags by comma ",", for example:
GET /json/v2/mailboxes/?tags=tag1,tag2
This will return all the mailboxes that have both tag1 and tag2. Response count will be limited to 500 records. Use scroll method to fetch larger datasets
Request
GET https://service.awardwallet.com/email/json/v2/mailboxes/
GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tags |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma. |
states |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox |
types |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox |
errorCodes |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox |
emails |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as |
Response Example
[
{
"state": "listening",
"id": 1234,
"creationDate": "2018-08-03T20:09:49+0000",
"startFrom": "2018-07-16",
"listen": true,
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
],
"email": "john@gmail.com",
"type": "google",
"callbackUrl": "https://some.example.host/url1"
},
{
"state": "listening",
"id": 1235,
"creationDate": "2018-08-30T15:54:27+0000",
"startFrom": "2018-07-16",
"listen": true,
"userData": "Testing the connection via the Microsoft API",
"tags": [
"test",
"userid_1234"
],
"email": "john@hotmail.com",
"type": "microsoft",
"callbackUrl": "https://some.example.host/url2"
}
]
Response
Parameter | Type | Required | Description |
---|---|---|---|
array | false | An array of Mailbox objects. |
List Mailboxes with Pagination
List all the mailboxes you have aded to the scanner. You can filter the results by tags. To do that, Separate the tags by comma ",", for example:
GET /json/v2/mailboxes/scroll/?tags=tag1,tag2
This will return all the mailboxes that have both tag1 and tag2.
If you have many connected mailboxes (hundreds or thousands), you should be using this method to list them. On your first call, you would request this method without the pageToken
attribute, but on the consequent requests, to fetch the next page, you need to pass the nextPageToken
from the response body of your previous request. When you stop receiving the nextPageToken
, it means that there are no more records to fetch.
Request
GET https://service.awardwallet.com/email/json/v2/mailboxes/scroll
GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/scroll
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tags |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma. |
states |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox |
types |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox |
errorCodes |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox |
emails |
array | true | This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as |
pageToken |
string | true | The value that you got in the |
Response Example
{
"items": [
{
"state": "listening",
"id": 1234,
"creationDate": "2018-08-03T20:09:49+0000",
"startFrom": "2018-07-16",
"listen": true,
"userData": "Testing the connection via the Google API",
"tags": [
"test",
"userid_1234"
],
"email": "john@gmail.com",
"type": "google",
"callbackUrl": "https://some.example.host/url1"
},
{
"state": "listening",
"id": 1235,
"creationDate": "2018-08-30T15:54:27+0000",
"startFrom": "2018-07-16",
"listen": true,
"userData": "Testing the connection via the Microsoft API",
"tags": [
"test",
"userid_1234"
],
"email": "john@hotmail.com",
"type": "microsoft",
"callbackUrl": "https://some.example.host/url2"
}
],
"nextPageToken": "abc"
}
Response
Parameter | Type | Required | Description |
---|---|---|---|
array | false | An array of Mailbox objects. |
|
nextPageToken |
string | false | Please pass this value to the next |
Disconnect Mailbox
This method allows you to remove a mailbox that was previously added for scanning.
Request
POST https://service.awardwallet.com/email/json/v2/mailboxes/disconnect/{mailboxId}
POST https://email-eu.awardwallet.com/email/json/v2/mailboxes/disconnect/{mailboxId}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
mailboxId | integer | true | This is the ID that you received from either one of the following methods: List Mailboxes ( |
revoke | boolean | false | Revoke tokens for oauth mailboxes, default false |
Response Example
"successfully deleted"
Itineraries
Flight
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 150,
"cost": 100,
"discount": 28.34,
"spentAwards": "3 segments",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 30
},
{
"name": "Seat selection",
"charge": 5.5
},
{
"name": "Baggage fee",
"charge": 14.5
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "delta",
"name": "Delta Air Lines",
"accountNumbers": [
{
"number": "1234****",
"masked": true
},
{
"number": "4321****",
"masked": true
}
],
"earnedRewards": "300 award miles"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Transfer shuttle will be located at the terminal exit",
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"airportCode": "LAX",
"terminal": "A",
"name": "Los Angeles International Airport",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "LAX",
"addressLine": "1 World Way",
"city": "Los Angeles",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": "90045",
"lat": 33.9415889,
"lng": -118.40853,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"arrival": {
"airportCode": "SFO",
"terminal": "2",
"name": "San Francisco International Airport",
"localDateTime": "2030-01-01T15:00:00",
"address": {
"text": "SFO",
"addressLine": "San Francisco International Airport",
"city": "San Francisco",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": null,
"lat": 37.615215,
"lng": -122.389881,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"marketingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"flightNumber": "0013",
"confirmationNumber": "MRTG67",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"isCodeshare": true
},
"operatingCarrier": {
"airline": {
"name": "British Airways",
"iata": "BA",
"icao": "BAW"
},
"flightNumber": "5566",
"confirmationNumber": "CARR23",
"phoneNumbers": [
{
"description": null,
"number": "+1-718-335-7070"
}
]
},
"wetleaseCarrier": {
"name": "Sky Express",
"iata": null,
"icao": null
},
"seats": [
"3E",
"3F"
],
"aircraft": {
"iataCode": "7M7",
"name": "Boeing 737MAX 7 Passenger",
"turboProp": false,
"jet": true,
"wideBody": false,
"regional": false,
"registrationNumber": "N345DL"
},
"traveledMiles": "300mi",
"cabin": "Coach",
"bookingCode": "CL",
"duration": "1h30min",
"meal": "Snacks",
"smoking": false,
"status": "Confirmed",
"stops": 0,
"flightStatsMethodUsed": "ScheduleByFlight"
},
{
"departure": {
"airportCode": "SFO",
"terminal": "2",
"name": "San Francisco International Airport",
"localDateTime": "2030-01-05T06:00:00",
"address": {
"text": "SFO",
"addressLine": "San Francisco International Airport",
"city": "San Francisco",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": null,
"lat": 37.615215,
"lng": -122.389881,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"arrival": {
"airportCode": "LAX",
"terminal": "A",
"name": "Los Angeles International Airport",
"localDateTime": "2030-01-05T07:30:00",
"address": {
"text": "LAX",
"addressLine": "1 World Way",
"city": "Los Angeles",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": "90045",
"lat": 33.9415889,
"lng": -118.40853,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"marketingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"flightNumber": "0014",
"confirmationNumber": "MRTG67",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"isCodeshare": true
},
"operatingCarrier": {
"airline": {
"name": "British Airways",
"iata": "BA",
"icao": "BAW"
},
"flightNumber": "9009",
"confirmationNumber": "CARR23",
"phoneNumbers": [
{
"description": null,
"number": "+1-718-335-7070"
}
]
},
"wetleaseCarrier": null,
"seats": [
"1B",
"1C"
],
"aircraft": {
"iataCode": "7M7",
"name": "Boeing 737MAX 7 Passenger",
"turboProp": false,
"jet": true,
"wideBody": false,
"regional": false,
"registrationNumber": "N345DL"
},
"traveledMiles": "300mi",
"cabin": "First class",
"bookingCode": "I",
"duration": "1h30min",
"meal": "Snacks",
"smoking": null,
"status": "Confirmed",
"stops": null,
"flightStatsMethodUsed": "ScheduleByAirport"
}
],
"issuingCarrier": {
"airline": {
"name": "Delta Air Lines",
"iata": "DL",
"icao": "DAL"
},
"confirmationNumber": "ISSD12",
"phoneNumbers": [
{
"description": null,
"number": "+1-404-714-2300"
}
],
"ticketNumbers": [
{
"number": "006 123321",
"masked": false
},
{
"number": "006 456654",
"masked": false
}
]
},
"type": "flight"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Names of the people listed on the reservation |
|
array | true | An array describing individual flight segments of the itinerary. |
|
object | false | Object that defines the airline that issued the ticket, could be the same as the |
Issuing Carrier
Any air ticket is always issued by some airline, this object defines the airline that actually issued the ticket.
Parameter | Type | Required | Description |
---|---|---|---|
object | false | Object describing the airline that issued the ticket. |
|
confirmationNumber |
string | false | PNR which corresponds to the airline that issued the ticket. |
array | false | In case if there are multiple travelers, all of their ticket numbers will be listed in this array. |
|
array | false | Contact phone numbers |
Flight Segment
Parameter | Type | Required | Description |
---|---|---|---|
object | true | An object describing the departure event such as the departing airport (code, name, address, etc.) as well as the time of the departure. |
|
object | true | An object describing the arrival event such as the arriving airport (code, name, address, etc.) as well as the time of the arrival. |
|
object | true | Object that defines the flight as it was ticketed. In other words, this is the information that the users would see on their ticket or boarding pass. |
|
object | false | If an email contains information about an “operating airline” that is different from the airline listed under the |
|
object | false | Wet lease airline is an airline that is DBA (doing business as) the operating airline. It wouldn’t have its own flight number or ticket numbers or confirmation numbers but you may see the wet lease airline listed on the ticket as “ExpressJet” or “KLM Cityhopper”, etc. |
|
seats |
array | false | Assigned passenger seats. |
object | false | Object defining the aircraft. |
|
traveledMiles |
string | false | Number of miles traveled on this flight segment, as we gathered it from the provider's website. |
calculatedTraveledMiles |
integer | false | Estimated number of miles traveled on this flight segment, calculated based on the destination and arrival airports |
cabin |
string | false | Cabin class, i.e. “Economy” |
bookingCode |
string | false | Booking class code, i.e. “T” |
duration |
string | false | Flight duration, as a string, as we gathered it from the provider’s website. Don’t expect to be able to use it programmatically to add or subtract time without some type of transformation on your end that would be specific to each provider. |
calculatedDuration |
integer | false | Flight duration in minutes, calculated based on the departure and arrival times |
status |
string | false | Status of the segment. I.e. cancelled, confirmed, etc. |
cancelled |
boolean | false | Will be set to “true” if this flight was canceled |
meal |
string | false | Meal, if any, that will be offered on the flight. |
smoking |
boolean | false | Most flights nowadays are non-smoking; however, in case if the airline identifies the flight as a smoking flight it would be identified in this field. |
stops |
integer | false | Number of stops this flight has. |
flightStatsMethodUsed |
string | false | If FlightStats API was called to retrieve some missing files that are not present in the email and are required for this flight segment the name of the FlightStats API call will be returned in this field. The possible values are:
|
Aircraft
Parameter | Type | Required | Description |
---|---|---|---|
iataCode |
string | false | Aircraft IATA code |
name |
string | true | Aircraft name |
turboProp |
boolean | false | Indicates if this is a turboprop aircraft |
jet |
boolean | false | Indicates if this is a jet engine aircraft |
wideBody |
boolean | false | Indicates if this is a wide-body aircraft |
regional |
boolean | false | Indicates if this is a regional aircraft |
registrationNumber |
string | false | Registration number of the aircraft |
Operating Carrier
Whenever the operating airline is different from the airline listed on the ticket (next to the flight number), that operating airline flight info would be listed in this object as the operating carrier. Don’t confuse this with a wet lease airline.
Parameter | Type | Required | Description |
---|---|---|---|
object | false | Object describing the operating airline if this airline is different from the one that was listed on the passenger’s ticket. |
|
flightNumber |
string | false | Operating airline flight number |
confirmationNumber |
string | false | PNR issued by the operating airline, in most cases will be unknown, i.e. |
array | false | Contact phone numbers |
Marketing Carrier
The flight and airline information as it shows up on the ticket.
Parameter | Type | Required | Description |
---|---|---|---|
object | true | Object describing the airline that is listed on the ticket, sometimes it is the 2 letter prefix that goes before the flight number as listed on the issued ticket. |
|
flightNumber |
string | true | Flight number that is listed on the passenger’s ticket. |
confirmationNumber |
string | false | Passenger name record, a.k.a. PNR that is associated with the airline the passenger was ticketed for. |
array | false | Airline phone numbers as shown in the email or the number(s) could be populated by AwardWallet automatically based on the airline even if the numbers were not present in the email. |
|
isCodeshare |
boolean | false | If this is a codeshare flight and we know the actual operating airline, we would set this attribute to |
Airline
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | Airline name |
iata |
string | false | IATA code of the airline |
icao |
string | false | International Civil Aviation Organization airline code. |
Flight Departure or Arrival
This object is describing the arrival or departure events of air travel.
Parameter | Type | Required | Description |
---|---|---|---|
airportCode |
string | true | If this location happened to be an airport this field will return a Validated IATA airport code. |
terminal |
string | false | In cases when terminal is known it will be returned in this field. |
name |
string | true | Train station name or airport name such as “John F. Kennedy International Airport”. |
localDateTime |
string | true | Local date and time of arrival or departure (depending on the type of this location). |
object | true | Object defining the address of this location. |
Address
Parameter | Type | Required | Description |
---|---|---|---|
text |
string | true | Non-validated address string. You can usually use this line to search some API (i.e. Google API) to get detailed / structured information about that address. We usually just grab this text as-is from the provider’s website. |
addressLine |
string | false | Validated address line of the address (without the city, state, country and zip code) that we got from either Google API or another authoritative source. |
city |
string | false | Name of the city validated either by Google API or another authoritative source |
stateName |
string | false | Name of the state validated either by Google API or another authoritative source |
countryName |
string | false | Name of the country validated either by Google API or another authoritative source |
countryCode |
string | false | 2 letter country code validated either by Google API or another authoritative source |
postalCode |
string | false | Zip / postal code validated either by Google API or another authoritative source |
lat |
number | false | Latitude coordinate of the address |
lng |
number | false | Longitude coordinate of the address |
timezone |
integer | false | Time zone in which this address is located. |
timezoneId |
string | false | Name of the time zone |
Person
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | Name of the person listed on the reservation. |
full |
boolean | false | Sometimes passenger or guest names are shortened on the reservation, if we are able to detect it, this field will reflect that. It will be set to |
type |
string | false |
Travel Agency
Parameter | Type | Required | Description |
---|---|---|---|
object | false | This object describes the travel agency, specifically the loyalty information as it pertains to this travel agency. |
|
array | false | Confirmation numbers that were assigned to this trip by the travel agency. Different from the PNRs assigned by the airline. |
|
array | false | Phone numbers of the travel agency. |
Phone Number
Parameter | Type | Required | Description |
---|---|---|---|
description |
string | false | Description of the phone number. |
number |
string | true | Phone number |
Confirmation Numbers
Parameter | Type | Required | Description |
---|---|---|---|
number |
string | true | Confirmation number |
description |
string | false | Confirmation number description |
isPrimary |
boolean | false | Indicates whether this confirmation number can be considered as primary |
Provider Info
If there is a loyalty program associated with this reservation, the details specific to that program will be listed in this object.
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | false | Loyalty program name |
code |
string | false | Alpha-numeric value with no spaces that uniquely identifies any given loyalty program within AwardWallet. |
array | false | Array of related loyalty program account numbers |
|
earnedRewards |
string | false | Rewards earned for booking the reservation |
Number
This object represents a ticket or an account number.
Parameter | Type | Required | Description |
---|---|---|---|
number |
string | true | Number as it was parsed from the email |
masked |
boolean | true | Will be set to |
Car Rental
Rental car reservation
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "avis",
"name": "Avis",
"accountNumbers": [
{
"number": "AVS454545",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "$50 penalty if cancelled",
"notes": "Make a note of any damages before leaving the pickup area",
"confirmationNumbers": [
{
"number": "1122334455",
"description": "Confirmation number",
"isPrimary": true
},
{
"number": "887756",
"description": "Reference",
"isPrimary": false
}
],
"pickup": {
"address": {
"text": "Palm Beach Intl Airport,PBI, 2500 Turnage Boulevard, West Palm Beach, FL 33406 US",
"addressLine": "1000 James L Turnage Boulevard",
"city": "West Palm Beach",
"stateName": "Florida",
"countryName": "United States",
"countryCode": "US",
"postalCode": "33415",
"lat": 26.6857475,
"lng": -80.0928165,
"timezone": -14400,
"timezoneId": "America/New_York"
},
"localDateTime": "2030-01-01T13:30:00",
"openingHours": "Sun - Sat open 24 hrs",
"phone": "+1-13-PICKUP",
"fax": "+1-14-FAX"
},
"dropoff": {
"address": {
"text": "Palm Beach Intl Airport,PBI, 2500 Turnage Boulevard, West Palm Beach, FL 33406 US",
"addressLine": "1000 James L Turnage Boulevard",
"city": "West Palm Beach",
"stateName": "Florida",
"countryName": "United States",
"countryCode": "US",
"postalCode": "33415",
"lat": 26.6857475,
"lng": -80.0928165,
"timezone": -14400,
"timezoneId": "America/New_York"
},
"localDateTime": "2030-01-05T13:30:00",
"openingHours": "Sun - Sat open 24 hrs",
"phone": "+1-13-DROPOFF",
"fax": "+1-14-FAX"
},
"car": {
"type": "Regular",
"model": "Ford Edge or similar",
"imageUrl": "http://car.image/url"
},
"discounts": null,
"driver": {
"name": "John Doe",
"full": true
},
"pricedEquipment": null,
"rentalCompany": null,
"type": "carRental"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
object | true | Object defining the pickup event (time and location) of the rental car. |
|
object | true | Object defining the dropoff event (time and location) of the rental car. |
|
object | false | Object defining the rental car. |
|
array | false | An array of various discounts that were applied to the reservation. |
|
object | false | Object describing the driver of the car. |
|
array | false | An array of additional equipment that was added to the reservation. |
|
rentalCompany |
string | false | Name of the rental company. |
Car Rental Discount
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | Discount name, such as “Your Rate has been discounted based on the Hertz CDP provided”. |
code |
string | true | Discount code, such as “AAA SOUTHERN NEW ENGLAND” |
Car
Parameter | Type | Required | Description |
---|---|---|---|
type |
string | false | Type of the rental car, i.e. “Intermediate SUV”. |
model |
string | false | Model of the rental car, i.e. “Ford Escape or similar”. |
imageUrl |
string | false | URL of the image of the car. |
Car Rental Location
Pickup or drop off location of the rental car.
Parameter | Type | Required | Description |
---|---|---|---|
object | true | Rental car facility address. |
|
localDateTime |
string | true | Scheduled date and time of the car pickup or drop-off in the time zone of the location of the rental car facility. |
openingHours |
string | false | Rental car facility hours of operation. |
phone |
string | false | Rental car facility phone number. |
fax |
string | false | Rental car facility fax number. |
Hotel Reservation
Hotel reservation
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 300,
"cost": 200,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 100
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "spg",
"name": "Starwood Hotels",
"accountNumbers": [
{
"number": "xxxxxx345",
"masked": true
}
],
"earnedRewards": "4 nights"
},
"cancelled": false,
"cancellationPolicy": "Cancellation is free 24 hours prior to check-in",
"cancellationDeadline": "2029-12-31T13:30:00",
"isNonRefundable": null,
"notes": "Use the secondary entrance if you're carrying large luggage",
"confirmationNumbers": [
{
"number": "1122334455",
"description": "Confirmation number",
"isPrimary": true
},
{
"number": "887756",
"description": "Reference",
"isPrimary": false
}
],
"hotelName": "Sheraton Philadelphia Downtown Hotel",
"chainName": null,
"address": {
"text": "201 North 17th Street, Philadelphia, Pennsylvania 19103 United States",
"addressLine": "201 North 17th Street",
"city": "Philadelphia",
"stateName": "Pennsylvania",
"countryName": "United States",
"countryCode": "US",
"postalCode": "19103",
"lat": 39.9569828,
"lng": -75.1674669,
"timezone": -14400,
"timezoneId": "America/New_York"
},
"checkInDate": "2030-01-01T13:30:00",
"checkOutDate": "2030-01-05T12:00:00",
"phone": "+1-22-3333",
"fax": "+1-66-77899",
"guests": [
{
"name": "John D.",
"full": false
},
{
"name": "Jane D.",
"full": false
}
],
"guestCount": 2,
"kidsCount": 3,
"roomsCount": 1,
"rooms": [
{
"type": "King bed",
"description": "Traditional, TV, free wi-fi",
"rate": "30$/night",
"rateType": "King bed"
}
],
"type": "hotelReservation"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
cancellationNumber |
string | false | Cancellation number if the reservation has been cancelled |
cancellationDeadline |
string | false | Deadline date for changing or cancelling the reservation without additional penalties |
isNonRefundable |
boolean | false | Set to |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
hotelName |
string | true | Name of the hotel, i.e. “Hilton Garden Inn Atlanta Perimeter Center” |
chainName |
string | false | Name of the hotel chain. |
object | true | An object describing all the details of the address of the hotel. |
|
checkInDate |
string | true | Check-in date. |
checkOutDate |
string | true | Check-out date. |
phone |
string | false | Hotel’s phone number. |
fax |
string | false | Hotel’s fax number. |
array | false | An array describing guests that are listed on the reservation. |
|
guestCount |
integer | false | Number of guests on the reservation. |
kidsCount |
integer | false | Number of kids listed on the reservation. |
roomsCount |
integer | false | Number of rooms listed on the reservation. |
array | false | An array describing the room(s) listed on the reservation. |
|
freeNights |
integer | false | Number of free nights obtained via a certificate or a promo |
Room
Parameter | Type | Required | Description |
---|---|---|---|
type |
string | false | Room type, i.e. “2 QUEEN BEDS NONSMOKING” |
description |
string | false | Room description, i.e. “Non-Smoking Room Confirmed” |
rate |
string | false | Room rate per night. |
rateType |
string | false | Room rate type, i.e. “2 QUEEN BEDS NONSMOKING”. |
Bus
Bus ride
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "boltbus",
"name": "BoltBus",
"accountNumbers": [
{
"number": "BB3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Keep your ticket at your person at all times",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"scheduleNumber": "2023",
"departure": {
"stationCode": null,
"name": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
"addressLine": "700 Atlantic Avenue",
"city": "Boston",
"stateName": "Massachusetts",
"countryName": "United States",
"countryCode": "US",
"postalCode": "02111",
"lat": 42.3504505,
"lng": -71.0561242,
"timezone": -14400,
"timezoneId": "America/New_York"
}
},
"arrival": {
"stationCode": null,
"name": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
"localDateTime": "2030-01-01T20:34:00",
"address": {
"text": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": null,
"lng": null,
"timezone": null,
"timezoneId": null
}
},
"busInfo": {
"type": "Regular",
"model": "Mercedes"
},
"seats": [
"11",
"12"
],
"traveledMiles": "43mi",
"cabin": null,
"bookingCode": null,
"duration": "7h",
"meal": null,
"smoking": null,
"stops": null
}
],
"ticketNumbers": [
{
"number": "345667",
"masked": false
},
{
"number": "345668",
"masked": false
}
],
"type": "bus"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
array | false | Names of the people listed on the reservation |
|
type |
string | true | Type of reservation. Value: |
array | true | An array describing individual travel segments of the itinerary. |
|
array | false | There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field. |
Bus segment
Parameter | Type | Required | Description |
---|---|---|---|
scheduleNumber |
string | false | ScheduleNumber is similar in concept to FlightNumber but applicable to Trains or Busses, etc. So it is designed to define a route number for various types of transportation itineraries. |
object | true | An object describing the departure event of this trip segment, such as a bus stop location and the time of departure. |
|
object | true | An object describing the arrival event of this trip segment, such as a bus stop location and the time of arrival. |
|
object | false | And object describing the bus |
|
seats |
array | false | Assigned passenger seats. |
traveledMiles |
string | false | Number of miles traveled on this segment. |
cabin |
string | false | Cabin class, i.e. “Economy” |
bookingCode |
string | false | Booking class code, i.e. “SL” for “Sleeper class” booking code. |
duration |
string | false | Trip duration |
meal |
string | false | Meal, if any, that will be offered on the train, ferry, bus, etc. |
smoking |
boolean | false | Most transporation services nowadays are non-smoking; however, in case if the provider identifies the car / train / bus as smoking it would be listed in this field. |
stops |
integer | false | Number of stops this transportation segment has. |
Vehicle
This object describes the vehicle used to trasport a passenger
Parameter | Type | Required | Description |
---|---|---|---|
type |
string | false | Short description |
model |
string | false | Model of the vehicle |
Transportation Departure or Arrival
This object describes the transportation departure and arrival events
Parameter | Type | Required | Description |
---|---|---|---|
stationCode |
string | false | This attribute shows the bus station or train station or port code as it shows up on the email. This field is not validated. |
name |
string | true | Station or location name |
localDateTime |
string | true | Local date and time of arrival or departure (depending on the type of this location). |
object | true | Object defining the address of this location. |
Train
Train ride
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "amtrak",
"name": "Amtrak",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Taxi will be waiting for you in the parking area",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"stationCode": "BBSS",
"name": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "Boston South Station - Gate 9 NYC-Gate 10 NWK\\/PHL",
"addressLine": "700 Atlantic Avenue",
"city": "Boston",
"stateName": "Massachusetts",
"countryName": "United States",
"countryCode": "US",
"postalCode": "02111",
"lat": 42.3504505,
"lng": -71.0561242,
"timezone": -14400,
"timezoneId": "America/New_York"
}
},
"arrival": {
"stationCode": "NNYW",
"name": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
"localDateTime": "2030-01-01T20:34:00",
"address": {
"text": "New York W 33rd St & 11-12th Ave (DC,BAL,BOS,PHL)",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": null,
"lng": null,
"timezone": null,
"timezoneId": null
}
},
"scheduleNumber": "2023",
"serviceName": "Amtrak Express",
"trainInfo": {
"type": "Regular",
"model": null
},
"car": "4",
"seats": [
"11",
"12"
],
"traveledMiles": "43mi",
"cabin": "coach",
"bookingCode": null,
"duration": "7h",
"meal": null,
"smoking": null,
"stops": null
}
],
"ticketNumbers": [
{
"number": "345667",
"masked": false
},
{
"number": "345668",
"masked": false
}
],
"type": "train"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
array | false | Names of the people listed on the reservation |
|
type |
string | true | Type of reservation. Value: |
array | true | An array describing individual travel segments of the itinerary. |
|
array | false | There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field. |
Train segment
Parameter | Type | Required | Description |
---|---|---|---|
scheduleNumber |
string | false | ScheduleNumber is similar in concept to FlightNumber but applicable to Trains or Busses, etc. So it is designed to define a route number for various types of transportation itineraries. |
object | true | An object describing the departure event of this trip segment, such as a train station and the time of departure. |
|
object | true | An object describing the arrival event of this trip segment, such as a train station and the time of arrival. |
|
serviceName |
string | false | Short name of the particular service or route |
object | false | And object describing the train |
|
car |
string | false | Train car number. |
seats |
array | false | Assigned passenger seats in a car |
traveledMiles |
string | false | Number of miles traveled on this segment. |
cabin |
string | false | Cabin class, i.e. “Economy” |
bookingCode |
string | false | Booking class code, i.e. “SL” for “Sleeper class” booking code. |
duration |
string | false | Trip duration |
meal |
string | false | Meal, if any, that will be offered on the train, ferry, bus, etc. |
smoking |
boolean | false | Most transporation services nowadays are non-smoking; however, in case if the provider identifies the car / train / bus as smoking it would be listed in this field. |
stops |
integer | false | Number of stops this transportation segment has. |
array | false | Array of links to train tickets or boarding passes for this segment |
Link to a ticket or a boarding pass
Parameter | Type | Required | Description |
---|---|---|---|
link |
string | false | Link to a downloadable ticket, which is usually a PDF file with a QR code |
name |
string | false | Name of the ticket owner |
Transfer
Car or shuttle bus ride
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "uber",
"name": "Uber.com",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "You may be asked to provide an ID",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"airportCode": "SFO",
"name": "San Francisco International Airport",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "SFO",
"addressLine": "San Francisco International Airport",
"city": "San Francisco",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": null,
"lat": 37.615215,
"lng": -122.389881,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"arrival": {
"airportCode": null,
"name": "315 Walnut Ave, South San Francisco, CA 94080, USA",
"localDateTime": "2030-01-01T14:34:00",
"address": {
"text": "315 Walnut Ave, South San Francisco, CA 94080, USA",
"addressLine": "315 Walnut Avenue",
"city": "South San Francisco",
"stateName": "California",
"countryName": "United States",
"countryCode": "US",
"postalCode": "94080",
"lat": 37.6569251,
"lng": -122.4143844,
"timezone": -25200,
"timezoneId": "America/Los_Angeles"
}
},
"vehicleInfo": {
"type": "Regular",
"model": "Ford Focus",
"imageUrl": "http://car.image/url"
},
"adults": 1,
"kids": 0,
"traveledMiles": "4.3mi",
"duration": "7h"
}
],
"type": "transfer"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
array | false | Names of the people listed on the reservation |
|
type |
string | true | Type of reservation. Value: |
array | true | An array describing individual travel segments of the itinerary. |
Transfer segment
Parameter | Type | Required | Description |
---|---|---|---|
object | true | An object describing the departure event of this trip segment, such as an address or an airport and the time of departure. |
|
object | true | An object describing the arrival event of this trip segment, such as an address or an airport and the time of arrival. |
|
object | false | And object describing the vehicle |
|
adults |
integer | false | |
kids |
integer | false | |
traveledMiles |
string | false | Number of miles traveled on this segment. |
duration |
string | false | Trip duration |
Transfer Departure or Arrival
This object describes the transfer departure and arrival events
Parameter | Type | Required | Description |
---|---|---|---|
airportCode |
string | false | Iata code of an airport. |
name |
string | true | Location name |
localDateTime |
string | true | Local date and time of arrival or departure (depending on the type of this location). |
object | true | Object defining the address of this location. |
Cruise
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "disneycruise",
"name": "Disney Cruise Line",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Do not forget to check in with the receptionist at the main deck",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"stationCode": null,
"name": "PORT CANAVERAL",
"localDateTime": "2030-01-01T13:30:00",
"address": {
"text": "PORT CANAVERAL",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": null,
"lng": null,
"timezone": null,
"timezoneId": null
}
},
"arrival": {
"stationCode": null,
"name": "NASSAU",
"localDateTime": "2030-01-02T08:00:00",
"address": {
"text": "NASSAU",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": 25.0479835,
"lng": -77.355413,
"timezone": -14400,
"timezoneId": "America/Nassau"
}
}
},
{
"departure": {
"stationCode": null,
"name": "NASSAU",
"localDateTime": "2030-01-02T12:00:00",
"address": {
"text": "NASSAU",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": 25.0479835,
"lng": -77.355413,
"timezone": -14400,
"timezoneId": "America/Nassau"
}
},
"arrival": {
"stationCode": null,
"name": "PORT CANAVERAL",
"localDateTime": "2030-01-03T14:00:00",
"address": {
"text": "PORT CANAVERAL",
"addressLine": null,
"city": null,
"stateName": null,
"countryName": null,
"countryCode": null,
"postalCode": null,
"lat": null,
"lng": null,
"timezone": null,
"timezoneId": null
}
}
}
],
"cruiseDetails": {
"description": "Long cruise",
"class": "Regular",
"deck": "3",
"room": "342",
"ship": "Disney Dream",
"shipCode": "SHCD",
"voyageNumber": "K229"
},
"type": "cruise"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
array | false | Names of the people listed on the reservation |
|
array | true | An array describing individual travel segments of the itinerary. |
|
object | false | Cruise Details |
Cruise Details
Parameter | Type | Required | Description |
---|---|---|---|
description |
string | false | Cruise description, such as “7-Day Eastern Caribbean from Orlando (Port Canaveral)” |
class |
string | false | Room class |
deck |
string | false | Name of the deck, i.e. “The Haven Stateroom” |
room |
string | false | Room number |
ship |
string | false | The name of the ship, i.e. “Norwegian Epic” |
shipCode |
string | false | This is usually a two-letter code that identifies the ship |
voyageNumber |
string | false | Voyage number |
Cruise Segment
Parameter | Type | Required | Description |
---|---|---|---|
object | true | Object describing the departure port |
|
object | true | Object describing the arrival port |
Event
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "opentable",
"name": "OpenTable.com",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Receipt will be available in your mobile application",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"address": {
"text": "132 West 58th Street New York, NY 10019",
"addressLine": "132 West 58th Street",
"city": "New York",
"stateName": "New York",
"countryName": "United States",
"countryCode": "US",
"postalCode": "10019",
"lat": 40.7653771,
"lng": -73.9779742,
"timezone": -14400,
"timezoneId": "America/New_York"
},
"eventName": "Loi Estiatorio",
"eventType": 1,
"startDateTime": "2030-01-01T18:00:00",
"endDateTime": "2030-01-01T23:00:00",
"phone": "+1-23-44556",
"fax": "+1-99-33434",
"guestCount": 2,
"guests": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"seats": [
"table 13"
],
"type": "event"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
object | true | The address of the event. |
|
eventName |
string | true | Event name such as the name of the restaurant. |
eventType |
integer | true | Type of the event. The possible values are: 1 - for “Restaurant” 2 - for “Meeting” 3 - for “Show” 4 - for “Event” |
startDateTime |
string | true | Date and time when the event starts. |
endDateTime |
string | false | Date and time when the event ends. |
phone |
string | false | Phone number associated with the event, such as restaurant’s phone number. |
fax |
string | false | Fax number associated with the event, such as show organizer’s fax number. |
guestCount |
integer | false | Number of guests participating in the event. |
array | false | Arrays of guests participating in the event. |
|
seats |
array | false | Array of reserved seats |
Parking
Parking spot reservations (usually for airport long-term parking)
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 105.15,
"cost": 99.12,
"discount": null,
"spentAwards": null,
"currencyCode": "USD",
"fees": [
{
"name": "Taxes",
"charge": 6.03
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "parkingspot",
"name": "The Parking Spot",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Look at the overhead signs for directions to the desired spot",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Transcation number",
"isPrimary": true
},
{
"number": "887756",
"description": "Invoice number",
"isPrimary": false
}
],
"address": {
"text": "132 West 58th Street New York, NY 10019",
"addressLine": "132 West 58th Street",
"city": "New York",
"stateName": "New York",
"countryName": "United States",
"countryCode": "US",
"postalCode": "10019",
"lat": 40.7653771,
"lng": -73.9779742,
"timezone": -14400,
"timezoneId": "America/New_York"
},
"locationName": "Downtown 2 hr",
"spotNumber": "4",
"licensePlate": "ABC GHY",
"startDateTime": "2030-01-01T18:00:00",
"endDateTime": "2030-01-01T23:00:00",
"phone": "+1-234-56789",
"owner": {
"name": "John Doe",
"full": true
},
"rateType": "STANDARD SPOT",
"carDescription": "Volkswagen white",
"type": "parking"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
type |
string | true | Type of reservation. Value: |
array | false | Reservation confirmation number(s) specific to the parking provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
object | false | The address of the parking location. |
|
locationName |
string | false | Parking location name. |
spotNumber |
string | false | Parking spot number. |
licensePlate |
string | false | Licanse plate. |
startDateTime |
string | true | Parking start date and time. |
endDateTime |
string | true | Parking end date and time. |
phone |
string | false | Parking facility phone number. |
object | false | Car owner's name. |
|
rateType |
string | false | Rate type. |
carDescription |
string | false | Information about the parked vehicle |
Ferry
Example
{
"itineraries": [
{
"travelAgency": null,
"pricingInfo": {
"total": 251.41,
"cost": 193.75,
"discount": 40,
"spentAwards": "10000 points",
"currencyCode": "USD",
"fees": [
{
"name": "Tax",
"charge": 34.56
},
{
"name": "Insurance",
"charge": 23.1
}
]
},
"status": "Confirmed",
"reservationDate": "2000-01-01T00:00:00",
"providerInfo": {
"code": "aferry",
"name": "AFerry",
"accountNumbers": [
{
"number": "AM3398",
"masked": false
}
],
"earnedRewards": "50 points"
},
"cancelled": false,
"cancellationPolicy": "Ticket is non-refundable",
"notes": "Access to your vehicle will be restricted during the trip",
"confirmationNumbers": [
{
"number": "A04-33984-12",
"description": "Confirmation #",
"isPrimary": true
},
{
"number": "887756",
"description": "Transaction number",
"isPrimary": false
}
],
"travelers": [
{
"name": "John Doe",
"full": true
},
{
"name": "Jane Doe",
"full": true
}
],
"segments": [
{
"departure": {
"stationCode": "NO OSL",
"name": "Oslo, Norway",
"localDateTime": "2030-01-01T14:00:00",
"address": {
"text": "Akershusstranda 19, 0102 Oslo, Norway",
"addressLine": "Akershusstranda 19",
"city": "Oslo",
"stateName": null,
"countryName": "Norway",
"countryCode": "NO",
"postalCode": "0102",
"lat": 59.904139,
"lng": 10.738278,
"timezone": null,
"timezoneId": null
}
},
"arrival": {
"stationCode": "DEKEL",
"name": "Kiel, Germany",
"localDateTime": "2030-01-02T10:00:00",
"address": {
"text": "Norwegenkai, 24143 Kiel, Germany",
"addressLine": null,
"city": "Kiel",
"stateName": null,
"countryName": "Germany",
"countryCode": "DE",
"postalCode": null,
"lat": 54.316333,
"lng": 10.138806,
"timezone": null,
"timezoneId": null
}
},
"accommodations": [
"4-Bed inside cabin, shower/WC",
"4-Bed inside cabin, shower/WC"
],
"carrier": "ANEK SUPERFAST",
"vessel": "Hellenic Spirit",
"traveledMiles": "10km",
"duration": "2h",
"meal": "none",
"cabin": "economy",
"smoking": false,
"adultsCount": 2,
"kidsCount": 1,
"pets": "1 cat",
"vehicles": [
{
"type": "Auto",
"model": "Audi",
"length": "<5m",
"height": "1.8",
"width": "1.8-3m"
}
],
"trailers": [
{
"type": "Regular",
"model": "Standard",
"length": "<=2m",
"height": "<=2",
"width": "<=2"
}
]
}
],
"ticketNumbers": [
{
"number": "345667",
"masked": false
},
{
"number": "345668",
"masked": false
}
],
"type": "ferry"
}
]
}
Parameter | Type | Required | Description |
---|---|---|---|
object | false | If this reservation was booked through a travel agency this object would define the properties of that travel agency. |
|
object | false | An object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc. |
|
status |
string | false | Status of the reservation. I.e. cancelled, confirmed, etc. |
reservationDate |
string | false | Date when the reservation was booked |
object | false | This object describes the provider, specifically the loyalty information as it pertains to this provider. |
|
cancelled |
boolean | false | Indicates whether this itinerary has been cancelled. Cancelled reservations may not contain all required data. |
cancellationPolicy |
string | false | Cancelation policy of this specific reservation. |
notes |
string | false | This field may contain additional information which may be helpful to the traveler. It may include notes from the travel agent, such as meeting or pickup instructions. |
array | false | Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the |
|
array | false | Names of the people listed on the reservation |
|
type |
string | true | Type of reservation. Value: |
array | true | An array describing individual travel segments of the itinerary. |
|
array | false | There may be different ticket numbers associated with an itinerary. All the ticket numbers that we gather would be presented as an array in this field. |
Ferry segment
Parameter | Type | Required | Description |
---|---|---|---|
carrier |
string | false | The name of the company operating the ferry. |
vessel |
string | false | Name or type of the vessel / ferry. |
object | true | An object describing the departure event of this trip segment, such as a port and the time of departure. |
|
object | true | An object describing the arrival event of this trip segment, such as a port and the time of arrival. |
|
adultsCount |
integer | false | Number of adults listed on the reservation. |
kidsCount |
integer | false | Number of kids listed on the reservation. |
pets |
string | false | Information about the pets listed on the ticket. |
accommodations |
array | false | Assigned passenger accommodations on a ferry |
traveledMiles |
string | false | Number of miles traveled on this segment. |
duration |
string | false | Trip duration. |
meal |
string | false | Meal, if any, that will be offered on the ferry. |
cabin |
string | false | Cabin class, i.e. “Economy” |
smoking |
boolean | false | If accomodation is identified as a smoking place it would be identified in this field. |
array | false | An array describing the vehicle(s) listed on the reservation. |
|
array | false | An array describing the trailer(s) listed on the reservation. |
Vehicle or Trailer
This object describes a vehicle/trailer
Parameter | Type | Required | Description |
---|---|---|---|
type |
string | false | Short description |
model |
string | false | Model of the vehicle/trailer |
length |
string | false | Length of the vehicle/trailer (size description, includes number, e.g. "Less than 6.00 metres") |
height |
string | false | Height of the vehicle/trailer (size description, includes number, e.g. "Less than 1.80 metres") |
width |
string | false | Width of the vehicle/trailer (size description, includes number.) |
Errors
Error Code | Meaning |
---|---|
400 | Bad Request |
401 | Unauthorized – Your API key is wrong |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed – You tried to access an API with an invalid method |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable |