How to call the MyGuestlist API

The MyGuestlist API leverages a HTTPS request architecture. All functions are called using a series of HTTP requests to a specific URI.

You must pass a valid API key to most methods of the MyGuestlist API. You can do this by using the following URI syntax.

https://api.myguestlist.com/v1/API KEY/METHOD

Campaigns

The MyGuestlist API allows you to programatically send SMS and Email messages to contacts stored in MyGuestlist.

The following features are supported.

Sending Email /email

Description: Sends an email to the specified email address.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/email
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
to_name string Name of the recipient Jon Snow
to_email email Email address of the recipient jon@winterfel.gov
from_name string The name of the sender King's Landing News
from_email email The email address of the sender kingslanding@marketing.lanister.com
html html The message body of the email in HTML format
subject string The email subject line What's on this month at King's Landing
reference_id string A unique ID for the message. Must be less than 42 characters. kingsenews001
send_at datetime An ISO-8601 datetime string when to send this message. If omitted, sends immediately. 2017-04-01 23:00:00

Mail Merge Tokens

You may place the following mail merge tokens in the html of your message.

Token Description
#unsubscribe# Replaced with a URL to unsubscribe the contact. If your message does not contain this token, it will be automatically added to the footer of your message.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/email",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King's%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What's%20on%20this%20month%20at%20King's%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/email \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King'\''s%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What'\''s%20on%20this%20month%20at%20King'\''s%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00'                                            
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/email',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King\'s%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What\'s%20on%20this%20month%20at%20King\'s%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Message Queued For Delivery"
}
{
    "result": false,
    "message": "Unable To Queue Message"
}

Handling Errors

If for any reason your message could not be sent, the result Parameter returned to you will be false. The message may give you a better understanding why your message failed.

Message Reason
Insufficient Credits The MyGuestlist account does not have enough Email credits to send this message. The owner must sign in to MyGuestlist and purchase more credits.
Unable to allocate credits
Error Sending Email - Invalid Reference ID The reference_id you used in this request is invalid
Unable To Queue Message There was an error queing the message for delivery. Try again later.

Sending SMS /sms

Description: Sends an SMS to the specified phone number.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sms
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
from string An alphanumeric string for the from name/number of this message. Maximum 11 characters. Whitespace characters (such as a space) are not permitted. 0412312312
to number The phone number of the SMS recipient 0400000000
message string The message contents of the SMS Tonight sees the return of the famous Ned Stark! STOP #unsubscribe#
reference_id string A unique ID for the message. Must be less than 42 characters. kingsenews002
send_at datetime An ISO-8601 datetime string when to send this message. If omitted, sends immediately. 2017-04-01 23:00:00

Mail Merge Tokens

You may place the following mail merge tokens in the message of your SMS.

Token Description
#reply# Replaced with a phone number to allow for two-way SMS. This must be placed in the from field. See SMS Inbox for more information.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/sms \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Message Queued For Delivery"
}
{
    "result": false,
    "message": "Message contains invalid characters"
}

Handling Errors

If for any reason your message could not be sent, the result Parameter returned to you will be false. The message may give you a better understanding why your message failed.

Message Reason
Insufficient Credits The MyGuestlist account does not have enough Email credits to send this message. The owner must sign in to MyGuestlist and purchase more credits.
Reference ID not found You did not supply a reference_id to this endpoint.
Error Sending SMS - Invalid Reference ID The reference_id you used in this request is invalid
Unable To Queue Message There was an error queing the message for delivery. Try again later.
Message contains invalid characters The SMS you are trying to send contains invalid characters, such as accented characters used in languages other than English.
Invalid recipient details The recipient phone number you provided is invalid.

Sent Campaigns /sent_items

