Webservices

The new Controlled Substances Squared (CS2) Hosted REST webservice has been designed to make integration as simple and quick as possible. Please note, the webservice input and output is different from the one used in the Enterprise Edition of CS2.

You simply send a list of SMILES or INCHI strings ‘FileContent’ as part of the body of the REST call, then poll the webservice for a completed response. You can then download the results as either xml, sdf or .txt files.

If you do not specify any Jurisdictions, the service will check all the jurisdictions you have licensed. Alternatively, you can specify the Countries=<x> parameter to choose the countries/jurisdictions that you are interested in from the ones you currently licence (E.g Countries=UK,Countries=USA). The current jurisdictions covered and their codes are in Appendix 1 of this document.

You can also choose whether to include precursor laws. The default is for them to be included, but they can be turned off with the parameter IncludePrecursors=False.

You may submit up to 1000 compounds per call, with responses expected within 1-2 minutes for 1000 compounds depending on the number of jurisdictions selected and input chemistry complexity.

If you need to determine the controlled status for more than one compound it is highly recommended that you batch compounds rather than sending them one at a time. CS2 Search is far more efficient like this and you cannot start a new call until the previous completes or errors.

You can perform checks on as many compounds as your Controlled Substances Squared Hosted agreement allows you to check in a day. When this limit is reached the webservice will complete and return the Response ErrorText= Code4-Daily Limit on Compound Checks Reached.

Please see our POSTMAN documentation and examples. From this you can generate the code for cURL, Jquery, Ruby, Python, Node, PHP and Go. You can also download the example calls created by Scitegrity by pressing the orange ’Run in Postman’ button in the top left-hand corner of the documentation page (this requires the POSTMAN client to be installed). We also have a Pipeline Pilot component that can be used to call the service from within Pipeline Pilot.

 

Job Responses.

When the job is running the following parameters are available:

SessionID and JobID – These are generated when the Job is started and can be used with running job to get status information.

Status – This provides the current status of the job and can take the values ‘initializing’, ‘running’, ‘complete’ or ‘error’.

StatusCode – This provides information about the result of the job whilst it is running and once it has finished. Possible returned statuscodes are:

  

Status Code

Description

0 or 1

The webservice call is being made to the server to start the job

2

Job is running

5

Job was stopped by the client or administrator

6

Job completed normally with success

7

Job completed with an error – This can be caused by incorrect input such as the wrong parameters or incorrectly formatted REST call. However, if caused by one of the following issues then specific code message is placed in the message field. 

Code1-One concurrent query only

You may only have 1 concurrent webservice call. Please wait for that to finish. Hint: - Avoid lots of small calls or 1 of 2 compounds. There is a few second start-up time for any calls. It is more efficient to send larger number of compounds to be processed at once

Code2-User not authorized

Your login is not authorized to use webservices (probably only the CS2 End). Please contact Scitegrity or use a different login

Code3-No Credits Available

Please contact Scitegrity to purchase more

Code4-Compound Checks Limit Reached

Your daily check limit has been reached. Please wait until tomorrow or contact Scitegrity to increase your daily limit.

8

The process ID associated with the running job crashed or has otherwise disappeared. This is likely due to a problem with the CS2 server. If this occurs repeatedly please contact Scitegrity.

9

Job failed to start.

12

The job is queued – The job has been sent as is currently in the queue waiting to be run

13

Lost connection with the server

 

 

Once status code 6 has been received you can then download the output results file. This is available in JSON, XML, TXT and SDF formats.

Below is a list of the parameters that are returned if the job has successfully processed compounds.

It is not the full information that is available in the CS2 Front end, for example Markush or Control code documents, but provides the key information such as how it is controlled and where.

 

Output Header

Description 

INPUT_MOLECULE

The SMILES / INCHI string entered into the search

CONTROLLED_STATUS

The controlled status e.g No, Yes, Possibly Controlled (see separate table below for details on what these are)

RESULTCOMMENTS

The CS2 reason why the substance is controlled, for example ‘This is an ester of x, all ethers esters of x are controlled’

JURISDICTIONNAME

The Jurisdiction Name

LEGISLATION NAME

The Legislation Name

SUBSTANCE LEGISLATION NAME

The name of the substance in the legislation that the compound hits (e.g Morphine)

RULENAME

A short description of the generic rule the substance is controlled under in the legislation

CODE_NAME

The controlled code name

NATIVE_LINK

A link to the legislation in its Native language

LINK

A link to the legislation translated into whatever language you specify

ADDITIONAL INFORMATION

Additional information such as:- English substance legislation name where the country in question uses a non-western character set (e.g China, Japan etc), comments on limits in the legislation, other comments in the legislation.

 

The possible values of CONTROLLED_STATUS above that can be returned are:

 

Controlled status

Description

Controlled

The molecule is controlled in the specified jurisdiction

Possibly Controlled

The substance is an analogue of a controlled substance in the specified jurisdiction, and this jurisdiction also controls analogues. This accounts for 99.999% of possibly controlled results and applies mainly to the US, Canada and Mexico

OR

The substance has been drawn flat (without stereochemistry) and hits a controlled substance where one stereoisomer is controlled while a second is specifically not controlled. Without this stereochemical information we cannot definitively state whether it is the controlled or not. When this occurs’, it is explained in the result comments. It is however incredibly rare that this happens in legislation.

No

The compound is not controlled in any of the selected jurisdictions. Note:- If a compound is not controlled in any of the selected Jurisdictions then the controlled status will just say ‘No’ – this is not replicated for each Jurisdiction. 

Not Controlled

The compound is a match for a controlled substance in the legislation for a jurisdiction, however is it specifically excluded from control OR a legislation overrides has been placed on it within CS2 by the system admins (this applies typically to Enterprise Editions).

Not Determined

The controlled status could not be determined, usually this is because either no structure or an invalid structure has been provided.

 

The SYSTEM jurisdiction names and their corresponding jurisdiction codes can be found on our list of countries covered

For testing you can run a search on the smiles string CNC(C)Cc1ccc2OCOc2c1. This returns the results for MDMA.  Clc1cc(C(c2c(O)c(c3cc2)nc(C)cc3)Nc4cc(C)ccn4)ccc1 is an example of a compound not Controlled anywhere (Controlled Status  = No). Neither will not count as a search against your account.

Bookmark and Share