Introduction

The MyGuestlist Partner API allows MyGuestlist Partners to deeply integrate the MyGuestlist product into third-party applications and systems.

Examples of use

You may wish to use the MyGuestlist Partner API and functions for some of the following purposes:

  • Allowing your customers to directly access their MyGuestlist account without needing to login to another system
  • Leveraging the MyGuestlist product to add additional features to your system
  • Offering your customers exclusive discounted access to the MyGuestlist platform

Requesting Access to MyGuestlist Accounts

MyGuestlist allows third-party systems to access MyGuestlist Accounts via our MyGuestlist Client API. In order to use our Client API, you'll need a MyGuestlist API Key.

Requesting API Details

To request the API access details from MyGuestlist, you should make a call to the MyGuestlist Client API, to the method request_token at https://api.myguestlist.com/v1/request_token.


Headers

The following headers must be sent with this request.

Field Description
signature The Signature of the request is a calculated string, encrypted with SHA256. See Generating Signatures below.
username The MyGuestlist Account Username of the account attempting to login.
nonce The nonce of the request is the current date and time in GMT, specified in ISO-8601 format. For example, 2016-09-07 14:00:00.

If the username and password provided in the signature are valid, MyGuestlist will return a JSON object, such as:

{
    "result": true,
    "message": "Successfully fetched API credentials",
    "data": {
        "token": "TOKEN HERE",
        "secret": "SECRET HERE"
    }
}

Note: In the event there is an error, the result Parameter will always be false.

Important

Your server must have the correct date and time, and the time you pass in your nonce value must be in UTC/GMT time. If your servers time is off by more than one minute, you will not be able to authenticate with this method.



Generating the Signature

When calling the requst_token endpoint, your request must contain a valid signature header. You must generate this signature inside your application before sending it to MyGuestlist.

Security First

MyGuestlist will never send your application a MyGuestlist Account Password. Your application should not send a MyGuestlist Password over HTTP or HTTPS. Always ensure you send MyGuestlist Account Credentials in an encrypted form.

The signature is made up of the MyGuestlist username, encrypted password, and a nonce value seperated with a full stop (period). For example:

signature = username + "." + password_sha1_hash + "." + nonce

Finally, the signature is encrypted using SHA256 salted with the SHA1 hash of the users password.


Examples Generating Signatures

<?php
$username = "mgl_account_username";
$password = "mgl_awesome_password"; //Get these from your user

date_default_timezone_set("UTC");
$nonce = date("Y-m-d H:i:s");
$password = sha1($password);
$signature = hash_hmac("sha256", "{$username}.{$password}.{$nonce}", $password);
?>
<html>
    <head>
        <title>MyGuestlist API Test</title>
        <script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
        <script src="http://momentjs.com/downloads/moment.min.js"></script>
        <!-- <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/core.js"></script> -->
        <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
        <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/sha1.js"></script>
    </head>
    <body>
        
        <button>Login</button>
        
        <script>
        $('button').click(function() {
            
            var username = prompt('Username');
            var pass = CryptoJS.SHA1(prompt('Password')).toString();
            
            var nonce = moment().utc().format('YYYY-MM-DD HH:mm:ss');
            var signature = CryptoJS.HmacSHA256(username+'.'+pass+'.'+nonce, pass).toString();
            
            $.ajax({
                url: 'http://api.myguestlist.com/v1/request_token/',
                type: 'POST',
                dataType: 'json',
                beforeSend: function(req) {
                    req.setRequestHeader("username", username);
                    req.setRequestHeader("signature", signature);
                    req.setRequestHeader("nonce", nonce);
                },
                success: function(res) {
                    console.log(res);
                    
                    if (res.result) {
                        console.log(res.data.token);
                        console.log(res.data.secret);
                        login(res.data.token, res.data.secret);
                    }
                }
            });
            
        });
        
        </script>
    </body>
</html>

Sending Requests to the MyGuestlist API

