Accessing the API documentation

Question: How do I access the API documentation

Answer: Find them here on Mono Academy:

HAL API Documentation

Site API Documentation

 

Common HAL API issues

The following is a list of common issues found when accessing the HAL API and how to correct them. If you are receiving an unexpected, or no response from our HAL API then please check the following checklist.

  • All requests are POST requests
  • All requests must be sent to the following url https://hal.mono.net/api/v1/{endpoint}
  • The url must not contain ?command={command}. We included it in our documentation in that way to find each API command easy to find
  • Ensure you are sending a JSON payload
  • Ensure you've set the header "content-type: application/json"
  • Ensure there are no non-unix new lines in the JSON payload
  • Ensure you are including a valid "userToken". If you are still receiving authentication errors, ensure the token you are using is valid for the reseller/site you are attempting to access, particularly if you have access to a test reseller
  • Do not use the "test" parameter. This has been deprecated and will result in an error

 

Accessing the site API

Question: How do I use the site API?

Answer: In order to use the site API, a cookie token must be sent as one of the request headers. To get the token, you can use the following api call

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/site

{
"userToken": "{{user_token}}",
"command": "apiLogin",
"siteId": 1053063
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T07:30:16+00:00"
},
"data": [
{
"sessionName": "site_session",
"sessionId": "nu833b9v0mue42uk41pauilcg3"
}
]
}

 

Once you have the token, we can start sending it to the site's API which can be accessed using the site's domain in the following url http://{domain}/api.php/{endpoint} See an example below for a fictional site 

Documentation

Request

GET https://u1053063.mono.net/api.php/settings
header: Cookie:site_session=nu833b9v0mue42uk41pauilcg3

Response

[
{
"settings": {
"lang": "fr-ca",
"date": "d/m/Y",
"time": "H:i:s",
"analyticsInHead": false,
"speed": true,
"favicon": "",
"globalCSS": "",
"headHTML": "",
"bodyHTML": "",
"ageVerification": false,
"automaticLanguageDetection": false,
"socialMediaOptIn": false,
"forceSsl": true,
"enablePreview": true,
"customGaIds": "",
"cookie": false,
"customGTM": "",
"scrollIcon": "{\"scrollIconEnabled\":\"true\",\"iconPosition\":\"bottom_right\"}",
"lazyLoad": true,
"disableAutoPublish": false,
"enableAria": false,
"enableSkipNavigation": false,
"enableFocusIndication": false,
"footerLightLogo": false,
"footerContainerFluid": false,
"pwa": {
"enabled": "false",
"homescreen": "false",
"name": "LWG Photos",
"shortName": "LWG Photos",
"icon": "/uploads/logo.png",
"background": "rgba(0, 0, 0, 0)"
}
}
}
]

 

Creating a site

Question: How do I create a site via the API?

Answer: There are a few steps for creating a site. A site must belong to an account so that should be created first if there already isn't one. This is the account containing the customer information for all the sites under that account. Once an account is made, you can create the site but it will not be available until a subscription has been added to it. 

Step 1: Create an account (If you don't already have an account ID to attach the site to)

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/

{
"userToken": "{{user_token}}",
"command": "createAccount",
"resellerId": "{{reseller}}",
"name":"Tasty Donuts"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:04:01+00:00"
},
"data": [
{
"accountId": 686653
}
]
}

Step 2: Create the site

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account

{
"userToken": "{{user_token}}",
"command": "createSite",
"resellerId": {{reseller}},
"accountId": 686653,
"version": "v5",
"email": "noreply@monosolutions.com",
"subdomain": "sub001",
"locale": "en",
"username": "tastydonuts",
"password": "tastydonutspassword",
"type": "DIFM"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:04:01+00:00"
},
"data": [
{
"siteId": 1058385
}
]
}

 

Step 3: Add the site subscription

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/

{
"userToken": "{{user_token}}",
"command": "addSubscription",
"resellerId": {{reseller}},
"siteId": 1058385,
"apiId": "trial",
"billingFrequency": 2
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:12:57+00:00"
},
"data": [
{
"success": true,
"subscriptionId": 1061735
}
]
}

 

Unpublish / suspend / terminate

Question: What is the difference between unpublishing a site, suspending a site and terminating a site?

Answer: There are 3 different ways of taking a site away from the end user with 3 different API calls.

1. Unpublish

This is used whenever the site was accidentally published before it was due to be seen by the general public. When the public visits the site, they will see a gentle 'This site has not been published yet' message.

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/site

{
"command": "unpublishContent",
"siteId": "{{site}}",
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:28:49+00:00"
},
"data": [
{
"success": true
}
]
}