Description: Retrieve the messages that have been sent out via this account.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sent_items
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
date_start datetime An ISO-8601 datetime string to start searching from. 2017-04-01 23:00:00
date_end datetime An ISO-8601 datetime string to stop searching at. 2017-04-01 23:00:00
prefix string A prefix of a reference_id to search for. kings
reference_id string Only return items sent with this reference_id kingsenews002
type string The type of message sent. Can be either email, social or sms. email

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Sent items",
    "data": [
        {
            "reference_id": "kingsenews002",
            "type": "sms",
            "timestamp": "2017-04-01 23:00:00",
            "count": 1,
            "message": "Tonight sees the return of the famous Ned Stark! STOP #unsubscribe#",
            "from_name": "0412312312",
            "count_optout": 0
        },
        {
            "reference_id": "kingsenews001",
            "type": "email",
            "timestamp": "2017-04-01 23:00:00",
            "count": 1,
            "message": "message content",
            "from_name": "King's Landing News",
            "subject": "What's on this month at King's Landing",
            "count_open": 1,
            "count_optout": 0,
            "count_auto_optout": 0,
            "count_bounced": 0,
            "count_spam": 0,
            "count_optout": 0
        }

    ]
}
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Contacts

The MyGuestlist API allows you to get or update contacts stored in MyGuestlist.

The following features are supported.

Getting Contact Fields /get_contact_fields

Description: The get_contact_fields method allows your system to retrieve the client’s field names within MyGuestlist for field to field mapping between the two systems.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/get_contact_fields
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
expand boolean If set to true, the return will contain additional field details including the field type, and any applicable options for that field for single or multiple select field types. true

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"client_id\": \"abc123\", \"expand\": true}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields?=' \
  --header 'content-type: application/json' \
  --data '{"client_id": "abc123", "expand": true}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"client_id": "abc123", \"expand\": true}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "fields": [
        "PatronEmail", 
        "PatronMobile", 
        "PatronName", 
        "FavouriteColour"
    ]
}
{
    "fields": [
        {
            "name": "PatronEmail", 
            "type": "string"
        },
        {
            "name": "PatronMobile", 
            "type": "string"
        },
        {
            "name": "PatronName", 
            "type": "string"
        },
        {
            "name": "FavouriteColour", 
            "type": "singleSelect",
            "options": [
                "Green",
                "Red",
                "Blue"
            ]
        }
    ]
}
{
    "result": false,
    "message": "No client ID provided"
}

Available Field Types

MyGuestlist has support for multiple field types, which may be exposed by setting the expand parameter in your request. The following field types are available in MyGuestlist.

Type Description
string A single line text field.
text A multi-line text field.
number A field which only accepts numbers.
date A date field which does not include a time component. Format: yyyy-mm-dd
time A time field which does not include a date component. Format: hh:mm:ss (24 hour format)
datetime A date and time field. Format: yyyy-mm-dd hh:mm:ss
singleSelect A field which only allows selection of one option available in a list. This is normally rendered as a radio button or dropdown.
multipleSelect A field which allows selection of one or more option(s) available in a list. This is normally rendered as a series of checkboxes.
bool A field that only accepts a true or false value.
Sex A field that only accepts a m or f value. Used to denote the Gender of the user

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.

Getting Contacts /pull_db

Description: The pull_db method provides the ability to extract the entire database or any new and updated records from the database within MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/pull_db
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
touched_from datetime Filter the data by retrieving records inserted or updated from the specified date and time. The parameter is optional and can be set without the touched_to field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
touched_to datetime Filter the data by retrieving records inserted or updated to the specified date and time. The parameter is optional and can be set without the touched_from field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
member_id string Filter the data by retrieving records based on POSMemberNumber. The parameter is optional. acb123
MemberNumber string Filter the data by retrieving records based on Member Number. The parameter is optional. acb123
PatronEmail string Filter the data by retrieving records based on the contacts email address. The parameter is optional. bob@mgl.com.au
PatronMobile string Filter the data by retrieving records based on the contacts mobile number. The parameter is optional. 0420987765
PatronName string Filter the data by retrieving contacts that match the first name specified. The parameter is optional. Miranda
CardNumber string Filter the data by retrieving contacts that match the Card Number specified. The parameter is optional. acb123
PatronSurname string Filter the data by retrieving records based on last name of patron. The parameter is optional. abc
Heads Up