When calling request_token, you must pass the data in the request headers to MyGuestlist. Below are some examples of how to do this.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://api.myguestlist.com.au/v1/request_token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded",
    "nonce: NONCE_HERE",
    "signature: SIGNATURE_HERE",
    "username: USERNAME_HERE"
  ),
));

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

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>
curl --request POST \
  --url http://api.myguestlist.com.au/v1/request_token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'nonce: NONCE_HERE' \
  --header 'signature: SIGNATURE_HERE' \
  --header 'username: USERNAME_HERE'
                                            
                                        
var http = require("http");

var options = {
  "method": "POST",
  "hostname": "api.myguestlist.com.au",
  "port": null,
  "path": "/v1/request_token",
  "headers": {
    "signature": "SECRET_HERE",
    "nonce": "NONCE_HERE",
    "username": "USERNAME_HERE",
    "content-type": "application/x-www-form-urlencoded",
    "content-length": "0"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Logging into MyGuestlist Accounts

MyGuestlist provides partner websites the ability for their users to automatically login to a MyGuestlist account. Using this method, the user is not prompted for their MyGuestlist credentials.

In order for your website to automatically log users into MyGuestlist, your website must provide the API Key and secret as returned from the request_token endpoint discussed above.

When it comes time for your user to login to MyGuestlist, you will send them to a URL in the format:

https://api.myguestlist.com.au/v1/api_token/signin?signature=signature&nonce=nonce&token=api_token
Heads Up

Your server must have the correct date and time, and the time you pass in your nonce value must be in UTC/GMT time. If your servers time is off by more than one minute, you will not be able to authenticate with this method.

Your system should not directly inject this URL into your application. Stale links (older than one minute) will not allow the user to access their MyGuestlist account.



Generating the Signature

When calling the signin endpoint, your request must contain a valid signature in the URL. You must generate this signature inside your application.

Confusion Alert

The signature used when calling signin is generated differently to the one used for request_token!

To generate the signature used when signing into MyGuestlist accounts, the following is used:

signature = token + "." + secret + "." + nonce

Finally, the signature is encrypted using SHA256 salted with the SHA1 hash of the secret.


Examples Generating Signatures

<?php
$token = "mgl_api_token";
$secret = "mgl_api_secret"; //Get these from your database

date_default_timezone_set("UTC");
$nonce = date("Y-m-d H:i:s");
$signature = hash_hmac("sha256", "{$token}.{$secret}.{$nonce}", $secret);
?>
<html>
    <head>
        <title>MyGuestlist API Test</title>
        <script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
        <script src="http://momentjs.com/downloads/moment.min.js"></script>
        <!-- <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/core.js"></script> -->
        <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
        <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/sha1.js"></script>
    </head>
    <body>
        
        <button>Login</button>
        
        <script>
        $('button').click(function() {
            
            var token = prompt('Token');
            var secret = prompt('Secret');

            login(token, secret);
        });
        
        function login(token, secret) {
            var nonce = moment().utc().format('YYYY-MM-DD HH:mm:ss');
            var signature = CryptoJS.HmacSHA256(token+'.'+secret+'.'+nonce, secret).toString();
            window.open('http://api.mgl/v1/'+token+'/signin?signature='+signature+'&nonce='+nonce+'&token='+token);
        }
        
        </script>
    </body>
</html>

Creating a MyGuestlist Account

The MyGuestlist system holds various MyGuestlist Plan settings for each partner. Each Plan is given a Plan ID. There are two form of URL's you can direct your users to.

Partner Plan List

Each MyGuestlist Partner may use their Partner ID to access a page which lists the MyGuestlist Plans for that partner. The URL of this page is as follows.

https://account.myguestlist.com/signup/ref/Partner ID

For example, assuming an example Partner ID is 512abc456, the url would be:

https://account.myguestlist.com/signup/ref/512abc456

Direct Plan Link

You may wish to highlight the differences in your plan offerings on your own website. For this, you may link directly to a MyGuestlist Plan. Each plan has a unique ID, which can be placed in the URL. The format of this URL is:

https://account.myguestlist.com/signup/online_signup?pkgid=Plan ID

Assuming an example Plan ID is 513def789, the URL to the plan would be:

https://account.myguestlist.com/signup/online_signup?pkgid=513def789

Specifying Business Logo

When linking to a MyGuestlist Partner Plan List or Direct Plan Link, you may optionally specify a URL to a logo of the business that is creating the MyGuestlist account.

Confusion Alert

The business logo URL specified here is for the new MyGuestlist Account signing up. It is not the business logo of the Partner and it won't be displayed on the signup form.

When directing your users to a MyGuestlist Partner Plan List or Direct Plan Link, you may append a URL to an image. For example, to append the MyGuestlist logo to a Partner Plan the URL structure would be:

https://account.myguestlist.com/signup/ref/PartnerID/?logo_url=http%3A%2F%2Fcdn.myguestlist.com%2Fwp-content%2Fthemes%2Fmglv3%2FHTML%2Fimages%2Flogo.png

Or for a Direct Plan Link

https://account.myguestlist.com/signup/online_signup?pkgid=PlanID&logo_url=http%3A%2F%2Fcdn.myguestlist.com%2Fwp-content%2Fthemes%2Fmglv3%2FHTML%2Fimages%2Flogo.png

The URL to the logo must be publicly accesible (not behind a username/password protected area). When specifying the logo URL, be sure you URL Encode it.

Signup Reference

When linking to a MyGuestlist Partner Plan List or Direct Plan Link, you may optionally specify a reference your application may use to identify the signup. An example use may be to provide your applications user ID in the reference, so when you receive a webhook you know which one of your users the signup was for.

Note: References are not validated by MyGuestlist, and are provided for your use only. As such, you may receive multiple webhooks with the same reference.

To append a reference to a Partner Plan the URL structure would be:

https://account.myguestlist.com/signup/ref/PartnerID/?reference=YOURREF

Or for a Direct Plan Link

https://account.myguestlist.com/signup/online_signup?pkgid=PlanID/?reference=YOURREF

Getting Notified of new MyGuestlist Accounts

When a user completes a MyGuestlist signup form for one of your MyGuestlist Plans, MyGuestlist can send you a Webhook Notification with details about the new MyGuestlist Account that was created.

When a new MyGuestlist Account has been created, MyGuestlist will POST to your webhook URL with the following information in JSON format.

Heads Up

This must be setup by MyGuestlist before you start accepting MyGuestlist Accounts.

Important

MyGuestlist will make a maximum of six attempts to send the notification to your Webhook URL. MyGuestlist will stagger these attempts in the event there is a network issue preventing the notification being received.

Your system must return a content body that is not empty or equal to zero.

If after six attempts your server has not responded, MyGuestlist will give up.

Webhook Fields

Field Key Description
MyGuestlist Username account_username The MyGuestlist Username of the new account.
Client ID account_id The MyGuestlist Client ID of the new account.
API Key api_key An API Key which your system may use to connect with the MyGuestlist Client API.
Reference reference If you appended a reference to a signup link URL, this will be sent back to your system to track each signup link.

Example Webhook

The following is an example of a Webhook which your system may receive for a new MyGuestlist Account.

{
    "account_id": "51abc123456",
    "account_username": "mgl_account_test",
    "api_key": "abc1234-def5678-ghi9012-lmn2345-opqr6789",
    "reference": "1234"
}

Definitions

Throughout this document, we may refer to the following terms.

Term Definition
API Key A unique key which is used to access the MyGuestlist Client API for a MyGuestlist Account.
Client ID A unique string which MyGuestlist uses to identify a MyGuestlist Account.
MyGuestlist Account An account used to access the MyGuestlist Product on myguestlist.com.
MyGuestlist Plan A Plan is a set of pricing rules for a MyGuestlist Client Account. The Plan includes information such as monthly/setup fees, included messages and rates.
Plan ID An ID that relates to a MyGuestlist Plan.
Partner ID A random ID assigned to you by MyGuestlist. Replace Partner ID with your unique Partner ID where needed.
Partner Plan URL A URL where you can provide your Partner ID to view all of your MyGuestlist Plans.