2. Suspend

This is used to let the site owner know they need to take some action in order to have their site restored. The message is a stronger 'This site has been suspended' message.

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/site

{
"command": "suspend",
"siteId": "{{site}}",
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:28:49+00:00"
},
"data": [
{
"success": true
}
]
}

3. Terminate Subscription

This is a permanent command used to terminate all billing on the site and delete it. It's used when a site is no longer in use, or the subscription has expired for the site. If a subscription has it's 'onExpiry' set to terminate, then this command will run automatically in the night on the following day from the expiry date.

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account

{
"userToken": "{{user_token}}",
"command": "terminateSubscription",
"resellerId": {{reseller}},
"accountId": {{account}},
"subscriptionId" {{subscription}}:
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:28:49+00:00"
},
"data": [
{
"success": true
}
]
}

 

Generate a one-click site

Question: What's the difference a one click site and a regular site?

Answer: A oneclick site is effectively the same as a normal site and should be generated with the same commands as mentioned in the 'CREATE A SITE' guide. However there is an additional step which is used to copy a one click template and then apply the data from a data source to it. For more information on which sources are available to you, please contact your Mono representative.

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/site

{
"userToken": "{{user_token}}",
"command": "setContentFromSource",
"siteId": {{site}} ,
"source": "facebook",
"contentId": "mono.net",
"templateId": 748869,
"locale": "en"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:43:44+00:00"
},
"data": [
{
"timings": [
"0.4222 - Facebook Data Read",
"0.8380 - Image Content Read",
"1.0457 - Video Content Read",
"1.2378 - Profile Content Read",
"2.1982 - Template Read",
"2.8639 - Old Files Deleted",
"5.8710 - Base images and site structure copied from blank template",
"6.8751 - Image Uploaded: 084318_12565376_10154158454128455_3005633717749350389_n.jpg",
"7.9157 - Image Uploaded: 084318_10325549_10154088497233455_7261526333738588412_n.png",
"8.3522 - Image Uploaded: 084318_12308411_10154050777758455_5236318485668916155_n.png",
"8.8208 - Image Uploaded: 084318_12342661_10154042029913455_509899910205242986_n.png",
"9.8265 - Image Uploaded: 084318_12316460_10154038371613455_7106028232246534279_n.png",
"10.2614 - Image Uploaded: 084318_1509954_10153958753758455_8386239465017624410_n.jpg",
"10.8608 - Image Uploaded: 084318_12068510_10153930062328455_3798873274070764701_o.jpg",
"11.3484 - Image Uploaded: 084318_12043201_10153927794128455_7492233417228266573_n.png",
"11.8828 - Image Uploaded: 084318_1782269_10153895642973455_9014761557594816310_o.png",
"12.4227 - Image Uploaded: 084318_12006361_10153879524098455_7688120532391340725_n.jpg",
"12.8230 - Image Uploaded: 084318_11709597_10153672099113455_5403359006551569643_n.jpg",
"13.4500 - Image Uploaded: 084318_11537255_10153637790433455_4678814033450778018_o.png",
"13.7475 - Image Uploaded: 084318_11014270_10153368944438455_4122605335436908408_n.jpg",
"14.2799 - Image Uploaded: 084318_11055283_10153363936238455_8135489894054917526_n.png",
"14.6252 - Image Uploaded: 084318_11054464_10153363579493455_4851496470526455348_n.png",
"15.0532 - Image Uploaded: 084318_10850216_10153110309343455_9077596688681590198_n.jpg",
"15.5094 - Image Uploaded: 084318_10408984_10153110309333455_8186907304610908587_n.jpg",
"15.9560 - Image Uploaded: 084318_10849828_10153108266213455_973361009455249447_n.jpg",
"16.3315 - Image Uploaded: 084318_1511503_10153108266208455_7135003604658777504_n.jpg",
"16.7583 - Image Uploaded: 084318_10406498_10153093891958455_1658331513570915617_n.jpg",
"16.7585 - Gallery Image Skipped: 084318_12565376_10154158454128455_3005633717749350389_n.jpg",
"16.7586 - Gallery Image Skipped: 084318_10325549_10154088497233455_7261526333738588412_n.png",
"16.7587 - Gallery Image Skipped: 084318_12308411_10154050777758455_5236318485668916155_n.png",
"16.7587 - Gallery Image Skipped: 084318_12342661_10154042029913455_509899910205242986_n.png",
"16.7588 - Gallery Image Skipped: 084318_12316460_10154038371613455_7106028232246534279_n.png",
"16.7589 - Gallery Image Skipped: 084318_1509954_10153958753758455_8386239465017624410_n.jpg",
"16.7590 - Gallery Image Skipped: 084318_12068510_10153930062328455_3798873274070764701_o.jpg",
"16.7591 - Gallery Image Skipped: 084318_12043201_10153927794128455_7492233417228266573_n.png",
"16.7591 - Gallery Image Skipped: 084318_1782269_10153895642973455_9014761557594816310_o.png",
"16.7592 - Gallery Image Skipped: 084318_12006361_10153879524098455_7688120532391340725_n.jpg",
"16.7593 - Gallery Image Skipped: 084318_11709597_10153672099113455_5403359006551569643_n.jpg",
"16.7594 - Gallery Image Skipped: 084318_11537255_10153637790433455_4678814033450778018_o.png",
"16.7595 - Gallery Image Skipped: 084318_11014270_10153368944438455_4122605335436908408_n.jpg",
"16.7596 - Gallery Image Skipped: 084318_11055283_10153363936238455_8135489894054917526_n.png",
"16.7596 - Gallery Image Skipped: 084318_11054464_10153363579493455_4851496470526455348_n.png",
"16.7597 - Gallery Image Skipped: 084318_10850216_10153110309343455_9077596688681590198_n.jpg",
"16.7598 - Gallery Image Skipped: 084318_10408984_10153110309333455_8186907304610908587_n.jpg",
"16.7599 - Gallery Image Skipped: 084318_10849828_10153108266213455_973361009455249447_n.jpg",
"16.7599 - Gallery Image Skipped: 084318_1511503_10153108266208455_7135003604658777504_n.jpg",
"16.7600 - Gallery Image Skipped: 084318_10406498_10153093891958455_1658331513570915617_n.jpg",
"16.7602 - Image Skipped: 084318_11055283_10153363936238455_8135489894054917526_n.png",
"16.7603 - logo Skipped: 084318_11054464_10153363579493455_4851496470526455348_n.png",
"16.7604 - logo Skipped: 084318_11054464_10153363579493455_4851496470526455348_n.png",
"16.7812 - Finished File Upload",
"17.6379 - Global Data Applied",
"19.7708 - Global Data Applied - images",
"19.8501 - Global Data Applied - websites",
"19.9557 - Global Data Applied - lists",
"20.1193 - Global Data Applied - socialMedias",
"20.1195 - CustomerSource set to 'facebook'",
"20.1195 - facebook analytics set to 'mono.net'",
"20.2236 - 1058385 saved successfully",
"26.1379 - Site Published"
],
"site": {}
}
]
}

 