Excluding the touched_from and touched_to parameters from the request will retrieve the entire client’s MyGuestlist database. The request may timeout if the database is large.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"touched_from\": \"2017-04-30 23:00:00\", \"touched_to\": \"2017-04-30 23:30:00\", \"client_id\": \"abc123\"}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db?=' \
  --header 'content-type: application/json' \
  --data '{
"touched_from": "2017-04-30 23:00:00", 
"touched_to": "2017-04-30 23:30:00", 
"client_id": "abc123"
}
'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}\n' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

[
   {
      "client_id":"abc123",
      "contact_id":"6jg8hfg5v6",
      "mgl_categories":"VIP, Members",
      custom contact fields...
   },
   {
      "client_id":"abc123",
      "contact_id":"6jg8hfg5v7",
      "mgl_categories":"Members",
      custom contact fields...
   }
]
{
    "result": false,
    "message": "No client ID provided"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.

Adding Contacts /push_contact

Description: The push_contact method provides the ability to insert and update the database within MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/push_contact
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

This endpoint expects a JSON array of objects containing the following fields.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. Only supply this if you know the MyGuestlist contact record you need to update, otherwise MyGuestlist will handle this for you. 6fs63hthg
mgl_categories string A comma separated list of categories to assign the contact to within MyGuestlist. If a category doesn’t exist it will be created. VIP, Members
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method
Heads Up

As this function provides the ability to sync between the MyGuestlist database and your system/application, validation of the custom contact fields will not occur during the load so the data is consistent between the two databases. The data is assumed to be validated within your system/application.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"client_id\": \"abc123\",\"contact_id\": \"6fs63hthg\",\"mgl_categories\": \"VIP,Members\",\"PatronName\": \"Jon Snow\",\"PatronEmail\": \"jon@winterfel.gov\"}]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact?=' \
  --header 'content-type: application/json' \
  --data '[
    {
        "client_id": "abc123",
        "contact_id": "6fs63hthg",
        "mgl_categories": "VIP,Members",
        "PatronName": "Jon Snow",
        "PatronEmail": "jon@winterfel.gov"
    }
]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"client_id": "abc123","contact_id": "6fs63hthg","mgl_categories": "VIP,Members","PatronName": "Jon Snow","PatronEmail": "jon@winterfel.gov"}]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "abc123", 
            "contact_id": "6fs63hthg"
        }     
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
No such contact in MyGuestlist database The contact_id in your request does not exist in MyGuestlist.
No contact information to add/update There isn't enough information to update this contact.
No email or mobile information You must supply at least a PatronEmail or PatronMobile to add a contact to MyGuestlist.
Duplicate check failed The contact you have provided would cause a duplicate contact to be created in MyGuestlist.
New contact add failed There was an error adding this new contact to MyGuestlist.
Update contact failed There was an error updating this contact in MyGuestlist.

Purchases

The MyGuestlist API allows you to add purchase data against contacts in MyGuestlist.

The following features are supported.

Adding Purchases /add_purchase

