API Reference

Welcome to MasterPlan’s API! You can use this API to access all our API endpoints

The API is organized around REST. All request and response bodies, including errors, are encoded in JSON.

Currently we support the following official client bindings:

Authentication

Authentication is handled manually using your App Secret token.
For example in PHP, to access a user:
<?PHP 
    $apiKey = "12345678";
    $secretKey = "1a2b3c4d5e6f7h";
    
    //STEP ONE
    $fields = array(
        'clientID' => $clientID,
        'key'      => $apiKey,
        'time'     => time(),
    	'userID'   => $userID
    ); //NOTE KEYS IN ALPHABETICAL ORDER
    foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }
    rtrim($fields_string, '&');
    
    //STEP TWO
    $md5hash = md5($fields_string);
    
    //STEP THREE
    $token = md5($md5hash.$secretKey);
    
    //STEP FOUR
    $fields_string = "&token=".$token; 
    
    //STEP FOUR
    $url = 'https://circularsoftware.com/MasterPlan/api/admin/fetchUser';
    $ch = curl_init();
    curl_setopt($ch,CURLOPT_URL, $url);
    curl_setopt($ch,CURLOPT_POST, count($fields));
    curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
    $result = curl_exec($ch);
    curl_close($ch);
?>
                    

Authentication is verified using the API key, secret key, a timestamp and the body of your request. You can find your keys in the admin panel.

You must POST a token variable with every request, along with the key and timestamp. The request parameters are concatenated along with your key and timestamp and MD5 hashed into the token

The current token should be created non-client-side to keep the secret key private.

To create a token step-by-step:

  1. Order your request body (excluding the token) in alphabetical order in a URL Encoded key/value format i.e. key1=val1&key2=val2...
  2. MD5 hash the entire request body
  3. Concatenate the MD5 hash from above with your API Secret and MD5 this - this is your token
  4. Append the token to the end of your request body i.e. key1=val1&key2=val2...&token=token
  5. Perform a CURL request to the designated endpoint.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON under the variable "error". The various HTTP status codes we might return are listed below.

HTTP Status codes

Code Title Description
200 OK The request was successful.
400 Bad request Bad request
401 Unauthorized Your API key or token is invalid.
404 Not found The resource does not exist.
601 Missing Parameters Your request is not complete.
602 Invalid Parameters One or more of your parameters were invalid.
604 Request object not found Subject of the request was not found.
500 Internal Server Error An error occurred with our API.

Error types

All errors are returned in the form of JSON with a type and optional message.

Example response.

                        {"status":200}
                    
                        {"status":401, "error": "Your request was not valid. Please check you have included all necessary variables"}
                    

General API

Access to general and miscellaneous API functions within MasterPlan.

Lookup ISBN

Find and locate jobs within MasterPlan by ISBN

curl 'https://circularsoftware.com/MasterPlan/api/lookupISBN?isbn=[ISBN]'

This is a lookup tool which requires no authentication and allows a user to find and locate a job within MasterPlan by ISBN.

The API response object looks like the following.


{
    "status" : 200,
    "result" : {
        "clientID"  : "1234",
        "jobID"     : "9786543210000",
        "isbn"      : "9786543210000",
        "mode"      : "live",
        "url"       : "https:\/\/circularsoftware.com\/MasterPlan\/Client1234\/Job9786543210000\/"
    }
}
                    

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/lookupISBN/

HTTP GET params

The supported parameters are:

param Description
isbn string (required) The ISBN to lookup.

Response Types

Code Description
200 Successful lookup, returns the ClientID, JobID and url link to the publication within MasterPlan.
404 The ISBN was not found within MasterPlan, or isn't linked to a publication.

User API

The User API lets you retrieve and set user information associated with an userID.

Fetch User

Lookup a user based on their userID or desktopID:

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&userID=[userID]&time=[timestamp]'
-X POST 'https://circularsoftware.com/MasterPlan/api/admin/fetchUser'

This endpoint allows you to find and lookup users based on the userID or desktopID and return associated information for that user.

The API response object looks like the following.