Dynamic site login limitations

Question: I wish to craft a custom login link to a end user's site. How do I limit various parts of the editor?

Answer: You can submit a series of siteUserGroups which are our way of defining limitations to the editor. This is a comma separated list and the currently supported restrictions are defined as part of the documentation but the current list as of writing is below the API request example.

Documentation

Request

POST https://hal.mono.net/api/v1/reseller

{
"userToken": "{{user_token}}",
"command": "siteLogin",
"siteId": {{site}},
"userName": "John Smith",
"logoutUrl": "http://yourbusinesscentre.com?id=12345",
"siteUserGroups": "site_limit_home,site_limit_localStyling,site_limit_dragndrop,site_limit_modules,site_limit_settings,site_limit_help"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T09:04:24+00:00"
},
"data": [
{
"ticket": "9293f182658581d8de87f15882730b208328",
"loginUrl": "http://{toolDomain}/v5/login.php",
"fullLoginUrl": "http://{toolDomain}/v5/login.php?et={longToken}
}
]
}

Valid siteUserGroups

site_limit_pages - Prevent adding, moving and removing pages
site_limit_modules - Hide the modules bar
site_limit_settings - Hide the settings menu
site_limit_grid - Prevent any interaction with the editor grid in 'build'
site_limit_dragndrop - Prevent moving modules, rows and columns
site_limit_globalStyling - Prevent access to global styling
site_limit_localStyling - Prevent access to module level styling and settings
site_limit_build - Remove the build menu
site_limit_shop - Remove the shop menu
site_limit_blog - Remove the blog menu
site_limit_settings - Remove the settings menu
site_limit_content - Remove the content menu

 

Access site analytics data

Question: How do I get a complete breakdown of analytics for a particular site?

Answer: Every site has a custom mono GA code we use to aggregate analytics data. This is pulled each night from Google and stored in a database allowing us to query all the data across multiple sites. As a rule we follow the same structure as Google and documentation for the data can be found on Google's dimension explorer.