Description: The add_purchase method provides the ability to sync basic transaction and purchase data between the MyGuestlist and your applications databases. This gives your application users the ability to market to customers based on the purchases made.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/add_purchase
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
tx_id string The transaction ID to group the items purchased in one transaction. If one is not present one will be created on the fly within the MyGuestlist database. 1234
item_cat string The category this purchase belongs to.
item_dep string The department this purchase belongs to.
item_store string The store or location this purchase was made at. Melbourne City
item_brand string The brand or trading name this purchase was made at.
item_code string The code representation of the item purchased.
item_desc string The string representation of the item purchased.
item_adj string The adjustment applied to the item purchased.
item_qty number The quantity purchased. If left blank it will be set to 1. 12
price number The total price paid for the item(s). 147.99
purchased_at datetime The date and time the item was purchased at in ISO-8601 format. 2017-04-01 23:00:00

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"client_id\": \"abc123\", \"contact_id\": \"6fs63hthg\", \"tx_id\": \"5678\", \"item_cat\": \"Beer\", \"item_dep\": \"Imported\", \"item_code\": \"12344\", \"item_desc\": \"Tiger\", \"item_qty\": 3, \"price\": \"27.00\", \"purchased_at\": \"2017-04-30 23:00:00\" }]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase?=' \
  --header 'content-type: application/json' \
  --data '[{"client_id": "abc123", "contact_id": "6fs63hthg", "tx_id": "5678", "item_cat": "Beer", "item_dep": "Imported", "item_code": "12344", "item_desc": "Tiger", "item_qty": 3, "price": "27.00", "purchased_at": "2017-04-30 23:00:00" }]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"client_id": "abc123", "contact_id": "6fs63hthg", "tx_id": "5678", "item_cat": "Beer", "item_dep": "Imported", "item_code": "12344", "item_desc": "Tiger", "item_qty": 3, "price": "27.00", "purchased_at": "2017-04-30 23:00:00" }]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "abc123",
            "contact_id": "6fs63hthg",
            "tx_id": "5678", 
            "item_cat": "Beer", 
            "item_dep": "Imported", 
            "item_code": "12344", 
            "item_desc": "Tiger", 
            "item_qty": 3, 
            "price": "27.00", 
            "purchased_at": "2017-04-30 23:00:00"
        }    
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "abc123",
            "contact_id": "6fs63hthg",
            "tx_id": "5678", 
            "item_cat": "Beer", 
            "item_dep": "Imported", 
            "item_code": "12344", 
            "item_desc": "Tiger", 
            "item_qty": 3, 
            "price": "27.00", 
            "purchased_at": "2017-04-30 23:00:00"
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
No such contact in MyGuestlist database The contact_id in your request does not exist in MyGuestlist.
No purchase information to add You didn't supply any purchase data.
No item description provided The item_desc in your request was invalid.
No item price provided The price in your request was invalid.
No purchase date and time provided The purchased_at in your request was invalid.
Purchase add failed There was an error adding this purchase to MyGuestlist.

Reservations

The MyGuestlist API allows you to add reservations in MyGuestlist.

The following features are supported.

Getting Reservations /pull_reservations

Description: The pull_reservations method allows your system/application to retrieve the MyGuestlist account reservations and associated contact details.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/pull_reservations
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
touched_from datetime Filter the data by retrieving records inserted or updated from the specified date and time. The parameter is optional and can be set without the touched_to field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
touched_to datetime Filter the data by retrieving records inserted or updated to the specified date and time. The parameter is optional and can be set without the touched_from field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
Heads Up

Excluding the touched_from and touched_to parameters from the request will retrieve the entire client’s MyGuestlist reservations.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"touched_from\": \"2017-04-30 23:00:00\", \"touched_to\": \"2017-04-30 23:30:00\", \"client_id\": \"abc123\"}\n",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations?=' \
  --header 'content-type: application/json' \
  --data '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}
'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}\n' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

[
    {
      "reservation" : 
         {
            "id":"res29gjgu5y",
            "total_attendees":"23",
            "bookingStatus": "Confirmed",
            //custom reservation fields...
         },
      "contact" :
         {
            "client_id":"abc123",
            "contact_id":"5fgfhejgfu4",
            //custom contact fields...
         }
   }
]
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

Adding Reservations /push_reservations

Description: The push_reservations method allows your system/application to push the client’s reservations and associated contact details into their MyGuestlist account.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/push_reservations
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format, like the following example.

