Integration with publisher CMS Request and response JSON data formats

Request and response JSON data formats

POST requests

classifyArticle POST requests should send article data in the request body, as a JSON object in the following example:

{
    "html": "<title><h1>FA reveal bans for Port Vale's Mitch Clark and Tom Pope</h1></title><h2><p>Mitch Clark and Tom Pope were sent off in the closing stages of Port Vale's 3-2 win at Forest Green</p></h2><p>Port Vale duo Mitch Clark and Tom Pope face three and one game bans respectively.</p><p>The bans have been confirmed on the FA’s website this morning after both were sent off in last night’s 3-2 win at Forest Green Rovers.</p> ... <p><a data-content-type=\"section-topic\" data-link-tracking=\"InArticle|Link\" href=\"https://www.stokesentinel.co.uk/all-about/port-vale-fc\">For all your latest Port Vale news and analysis, click here</a></p>",
    "cmsID": "stokesentinel-3838610",
    "url": "www.stokesentinel.co.uk/sport/football/port-vale-pope-clark-bans-3838610",
    "author": "Michael Baggaley",
    "published": "2020-02-01T11:27:15.000Z",
    "lastModified": "2020-02-01T11:27:15.000Z",
    "title": "FA reveal bans for Port Vale's Mitch Clark and Tom Pope"
}

Request object details

Field nameRequired?Description
htmlOne only of html or text fields are required - if not possible to pass these then URL is mandatoryHTML markup of article content (do not include other markup from published pages such as header, footer, links or teasers for other articles)
textOne only of html or text fields are required - if not possible to pass these then URL is mandatoryPlain text version of article content
urlAt least one of url or cmsID are requiredURL that will reference the article when it is published
cmsIDAt least one of url or cmsID are requiredPublisher defined unique id for the article (represented as a string value)
titleNot mandatory, but useful for reporting and analytics.The article title. This should also be included in the html or text data to ensure it is processed by the Mantis analyser.
authorNot mandatory, but useful for reporting and analytics.The article author's name. For multiple authors format as a comma separated list of names in a single string.
publishedNot mandatory, but needed for Mantis to understand article versioningTimestamp for when article was published
lastModifiedNot mandatory, but needed for Mantis to understand article versioningTimestamp for when article content was last changed

GET requests

classifyArticle GET requests should pass the article URL or CMS id as a query parameters in the request, e.g.

https://<publisher-mantis-url>/classifyArticle?cmsID=stokesentinel-3838610

or

https://<publisher-mantis-url>/classifyArticle?url=www.stokesentinel.co.uk/s port/football/port-vale-pope-clark-bans-3838610

Response Data

Both POST and GET requests will return results in the response body as in the following examples:

Success:

Response object details

Field nameDescription
inputThis reflects the data that was sent in the original Mantis API request to analyse the article ands contains all the article metadata such as:
  • cmsID
  • URL
  • Author
  • Title
  • Published timestamp
  • Last Modified timestamp

This is in the same format as the POST endpoint request object
ratingsThis is an array of ratings using different Mantis rulesets - which can be customised for specific publications, advertising partners etc
ratings[n].customerThe name of the customer/ruleset this rating is for
ratings[n].ratingThe Brand safety rating for the article for this ruleset - values will be “RED”, “GREEN”, “AMBER”. See ratings description below for more details.
ratings[n].ruleSetVersionThe version number of the Mantis ruleset that was applied to the article to determine the Brand Safety rating.

Other fields may be present with a more detailed breakdown of the rules that resulted in the brand safety rating – if this has been enabled in the Mantis API platform.

Failure:

The response will include an ‘error’ field in the JSON data, with a description of the error that occurred.

{
    error: "Article id not found"
}