To see all the data for 2018 for any particular site you have access to, you can supply the following request

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/stat

{
"userToken": "{{user_token}}",
"command": "getSiteStat",
"siteId": {{site}},
"from": "2018-01-01",
"to": "2018-12-31",
"fields": [
"site.sessions-website",
"site.users-website",
"site.pageviews-website",
"site.sessionDuration-website",
"site.bounces-website",
"site.uniquePageviews-website",
"site.sessions-mobile",
"site.users-mobile",
"site.pageviews-mobile",
"site.sessionDuration-mobile",
"site.bounces-mobile",
"site.uniquePageviews-mobile",
"site.sessions-facebook",
"site.users-facebook",
"site.pageviews-facebook",
"site.sessionDuration-facebook",
"site.bounces-facebook",
"site.uniquePageviews-facebook",
"site.keyword-website",
"site.keyword-mobile",
"site.keyword-facebook",
"site.trafficSource-website",
"site.trafficSource-mobile",
"site.trafficSource-facebook",
"site.searchTraffic-website",
"site.searchTraffic-mobile",
"site.searchTraffic-facebook",
"site.searchEngine-website",
"site.searchEngine-mobile",
"site.searchEngine-facebook",
"site.paidSearchTraffic-website",
"site.paidSearchTraffic-mobile",
"site.paidSearchTraffic-facebook",
"site.referral-website",
"site.referral-mobile",
"site.referral-facebook",
"site.campaign-website",
"site.campaign-mobile",
"site.campaign-facebook",
"site.country-website",
"site.country-mobile",
"site.country-facebook",
"site.city-website",
"site.city-mobile",
"site.city-facebook",
"site.region-website",
"site.region-mobile",
"site.region-facebook",
"site.metro-website",
"site.metro-mobile",
"site.metro-facebook",
"site.visitfrequency-website",
"site.visitfrequency-mobile",
"site.visitfrequency-facebook",
"site.pageUrl-website",
"site.pageUrl-mobile",
"site.pageUrl-facebook",
"site.pageTitle-website",
"site.pageTitle-mobile",
"site.pageTitle-facebook",
"site.outlink-website",
"site.outlink-mobile",
"site.outlink-facebook",
"site.download-website",
"site.download-mobile",
"site.download-facebook",
"site.customEvent-website",
"site.customEvent-mobile",
"site.customEvent-facebook",
"site.ecommerce-website",
"site.ecommerce-mobile",
"site.ecommerce-facebook",
"site.ecommerceProducts-website",
"site.ecommerceProducts-mobile",
"site.ecommerceProducts-facebook",
"site.operatingSystem-website",
"site.operatingSystem-mobile",
"site.operatingSystem-facebook",
"site.configuration-website",
"site.configuration-mobile",
"site.configuration-facebook",
"site.browserType-website",
"site.browserType-mobile",
"site.browserType-facebook",
"site.browser-website",
"site.browser-mobile",
"site.browser-facebook",
"site.deviceCategory-website",
"site.deviceCategory-mobile",
"site.deviceCategory-facebook",
"site.campaignVisits",
"site.campaignPageviews",
"site.campaignGoals",
"site.campaignEvents",
"site.campaignEvents-website",
"site.campaignEvents-mobile",
"site.campaignEvents-facebook"
],
"group": ["year"]
}

 For reasons of privacy, we will not include a response in this documentation, but if you run the command yourself for a site that has a bit of traffic, you can see the breakdown of the data yourself

 

Adding a domain

Question: What are the different types of domain hosting solutions you have, and how do I use them via the API?

Answer: We offer 3 distinct domain solutions. Register, Transfer and Hosting. Register is the standard 'buy a domain and we'll manage it for you'. Transfer is where the domain is currently being managed by another party and using an auth code / EPP code, you can transfer the domain to us. Hosting is where the domain is managed by someone other than Mono but have their name servers pointing to us. It is likely each type with have its own pricing structure.

Step 1: Tell Mono to serve traffic for a domain to a particular site ID

The first step is to send an API call which will link a domain to a site ID. Whenever traffic is routed to our servers for that domain, our servers will respond by serving that site's pages. This must be done regardless of the type of domain it is (register/transfer/hosting)

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/site

{
"command": "addDomain",
"domain": "{{domain_name}}",
"position": "0",
"siteId": {{site}},
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T09:41:33+00:00"
},
"data": [
{
"success": true
}
]
}

Step 2.1 Register

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/domain