[
   {
      "reservation" : 
         {
            "id":"[RESERVATION ID]",
            "total_attendees":"[PAX]",
            "attendee_names ":"[NAMES]",
            custom reservation fields...
         },
      "contact" :
         {
            "client_id":"[CLIENT ID]",
            "contact_id":"[MGL ID]",
            custom contact fields...
         }
   }
]
Parameter Type Required Description Example Value
id string The ID for the new Reservation. abc123
total_attendees number The number of people attending the booking. abc123
attendee_names string or array Either a CSV list of attendee names, or an array of names. Jon, Ned, Joffrey
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. Only supply this if you know the MyGuestlist contact record you need to update, otherwise MyGuestlist will handle this for you. 6fs63hthg
Reservation Information Fields object The remainder of the reservation fields contain reservation information. I.e. reservation name, date, time etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_reservation_fields method
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"reservation\" : { \"id\":\"abc123\", \"total_attendees\": \"2\", \"attendee_names \": \"Jon, Ned, Joffrey\", \"Date\": \"2017-04-01\", \"Time\": \"19:00:00\"}, \"contact\" :\n{\"client_id\": \"abc123\", \"contact_id\": \"123\", \"PatronName\": \"Jon Snow\", \"PatronEmail\": \"jon@winterfel.gov\"}}]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations?=' \
  --header 'content-type: application/json' \
  --data '[{"reservation" : { "id":"abc123", "total_attendees": "2", "attendee_names ": "Jon, Ned, Joffrey", "Date": "2017-04-01", "Time": "19:00:00"}, "contact" :
{"client_id": "abc123", "contact_id": "123", "PatronName": "Jon Snow", "PatronEmail": "jon@winterfel.gov"}}]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"reservation" : { "id":"abc123", "total_attendees": "2", "attendee_names ": "Jon, Ned, Joffrey", "Date": "2017-04-01", "Time": "19:00:00"}, "contact" :\n{"client_id": "abc123", "contact_id": "123", "PatronName": "Jon Snow", "PatronEmail": "jon@winterfel.gov"}}]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reservation_id": "abc123",
        }     
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reservation_id": "abc123",
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

Getting Reservation Fields /get_reservation_fields

Description: The get_reservation_fields method allows the your system/application to retrieve the client’s reservation field names within MyGuestlist for field to field mapping between the two systems.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/get_reservation_fields
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"client_id\": \"abc123\"}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields?=' \
  --header 'content-type: application/json' \
  --data '{"client_id": "abc123"}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"client_id": "abc123"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "fields": [
        {
            "name": "Date", 
            "type": "date"
        },
        {
            "name": "Time", 
            "type": "time"
        },
        {
            "name": "bookingStatus",
            "type": "singleSelect",
            "options": [
                "Unconfirmed",
                "Pending",
                "Confirmed"
            ]
        },
        {
            "name": "FavouriteColour", 
            "type": "singleSelect",
            "options": [
                "Green",
                "Red",
                "Blue"
            ]
        }
    ]
}
{
    "result": false,
    "message": "No client ID provided"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

SMS Replies

The MyGuestlist API allows you to read replies to SMS messages sent from the MyGuestlist account.

SMS Inbox /sms_inbox

Description: Retrieve SMS replies sent to a virtual number managed by MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sms_inbox
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
date_start datetime An ISO-8601 datetime string to start searching from. 2017-04-01 23:00:00
date_end datetime An ISO-8601 datetime string to stop searching at. 2017-04-01 23:00:00
prefix string A prefix of a reference_id to search for. kings

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox?=' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox',
  qs: { '': '' },
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "SMS replies",
    "data": [
        {
            "timestamp": "2017-04-01 23:00:00",
            "number": "sms",
            "to": "0411111111",
            "reference_id": "kingsenews002",
            "message": "Thanks I'll be there",
        }
    ]
}
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Webhooks

Webhooks are real time notifications pushed from MyGuestlist to a specified URL when the corresponding event occurs on your database within MyGuestlist. Events will only be sent once to the specified URL.

In terms of information data flow between MyGuestlist and your system/application, a Request refers to data sent from MyGuestlist to your system/application and a Response is the data sent back to MyGuestlist.

Setup Required

Webhooks must be enabled on your account by MyGuestlist. There is no ability to configure webhook URL's yourself.

New Contact new_contact

Description: The new_contact event occurs when a new contact is added to the MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"new_contact",
   "PatronName": "Jon",
   "PatronEmail": "jsnow@winterfel.gov"
}

Contact Updated contact_update

Description: The contact_update event occurs when information on a contact is updated within the MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"contact_update",
   "PatronName": "Jon",
   "PatronEmail": "jsnow@winterfel.gov"
}

Contact Delete delete_contact

Description: The delete_contact event occurs when a contact is deleted within the client’s MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"delete_contact"
}