{
    "status":200,
    "result":
    {
        "spreadAccess":
        {
            "Job0001":
                {
                    "type":"all",
                    "range":""
                },
            "Job0002":
                {
                    "type":"range",
                    "range":"001~100"
                }
        },
        "userName":"Ann Other",
        "userID":"1",
        "desktopID":"1234567890",
        "clientAdmin":false,
        "userEmail":"ann@other.com"
    }
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/fetchUser

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
clientID string (required) The relevant ClientID for this client.
time string (required) A UNIX timestamp string representing the current time.
userID string (optional) The userID of the user that you wish to retrieve.
desktopID string (optional) The desktopID of the user that you wish to retrieve.

Response Types

Code Description
200 Success. User information and relevant spread access included in response.
601 Missing parameters. You must include EITHER a userID or desktopID to perform this action.
602 Permission Error. You do not have access to this user. Typically because the user isn't registered to your ClientID.
604 Not Found. Requested user not found.

Create User

Create a new user.

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&time=[timestamp]&name=[THEIR NAME]&email=[THEIR EMAIL]&pass=[THEIR PASSWORD]&access=[ACCESS OBJECT]'
-X POST 'https://circularsoftware.com/MasterPlan/api/admin/createUser'

This endpoint allows you to create a new user and initialise permissions for your client.

You will need to pass an access object in JSON also. The format of that JSON object is as follows.


{
    "Job0001":{
        "type":"all",
        "range":""
    },
    "Job0002":{
        "type":"range",
        "range":"001~100"
    },
    "Job0003":{
        "type":"none",
        "range":""
    }
}
                        

The API response object looks like the following.


{
    "status":200,
    "result":{
        "userID":874
    }
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/createUser

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
clientID string (required) The relevant ClientID for this client.
time string (required) A UNIX timestamp string representing the current time.
name string The name of the user.
email string (required) The users email address. In a valid format.
pass string (required) User's password as a plain text string.
access string A JSON encoded string containing an array of jobs and the access settings for each job. The options for type being all, none or range. If "range" then you must provide a range as spread references separated by ~ i.e. 001~100

Response Types

Code Description
200 Successful creation, userID of the created user included in the response.
601 Missing parameters. Either email or password.
602 Invalid parameters; email address invalid.

Remove User

Remove user by UserID

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&userID=[their UserID]&time=[timestamp]'
-X POST 'https://circularsoftware.com/MasterPlan/api/admin/removeUser'

This endpoint allows you to remove a user by specifying a userID.

The API response object looks like the following.


{
    "status":200
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/removeUser

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
clientID string (required) The relevant ClientID for this client.
userID string The userID of the user to be removed.
time string (required) A UNIX timestamp string representing the current time.

Response Types

Code Description
200 Successful removal.

Client API

The Client API lets you interact with your client account.

Get Statuses

View your current statuses and information

curl 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&time=[timestamp]'
'https://www.circularsoftware.com/MasterPlan/api/client/getStatuses'

The API response object looks like the following.


{
    "status": 200,
    "statuses": {
        "status1": {
            "name": "Planning",
            "color": "255,0,0"
        },
        "status2": {
            "name": "Work In Progress",
            "color": "255,165,8"
        },
        "status3": {
            "name": "Images Approved",
            "color": "255,255,0"
        },
        "status4": {
            "name": "Editorial Approved",
            "color": "51,153,255"
        },
        "status5": {
            "name": "Proof Approved",
            "color": "148,0,211"
        },
        "status6": {
            "name": "Print Ready",
            "color": "54, 211, 0"
        }
    }
}

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/client/getStatuses/

HTTP GET params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.

Response Types

Code Description
200 Fetch successful. Statuses found in "status" object.

Search Page Text

Retrieve either an entire spread's text or search for spreads containing a given keyword.

Retrieve an entire spread's text:

curl -d 'clientID=[clientID]&jobID=[jobID]&key=[apiKey]&time=[timestamp]&token=[accessToken]&page=[pageNumber]'
'https://www.circularsoftware.com/MasterPlan/api/admin/search'

The API response object looks like the following.

{
    "status":200,
    "result":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        Nam aliquet elit at gravida ultricies. 
        Proin vel orci sit amet sapien vestibulum egestas malesuada a ipsum. 
        Fusce sed mollis nulla. Vestibulum consectetur molestie vulputate. 
        Cras pulvinar semper venenatis. Nulla ut lacinia dui. 
        Proin a urna tristique, feugiat sapien id, tincidunt ligula. 
        Curabitur luctus lacus a hendrerit convallis. 
        Sed sit amet metus id ante facilisis pretium. 
        Phasellus libero enim, dignissim ut nulla et, vulputate malesuada lectus. 
        Nullam id quam ac libero fermentum congue. 
        Morbi ipsum augue, efficitur eget scelerisque a, ultrices ut felis. 
        Curabitur id nulla odio. Maecenas a libero lorem."
}

Search for spread's text:

curl -d 'clientID=[clientID]&jobID=[jobID]&key=[apiKey]&time=[timestamp]&token=[accessToken]&search=[term]&snippetSpan=100
'https://www.circularsoftware.com/MasterPlan/api/admin/search'

The API response object looks like the following.

{
    "status":200,
    "result":{
        "Job1234":
        [
            {
                "page":"106",
                "snippet":"...sample text.."
            },
            {
                "page":"139",
                "snippet":"...sample..."
            }
        ]
    }
}

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/admin/search/

HTTP GET params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string Relevant JobID. Required when using "page" option.
page string The relevant page or spread to return.
search string The search term.
snippetSpan int (optional) Default:50. Numerical value representing the number of characters either side (to the nearest space) of search term to return as a snippet.

Response Types

Code Description
200 Success. Result contained within "result" object. Either an array of Spreads/Pages when searching or plain text if requested a page.
601 Missing paramters. You must supply EITHER "page" or "search" and a "page" request requires a JobID
602 Invalid parameters. Likely to be blank.

Fetch Jobs

Get either all or a specific job and related details for your clientID.

Retrieve a JSON object containing jobs per client, if JobID is specified, only that specific Job will be returned; otherwise, all jobs for that client will be returned:

curl -d 'clientID=[clientID]&key=[apiKey]&time=[timestamp]&token=[accessToken]'
'https://www.circularsoftware.com/MasterPlan/api/client/fetchJobs/'

The API response object looks like the following.

{
    "status":200,
    "result":{
        "jobs":[
        {
            "jobID":"0001",
            "title":"Job0001",
            "width":"1992",
            "height":"1345",
            "author":"My Author",
            "publisher":"My Publisher",
            "publishDate":"2017-01-30",
            "isbn13":"",
            "isbn10":"",
            "dewey":"",
            "slackhook":"https:\/\/hooks.slack.com\/...HRB2O",
            "coverURL":"COVER.jpg"
        },
        {
            "jobID":"0001",
            "title":"Job0002",
            "width":"2500",
            "height":"1000",
            "author":"My Author",
            "publisher":"My Publisher",
            "publishDate":"1996-11-10",
            "isbn13":"",
            "isbn10":"",
            "dewey":"",
            "slackhook":"",
            "coverURL":"COVER.jpg"
        }]
    }
}

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/client/fetchJobs/

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (optional) If JobID is specified, only details for that specific job will be returned.

Response Types

Code Description
200 Success. All jobs contained with Result > Jobs.
404 Job not found. Only when JobID is provided.

Job API

The Job API lets you interact with individual jobs for your client.

Add Job (MP HOSTED)

Add a new Job to an existing Client

curl 'https://www.circularsoftware.com/MasterPlan/api/databaseCrawler?token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&time=[timestamp]&editorDesktopID=[desktopID]'
                        

The API response object looks like the following.


{
    "status":200
}
                        

MASTERPLAN HOSTED IMAGE/TEXT FILES

This endpoint is designed for use with the MasterPlan Desktop APP where your JPG files are hosted by us.

Once you've successfully uploaded Spread JPGs, issue a cURL request to the below endpoint and our system will crawl the newly added job folder on the server, and parse it within our database and mark the job as visible to administrators within the MasterPlan online platform.

This endpoint can be requested multiple times without causing any duplication within the database. You can also supply the optional SPREADID parameter if any changes are made to an individual spread.

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/databaseCrawler/

HTTP GET params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (required) Your new Job ID (must be between 4 and 13 digits).
spreadID string (optional) The altered spread ID.
editorDesktopID string (optional) The desktopID for the user performing the update request.

Response Types

Code Description
200 Successful Inclusion into Database.
400 Parameters missing or invalid. (information given within "error" object)

Add Job (SELF HOSTED)

cURL:

curl -d 'clientID=[clientID]&editorDesktopID=[desktopID]&jobID=[apiKey]&key=[apiKey]&spreads=[jSON - see below]&texts=[jSON - see below]&time=[timestamp]&token=[accessToken]'
'https://www.circularsoftware.com/MasterPlan/api/job/updateSpreads'

The API response object looks like the following.


{
    "status":200
}
                        

Example "spreads" JSON value:

{
    "001":
    {
        "spreadID":"001_135487548"
    }, 
    "002":
    {
        "spreadID":"002_135487548"
    },
    "004":
    {
        "spreadID":"004_135487548"
    }
}

Example "texts" JSON value:

{
    "002":
    {
        "data":"This is some plain text representing the text found on page 002 of this publication." 
    },
    "003":
    {
        "filename":"003_132647345" 
    }
}

The above will supply the plain text "This is some plain text..." to our system for Page 002. We will download the text from the filename provided for text data for Page 003.

SELF HOSTED IMAGE FILES

This endpoint is designed for use when adding or editting your JPG/TXT files when they are self hosted.

As per the above endpoint, except that your JPG and TXT files are not hosted with us. To let our database know the existance of your JPGs and the content of your searchable TXT files, you must provide a JSON encoded string containing the relevant SpreadIDs and the text for each page or spread.

This endpoint can be requested multiple times without causing any duplication within the database. It will only replace the data provided.

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/job/updateSpreads/

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (required) Your new Job ID (must be between 4 and 13 digits).
spreads json string (required) A JSON encoded string with the relevant SpreadID as the key, and its value as an object containing the new spreadID and text values.
texts json string (required) A JSON encoded string containing the relevant SpreadID as the key, either provide a "data" value containing plain text or a "filename" value containing the name of the txt file containg the page's text.
editorDesktopID string (optional) The desktopID for the user performing the update request.

Response Types

Code Description
200 Successful Inclusion into Database.
602 Missing Parameters.

Add or Edit Job Details

After uploading a new job (as above), you should call this endpoint to ensure that some basic details are stored for your job including a title and spread dimensions.

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&time=[timestamp]&width=[SpreadWidth]&height=[SpreadHeight]'
'https://www.circularsoftware.com/MasterPlan/api/admin/saveJobDetails/'

The API response object looks like the following.


{
    "status":200,
    "result":
    {
        "title":"My Job Title"
    }
}
                        

Once you've successfully uploaded Spread JPGs and requested the database crawler to generate your job (see Add New Job), you should now provide some key information about your new job so that the job is correctly displayed on the MasterPlan App.

This endpoint was designed to be call multiple times and will only replace those details which are specified in each API call.

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/saveJobDetails/

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
title string (optional) The title for your job.
width string (optional) The spread width (please use the typical width for the majority of your spreads).
height string (optional) The spread height.
slackhook string (optional) A URL pointing to a valid Slack Webhook See Slack for more details.
coverurl string (optional) A URL pointing to a valid IMAGE which will replace the uploaded cover.
author string (optional) The publication's author.
publisher string (optional) The publication's publisher.
isbn10 string (optional) A ten-digit ISBN.
isbn13 string (optional) A thirteen-digit ISBN.

Response Types

Code Description
200 Successful Update.
601 Something went wrong. (information given within "error" object)

Add or Edit Job Access

Update a job's details such as whether spreads are "Members Only" or "Searchable".

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&time=[timestamp]&overlays=[true|false]&annotator=[true|false]&annotatorNonUsers=[true|false]&hideMOSpreads=[true|false]&spreads[001][membersOnly]=[true|false]&spreads[001][revertOn]=[date]&spreads[001][searchable]=[true|false]'
'https://www.circularsoftware.com/MasterPlan/api/admin/saveJob/'

The API response object looks like the following.


{
    "status":200
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/saveJob/

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
overlays boolean (optional) Whether or not spreads have information overlays
annotator boolean (optional) Whether the job features the "annotator" tool for spreads.
annotatorNonUsers boolean (optional) If the above is "true" then whether the annotator is available for Non Registered Users.
hideMOSpreads boolean (optional) Whether Members Only spreads are visible. "True" will result in locked spreads being hidden entirely.
spreadtype string (optional) Choose between "double" and "single". Change whether the spread is a double-page or single-page spread.
viewtype string (optional) Choose between "epub", "slides" or "custom". Change what happens when a user clicks on a spread. It will be displayed in Readium (epub), in a lightbox (slides) or will open a URL in a new tab (custom).
sharedesc string (optional) Provide a description of the Job which is displayed in certain Share Dialogs (such as when sharing to Facebook).
sharelink string (optional) Provide a link (URL) to redirect users to when they click on a shared job (such as a Facebook post).
spreads array (optional) The spreads array contains SpreadID keys such as spreads[001] or spreads[002]. These in turn contain the keys "membersOnly", "revertOn" and "searchable". "revertOn" must be in the format dd/mm/yyyy hh:ii.
I.e.
spreads[001][membersOnly]=true
spreads[001][revertOn]=01/01/2022 09:00
spreads[001][searchable]=false

Response Types

Code Description
200 Successful Update.

Edit Job Mode

The following will change the provided JobID between LIVE and WIP modes.

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&time=[timestamp]&type=mode&modetype=[WIP|LIVE]'
'https://www.circularsoftware.com/MasterPlan/api/admin/saveJob/'

The API response object looks like the following.


{
    "status":200
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/saveJob/

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A UNIX timestamp string representing the current time.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
type string (required) "mode" is the only supported type.
modetype string (required) Either "LIVE" or "WIP".

Response Types

Code Description
200 Successful Update.

Add Custom URL to a Spread

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&customURL_spread=[spreadID]&customURL_url=[CUSTOM URL]&time=[timestamp]'
-X POST 'https://circularsoftware.com/MasterPlan/api/admin/saveSpreadURL/'

The API response object looks like the following.


{
    "status":200
}
                        

When the view_type for a given job is set to "Custom" then you can specify the URL which an individual spread will link to using this endpoint.

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/admin/saveSpreadURL/

HTTP POST params

The supported parameters are:

param Description
key string (required) Your authenication key.
token string (required) Your authentication token. As generated above.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
time string (required) A UNIX timestamp string representing the current time.
customURL_spread string (required) The spread which you'd like to alter the Custom URL for i.e. 018.
customURL_url string (required) A valid and properly formatted URL including the scheme (http:// or https://).

Response Types

Code Description
200 The Custom URL has been successfully set for the given SpreadID.
401 Unauthorised (details given in "error" object)
601 Parameters missing. (information given within "error" object)
602 Invalid parameters (information given within "error" object, typically a malformed URL given)

Edit Annotations

Add or edit annotations for a specific spread

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&spreadID=[spreadID]&time=[timestamp]&notes=[NOTES JSON OBJECT]&status=[statusID]' 
-X POST 'https://circularsoftware.com/MasterPlan/api/job/setSpreadAnnotations'

This endpoint allows you to add or edit the annotations on a specific spread.

The notes parameter is a JSON string containing all the relevant data for the note and should take the following format:
NOTE the sequential numbering of notes


{
    "note-1":{
        "note"      :   "The text content of the note",
        "x"         :   "X Coordinate of note i.e 937",
        "y"         :   "Y Coordinate of note i.e. 545",
        "ToolsX"    :   "X Coordinate of the Toolbox for the note, 
                        the default is the X Coordinate + 25 i.e. 962",
        "ToolsY"    :   "Y Coordinate of the Toolbox for the note, 
                        the default is the Y Coordinate - 20 i.e. 525",
        "colour"    :   "Note Icon Colour as RGB i.e. rgb(83, 164, 176)",
        "icon"      :   "A FontAwesome icon i.e. fa-comment",
        "ts"        :   "Timestamp representation of the notes created time i.e. 1501983454390"
    },
    "note-2":{
        "note"      :   "Note text here",
        "x"         :   "937",
        "y"         :   "545",
        "ToolsX"    :   "962",
        "ToolsY"    :   "525",
        "colour"    :   "rgb(83, 164, 176)",
        "icon"      :   "fa-comment",
        "ts"        :   "1501983454390"
    }
}
                        

The API response object looks like the following.


{
    "status":200,
    "result": {
        "annotations":"created",
        "status":"changed to \"Work In Progress\""  
    }
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/job/setSpreadAnnotations

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
spreadID string (required) The relevant SpreadID.
time string (required) A UNIX timestamp string representing the current time.
notes string (required) A json string of all notes, not just the ones you wish to edit.
status string (optional) The statusID you'd like to change this Spread to (i.e. "status4").

Response Types

Code Description
200 Successful alteration.

Fetch Annotations

Fetch Annotations For Spread

curl -d 'token=[accessToken]&key=[apiKey]&clientID=[clientID]&jobID=[jobID]&spreadID=[spreadID]&time=[timestamp]' 
-X POST 'https://circularsoftware.com/MasterPlan/api/job/getSpreadAnnotations'

This endpoint allows you to fetch the annotations for a given spread which will return the sketch coordinates and all notes.

The API response object looks like the following.


{
    "status":200,
    "result":{
        "sketchData":
        [
            {"x":"249.5","y":"118","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"120","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"124","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"128","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"131","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"135","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"249.5","y":"138","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"251.5","y":"139","drag":"true","color":"rgb(83, 164, 176)"},
            {"x":"257.5","y":"140","drag":"true","color":"rgb(83, 164, 176)"},
            ...
            {"x":"945.5","y":"389","color":"rgb(217, 37, 37)"},
            {"x":"956.5","y":"388","color":"rgb(217, 37, 37)"}
        ],
        "noteData": {
            "note-1": {
                "note":"Example Note 1", 
                "ToolsX":"634.5", 
                "ToolsY":"174", 
                "x":"609.5", 
                "y":"124", 
                "colour":"rgb(83, 164, 176)", 
                "icon":"fa-comment", 
                "ts":"1501964993147"
            },
            "note-2":{
                "note":"Example Note 2", 
                "ToolsX":"554.5", 
                "ToolsY":"145", 
                "x":"529.5", 
                "y":"95", 
                "colour":"rgb(217, 37, 37)", 
                "icon":"fa-comment", 
                "ts":"1502046600908"
            }
        }
    }
}
                        

HTTP Request

POST https://circularsoftware.com/MasterPlan/api/job/getSpreadAnnotations

HTTP POST params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A reference to the current timestamp used in the creation of your token.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
spreadID string (required) The relevant SpreadID.
time string (required) A UNIX timestamp string representing the current time.

Response Types

Code Description
200 Successful removal.

Response - Result

This returns a JSON ARRAY named "sketchData" which contains the individual sketch coordinates:

xThe X coordinate for the pixel
yThe Y coordinate for the pixel
dragWhether the pixel was placed individually or as part of a drag
colorThe pixel colour

It also returns a JSON OBJECT named "noteData", the notes are numerically ordered as "note-X" and each item contains a further object which contains the following information:

noteThe text value of the note
ToolsXignore
ToolsYignore
xThe X coordinate for the note
yThe Y coordinate for the note
colourThe note icon's colour
iconThe note icon (fontawesome)
tsA timestamp relating to the time the note was created

Fetch Annotation PNG

Fetch the PNG annotation for a given spread

curl -d 'clientID=[Your ClientID]&jobID=[Your JobID]&spreadID=[SpreadID]&time=[timestamp]'
'https://www.circularsoftware.com/MasterPlan/api/job/fetchPNG'

This endpoint will provide the PNG representation of the annotations to a given spread.

It will return a valid PNG image if successful.

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/job/fetchPNG

HTTP GET params

The supported parameters are:

param Description
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
spreadID string (required) The relevant SpreadID.
time string (required) A UNIX timestamp string representing the current time.

Response Types

Code Description
200 Will return an image of Content-Type "image/png".
404 Annotation not found/doesn't exist.

Move Annotations

Move all notes and sketches from one spread to another.

curl -d 'token=[accessToken]&key=[apiKey]clientID=[Your ClientID]&jobID=[Your JobID]&time=[timestamp]&spreadID=[SpreadID]&moveTo=[SpreadID]'
'https://www.circularsoftware.com/MasterPlan/api/job/moveSpreadAnnotations'

The annotations of the moveTo spreadID will be completely erased and replaced with the annotations from your SpreadID.

HTTP Request

GET https://circularsoftware.com/MasterPlan/api/job/moveSpreadAnnotations

HTTP GET params

The supported parameters are:

param Description
token string (required) A valid token for your authenticated session.
key string (required) Your unique application key.
time string (required) A reference to the current timestamp used in the creation of your token.
clientID string (required) The relevant ClientID for this client.
jobID string (required) The relevant JobID.
spreadID string (required) The relevant SpreadID for the spread you'd like to move.
moveTo string (required) The new SpreadID.

Response Types

Code Description
200 Spread Move successful.