{
"accountId": "{{account}}",
"command": "register",
"contactSet": {
"admin": {
"address1": "Street 1",
"address2": "",
"address3": "",
"city": "Frankfurt",
"country": "DE",
"email": "germansite@germany.de",
"fax": "",
"first_name": "Bob",
"last_name": "Jones",
"org_name": "Bob's Bits",
"org_vat": "",
"phone": "+49.50313338855",
"postal_code": "31111",
"state": "Niedersachsen"
},
"owner": {
"address1": "Street 1",
"address2": "",
"address3": "",
"city": "Frankfurt",
"country": "DE",
"email": "germansite@germany.de",
"fax": "",
"first_name": "Bob",
"last_name": "Jones",
"org_name": "Bob's Bits",
"org_vat": "",
"phone": "+49.50313338855",
"postal_code": "31111",
"state": "Niedersachsen"
}
},
"domainName": "{{domain_name}}",
"period": "12",
"resellerId": {{reseller}},
"tldData": {
"registrant_extra_info": {
"registrant_type": "organization"
}
},
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T09:41:33+00:00"
},
"data": [
{
"success": true
}
]
}

Step 2.2 Transfer

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/domain

{
"accountId": "{{account}}",
"command": "transfer",
"contactSet": {
"admin": {
"address1": "Street 1",
"address2": "",
"address3": "",
"city": "Frankfurt",
"country": "DE",
"email": "germansite@germany.de",
"fax": "",
"first_name": "Bob",
"last_name": "Jones",
"org_name": "Bob's Bits",
"org_vat": "",
"phone": "+49.50313338855",
"postal_code": "31111",
"state": "Niedersachsen"
},
"owner": {
"address1": "Street 1",
"address2": "",
"address3": "",
"city": "Frankfurt",
"country": "DE",
"email": "germansite@germany.de",
"fax": "",
"first_name": "Bob",
"last_name": "Jones",
"org_name": "Bob's Bits",
"org_vat": "",
"phone": "+49.50313338855",
"postal_code": "31111",
"state": "Niedersachsen"
}
},
"domainName": "{{domain_name}}",
"period": "12",
"resellerId": {{reseller}},
"tldData": {
"auth_code": "123i8d89"
}
},
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T09:41:33+00:00"
},
"data": [
{
"success": true
}
]
}

Step 2.3 Hosting

Just a quick guide on domain hosting that can be found here.

 

IMPORTANT: Mono cannot set the name servers for a domain we didn’t register. You must communicate with the client in order to point their domains to our name servers (ns1.mono.net, ns2.mono.net, ns3.mono.net)

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account/domain

{
"accountId": "{{account}}",
"command": "hosting",
"domainName": "{{domain_name}}",
"resellerId": "{{reseller}}",
"userToken": "{{user_token}}"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T09:41:33+00:00"
},
"data": [
{
"success": true
}
]
}

 

How to add Google Analytics to a site

Question: How do I add one or more GA codes to a site

Answer: Use the site API to send the GA codes to the /settings endpoint. Use the same procedure as defined here to obtain the site_session token then use the following request

Documentation

Request

PATCH http://{domain}/api.php/settings

{
"customGaIds": "GA-123456,GA-23456"
}

Response

[]

 

How do I create an II site?

Question: How do I choose whether I want an ii or v5 site from the API

Answer: Assuming your reseller has been given the right to create ii sites, it's exactly the same process as generating a v5 site, except you set the 'version' to be 'ii' in lower case. Currently it's best to create ii sites as Simple editing mode sites so the end user can enjoy the full 'new user experience'

Documentation

Request

POST https://hal.mono.net/api/v1/reseller/account

{
"userToken": "{{user_token}}",
"command": "createSite",
"resellerId": {{reseller}},
"accountId": 686653,
"version": "ii",
"email": "noreply@monosolutions.com",
"subdomain": "sub001ii",
"locale": "en",
"username": "tastydonuts-ii",
"password": "tastydonutspassword",
"type": "DIY"
}

Response

{
"status": {
"code": 200,
"text": "",
"timeStamp": "2018-10-04T08:04:01+00:00"
},
"data": [
{
"siteId": 1058385
}
]
}

 

Submit a sitemap via site

Question: How do I submit a sitemap to google for my site via the API

Answer: The sitemap can be submitted via a POST to the site API endpoint /utils/sitemap. First, get the site_session token via the instructions here https://monosolutions.zendesk.com/hc/en-us/articles/360009909694#accessing-the-site-api and then submit the following API call to your site

Request

POST https://u1053063.mono.net/api.php/utils/sitemap
header: Cookie:site_session={your_site_session_token}

Response

[]
Was this article helpful?
1 out of 2 found this helpful

Articles in this section