ChemInventory's API enables you to build scripts to interact with the data saved in your inventory, such as to execute actions according to a programmable schedule or to integrate the system with external software.

API Authentication

ChemInventory's API is URL-based, where requests are sent to various HTTPS endpoints to retrieve or modify data in your inventory. The body of each request includes an authtoken parameter to authenticate access to the system.

These authentication tokens are tied to a given user account, with any actions carried out by that key authenticated and executed as if it were that user who initiated them. Crucially, this means that the functionality and actions available to each token are governed by the level of access the user has — that is, their privilege level . You can therefore configure token permissions through the associated user account.

It is possible to create multiple tokens for your inventory, each tied to a different user account or tied to the same account but used for different purposes. When creating a token, you can give the token a name to describe its purpose (e.g. "Weekly Export/Backup"). This can assist with token management in future, such as when revoking or rotating tokens.

Generating authentication tokens

Authentication tokens can be generated by users with Group Administrator privileges from the Inventory Management page. Open the Inventory Tools menu and click on API Tokens item.

laboratory chemical inventory api
Authentication tokens can be generated from the Inventory Management page.

When creating a new token, you will be prompted to enter a name for the token and select the user account the token is tied to. After the token has been generated, you will be able to view the token only once. You must handle this token securely as it gives full authenticated access to your inventory.

laboratory chemical inventory api
Tokens can be viewed during the generation process by clicking on the 'Acknowledge and reveal' pop up link.

It is not possible to view raw authentication tokens again, outside this initial generation process. If you lose a token, then you will need to revoke it and generate a new one.

Accessing the API

Querying an endpoint

ChemInventory's API can be accessed from the programming language of your choice, by sending a POST request to an HTTPS endpoint. Data included with your query, such as your authtoken, should be formatted as application/json.

Below is an example search query, written in NodeJS using the Axios HTTP client library: 

const axios = require('axios');

axios({
    method: "post",
    url: "https://app.cheminventory.net/api/search/execute",
    data: {
        "authtoken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "inventory": 9,
        "type": "name",
        "contents": "dipea"
    }
})
.then(response => console.log(response))

And the equivalent in Python, using the requests library: 

import requests

myRequest = requests.post(
    "https://app.cheminventory.net/api/search/execute",
    json = {
        "authtoken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "inventory": 9,
        "type": "name",
        "contents": "dipea"
    }
)

print(myRequest.text)

Your authtoken must be included in every query that you send to an endpoint. If you do not include a valid token, your request will be rejected.

Note

The root URL where you should direct queries may not be app.cheminventory.net, for example if you have a dedicated cloud installation. Please use the URL that you usually use when accessing ChemInventory in your browser.

Structure of response

All queries to endpoints return a standardized response, consisting of a JSON-formatted string with two properties: status and data. The status property indicates whether the request was processed successfully (the server will return "success" or "error") while the data property will include data retrieved from the server, or will be an empty array, depending on what endpoint was queried.

A response for the example search query above could be: 

{
    "status": "success",
    "data": {
        "orders": [],
        "containers": [
            {
                "id": 856461,
                "name": "N,N-diisopropyl ethylamine 99%",
                "location": 40032,
                "size": "50",
                "unitid": 1,
                "unit": "mL",
                "substance": 4454,
                "cas": "7087-68-5",
                "isomericsmiles": "CCN(C(C)C)C(C)C",
                "needsretrieval": 0,
                "comments": "Red label on bottle.",
                "barcode": "AEF01028",
                "supplier": "Aldrich",
                "dateacquired": "2016-06-30",
                "inventory": 9,
                "inventoryname": "Demo Group",
                "sitename": "Demo Site",
                "locationtext": "Cupboards > Cupboard 1"
            }
        ]
    }
}

In the event of an "error" status response, the data property will provide more information about the issue that has arisen.

URL Endpoints

Each of the endpoints listed below are relative to the root URL of your ChemInventory installation, plus an /api suffix. For most users, the API can be accessed at https://app.cheminventory.net/api. However, this URL may differ for you if you are covered by a Dedicated Cloud or self-hosted ChemInventory installation.

The 'Body Parameters' section under each endpoint describes the information which needs to be sent in your request body alongside the authtoken parameter. The 'Returns' section describes how information is returned from the endpoint.

/barcodes/assigned

Retrieves information listing all assigned barcodes. Only available to users with Group Administrator privileges.

Body parameters

None

Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/barcodes/duplicates/check

Gets details of existing container(s)/location(s)/user(s) which have already been assigned the barcode supplied in request. Takes into account site/enterprise level settings, if applicable.

Body parameters
barcode Required String. Barcode value to check
Returns

An object whose properties represent each duplicate barcode value. Each property is an array of objects with information about the container(s)/location(s)/user(s) that have been assigned the barcode value. 

{
    '[barcode value]': [
        { type: string, id: integer, name: string, description: string (if item is outside user's inventory) or integer (if item is in user's inventory },
        ...
    ],
    ...
}

/barcodes/duplicates/getall

Retrieves information for duplicate barcodes in the user's inventory. Takes into account site/enterprise level settings, if applicable. Available to users with administrator privileges only.

Body parameters

None

Returns

An object whose properties represent each duplicate barcode value. Each property is an array of objects with information about the container(s)/location(s)/user(s) that have been assigned the barcode value. 

{
    '[barcode value]': [
        { type: string, id: integer, name: string, description: string (if item is outside user's inventory) or integer (if item is in user's inventory },
        ...
    ],
    ...
}

/barcodes/generator/createvalues

Returns an array of potential new barcode values. Will update barcode prefix saved for inventory, if permitted, using supplied prefix parameter.

Body parameters
prefix Required String. Barcode prefix to use for each generated barcode. Up to three characters.
count Required Integer. The number of barcode values to return.
startingnumber Required Integer. The starting number to use for the new batch of barcodes.
duplicatecheck Required Boolean. Sets whether the system will generate new barcodes (and so preventing barcode duplicates). Should be always set to 'true'.
Returns

Array of strings of available barcode values. 

[ 'ABC001', 'ABC002', ... ]

/container/add

Adds new container(s) to an inventory. The locationid and substanceid values supplied for each object in the data array must be the same (endpoint will take values in data[0] and use for all subsequent entries). In effect this means that one endpoint call can be used to add multiple containers of the same substance to the same location.

An example container addition process can be found in the Example Workflows section at the bottom of this page.

Body parameters
data Required Array. Array of objects holding information about each new container record to create.

Each of the objects in the data array should be of the format below: 

{
    name: string,          [required]
    locationid: integer,   [required]
    substanceid: integer,  [required]
    supplier: string,
    barcode: string,
    containersize: string,
    units: integer,        [ID of unit for containersize. Available list can be retrieved from /general/units endpoint]
    comments: string,
    dateacquired: string,  [format YYYY-MM-DD]
    cf-[fieldid]: string   [custom container field information, if applicable]
}
Returns

Returns array listing IDs of newly created container(s). 

[ 1, 2, 3, ... ]

/container/delete

Deletes specified container(s).

Body parameters
containerid Required Array. Array of integers of container ID(s) to be deleted.
Returns

None.

/container/getsubstance

Retrieves substance information using details supplied. If not already present in database, adds new substance record. If substanceid supplied, retrieves substance info for specified substance.

Body parameters
name Required String. The name of the substance (e.g. "acetone").
cas Required String. The CAS number of the substance (can be "N/A" if no CAS number assigned, such as for in-house made compounds).
substanceid Integer. The ID number of an existing substance. Include this when retrieving substance information for a known substance, e.g. from container results.
Returns

An array of objects holding information of the target substance(s). More than one substance may be returned, e.g. if name is ambiguous with "N/A" supplied for cas. For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database. 

[
    {
        "id": 382144,
        "name": "Triphenylphosphine",
        "cas": "603-35-0",
        "isomericsmiles": "C1C=C(P(C2C=CC=CC=2)C2=CC=CC=C2)C=CC=1",
        "customsubstance": 0,
        "needsretrieval": 0,
        "molecularweight": "262.292",
        "substancefields": [],
        "ghs": [
            {
                "substanceid": 382144,
                "id": 1190,
                "inventory": 0,
                "site": 0,
                "enterprise": 0,
                "source": "Sigma-Aldrich",
                "dateset": "2016-11-26 19:46:35",
                "edituser": 0,
                "firstname": null,
                "lastname": null,
                "hazardstatements": "H302|H317|H373"
            }
        ]
    }
]

/container/ghs/delete

Deletes a GHS entry.

Body parameters
entryid Required Integer. ID of target GHS entry.
Returns

None.

/container/ghs/save

Either updates an existing entry or adds a new ghs entry (if entryid is 0).

Body parameters
entryid Required Integer. ID of target GHS entry, or 0 to create new entry.
hcodes Required Array. Array of strings representing hazard codes, e.g. [ "H225", "H410" ].
source Required String. The source of the GHS entry, which is displayed to users (e.g. "Sigma Aldrich").
substance Required Integer. ID of target substance.
Returns

Object listing the ID number of the affected GHS record. If entryid was 0, this is the ID of the newly added record. 

{
    id: 8226
}

/container/information/gethistory

Retrieves full history & audit logs for a container.

Body parameters
containerid Required Integer. ID of target container.
Returns

Array of arrays, representing all logs for container. Entries may not be listed in chronological order. Timestamps are in the UTC timezone. 

[
    [
        "2020-01-29 19:57:54",
        "Smith, Andrew",
        "Creation",
        "Container added to database"
    ],
    [
        "2020-04-02 13:47:55",
        "Mayfair, John",
        "Edit",
        "Product Code changed from \"UPG159-0\" to \"UPG159-0-12\""
    ],
    ...
]

/container/information/load

Retrieves all information saved for specified container, including custom fields.

Body parameters
containerid Required Integer. ID of target container.
Returns

Object listing information for requested container. For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database. 

{
    "id": 856461,
    "barcode": "AEF01028",
    "containername": "N,N-diisopropyl ethylamine 99%",
    "inventory": 1,
    "location": 40032,
    "locationString": "Cupboards > Cupboard 1",
    "size": "50",
    "unitid": 1,
    "unit": "mL",
    "supplier": "Aldrich",
    "comments": "Red label on bottle.",
    "dateacquired": "2016-06-30",
    "inrecycling": 0,
    "substance": 4454,
    "cas": "7087-68-5",
    "molecularformula": "C8H19N",
    "molecularweight": "129.24316",
    "isomericsmiles": "CCN(C(C)C)C(C)C",
    "needsretrieval": 0,
    "exactmass": "129.15175",
    "iupacname": "N-ethyl-N-propan-2-ylpropan-2-amine",
    "cf-362": "UPG159-05",
    "cf-363": "2022-10-26",
    "ghs": [
        {
            "substanceid": 4454,
            "id": 1336,
            "inventory": 0,
            "site": 0,
            "enterprise": 0,
            "source": "Sigma-Aldrich",
            "dateset": "2016-11-26 19:47:17",
            "edituser": 0,
            "firstname": null,
            "lastname": null,
            "hazardstatements": "H225|H302|H318|H331|H335"
        }
    ],
    "files": []
}

/container/information/save

Updates value saved for a field of a container.

Body parameters
containerid Required Integer. ID of target container.
field Required String. Must be one of 'containername', 'cas', 'containersize', 'barcode', 'supplier', 'supplier', 'dateacquired', 'comments', 'cf-[id]', 'sf-[id]'.
newvalue Required string, or object for 'containersize'. The new value for the field.

When setting 'containersize', an object of format { size: 250, unit: "g" } must be supplied for newvalue.

Returns

None.

/container/information/togglerecycling

Toggles recycling status of container, if recycling is enabled for the inventory's site. Only available within site and enterprise licenses.

Body parameters
containerid Required Integer. ID of target container.
Returns

None.

/container/move

Moves specified container(s) to specified location.

Body parameters
containerid Required Array. Array of integers of container ID(s) to be moved.
destinationid Required Integer. The ID of the destination location.
Returns

An array of container ID(s) which were processed successfully (i.e. moved). 

[ 1, 2, 3, ... ]

/container/recentlyadded

Returns details of containers added to the user's inventory within last 30 days. Only available to users with Group Administrator privileges.

Body parameters

None

Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/customfields/delete

Deletes specified custom field.

Body parameters
id Required Integer. ID of target custom field.
fieldtype Required String. Type of custom field being deleted. Either 'container' or 'substance'.
Returns

None.

/customfields/get

Retrieves full list of custom fields available to user.

Body parameters

None.

Returns

Object with custom field information. 

{
    "container": [
        {
            "id": 363,
            "name": "Expiry Date",
            "type": "date",
            "inventory": 9,
            "site": 0,
            "enterprise": 0,
            "hidden": "0",
            "searchable": 0,
            "allowedvalues": "",
            "showfororders": 0
        },
        ...
    ],
    "substance": [
        {
            "id": 870,
            "name": "Example Substance Dropdown",
            "type": "dropdown",
            "inventory": 9,
            "site": 0,
            "enterprise": 0,
            "hidden": "0",
            "searchable": 1,
            "allowedvalues": [
                "VAL1",
                "VAL2"
            ],
            "admineditonly": 0
        }
    ]
}

/customfields/save

Either updates an existing custom field or creates a new custom field (if id is 0).

Body parameters
id Required Integer. ID of target custom field (0 to create new field).
fieldtype Required String. Type of custom field being modified (or added, if id is 0). Either 'container' or 'substance'.
name Required String. The name of the custom field.
type Required String. The data type of the field. One of 'text', 'multilinetext', 'number', 'date', 'url', 'dropdown', 'tags'.
searchable Boolean. Set to true if field should appear on 'Search' page in ChemInventory.
admineditonly Boolean. Only applies to substance fields. Set to true to limit editing rights to inventory administrators.
allowedvalues Array of strings. Only applies to type of 'tags' and 'dropdown'. Determines allowed list of values users can choose from, e.g. [ 'Value 1', 'Value 2', ... ]
showfororders Boolean. Only applies to container fields. Set to true to configure field to be shown/available for values to be specified for order requests.
Returns

The ID number of the affected custom field. If id was 0, this is the ID of the newly created field. 

5361

/filestore/addsubstancelink

Adds a new substance link to a file.

Body parameters
fileid Required Integer. The ID of the file to be updated.
substanceid Required Integer. The ID of the substance to be linked to fileid.
Returns

None.

/filestore/createcategory

Creates a new file category.

Body parameters
name Required String. The name of the new category.
scope Required String. The scope/level that the category should be created in. One of 'inventory', 'site', 'enterprise'. Should always be set to 'inventory', unless user is a site or enterprise administrator.
Returns

ID of newly created category. 

480

/filestore/deletecategory

Deletes specified file category.

Body parameters
id Required Integer. The ID of the category to delete.
Returns

None.

/filestore/deletefile

Deletes a file.

Body parameters
fileid Required Integer. The ID of the file to be deleted.
Returns

None.

/filestore/download

Retrieves a URL where the file can be downloaded from. The URL is time-sensitive, and will expire after 30 minutes.

Body parameters
fileid Required Integer. The ID of the file to download.
Returns

Time-sensitive URL where the file can be accessed. 

"https://[URL]"

/filestore/getlinkedfiles

Retrieves files that are linked to specified substance.

Body parameters
substanceid Required Integer. The ID of the substance to be queried.
Returns

Array of objects. 

[
    {
        "id": 186451,
        "name": "(S)-(-)-2-(Fluorodiphenylmethyl)pyrrolidine.pdf",
        "categoryid": 480,
        "size": 104550,
        "dateuploaded": "2021-06-13 23:24:45",
        "mimetype": "application/pdf",
        "inventory": 9,
        "site": 0,
        "enterprise": 0
    },
    ...
]

/filestore/getsubstancelinks

Gets list of substances that file is currently linked to.

Body parameters
fileid Required Integer. The ID of the file to be queried.
Returns

Array of objects. 

[
    {
        "id": 5421,
        "name": "(S)-(-)-2-(Fluorodiphenylmethyl)pyrrolidine",
        "cas": "274674-23-6"
    },
    ...
]

/filestore/load

Retrieves file storage information available to user, including file categories and files themselves. For users within a site/enterprise structure, organization-wide file store data are also retrieved.

Body parameters
scope Required String. The scope of information to retrieve. One of 'inventory', 'site', 'enterprise'. Should always be set to 'inventory'.
Returns

Object with two properties: categories which lists the file categories available to user, and files which lists information about all files available to user. 

{
    "categories": [
        {
            "id": 480,
            "name": "(M)SDS",
            "inventory": 9,
            "site": 0,
            "enterprise": 0,
            "datecreated": "2017-11-21 11:14:04",
            "hidden": "0"
        },
        ...
    ],
    "files": [
        {
            "id": 186451,
            "name": "(S)-(-)-2-(Fluorodiphenylmethyl)pyrrolidine.pdf",
            "categoryid": 480,
            "size": 104550,
            "dateuploaded": "2021-06-13 23:24:45",
            "inventory": 9,
            "site": 0,
            "enterprise": 0,
            "substancelinkcount": 1,
            "firstname": "Andrew",
            "lastname": "Smith"
        },
        ...
    ]
}

/filestore/removesubstancelink

Removes a substance link from a file.

Body parameters
fileid Required Integer. The ID of the file to be updated.
substanceid Required Integer. The ID of the substance to be removed from fileid.
Returns

None.

/filestore/renamecategory

Renames specified file category.

Body parameters
id Required Integer. The ID of the category to be updated.
name Required String. The new name of the category.
Returns

None.

/filestore/renamefile

Renames a file.

Body parameters
fileid Required Integer. The ID of the file to be renamed.
filename Required String. The new name of the file (including file extension).
Returns

None.

/filestore/updatefilecategory

Updates category for specified file.

Body parameters
fileid Required Integer. The ID of the file to be updated.
newcategoryid Required Integer. The ID of the new category to assign to the file. For 'No Category', set to 0.
Returns

None

/general/exportbyid

Retrieves all information saved for specified containers.

Body parameters
containerids Required Array of Integers. The IDs of each container to be included in the export.
Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/general/getdetails

Gets general inventory and user information about the account associated with the API key. This includes IDs of the user account and inventory, along with suppliers, units, custom fields and locations. Effectively a 'one stop shop' for all data needed for subsequent requests.

Body parameters

None

Returns

Object listing user and inventory information. 

{
    "user": {
        "id": 178,
        "version": 0,
        "sso": false,
        "email": "demo@cheminventory.net",
        "inventory": 9,
        "inventoryname": "Demo Group",
        "inventoryTableLayout": null,
        "accounttype": 2,
        "firstname": "ChemInventory",
        "lastname": "Administrator",
        "barcode": null,
        "dateformat": {
            "id": 4,
            "jsformat": "d M yy",
            "momentformat": "D MMM YYYY",
            "placeholder": "Day month year"
        },
        "resetpassword": 0,
        "tandcnew": 0,
        "gettingstarted": "2020-08-14 14:28:20",
        "siteadmin": 0,
        "enterpriseadmin": 0,
        "preferences": {
            "limitlocations": {
                "9": []
            },
            "namesearch": "exact",
            "ns": "exact",
            "ll": {},
            "gl": {
                "w": 100,
                "h": 60
            }
        },
        "emailfeatures": true,
        "emailsharinginstitution": true,
        "otherInventories": [],
        "isDemo": true,
        "inventorysite": 29,
        "sitecountry": "226",
        "inventoryenterprise": 4,
        "siteenterprise": 4,
        "sitename": "Demo Site",
        "enterprisename": "Enterprise Demo",
        "expired": false,
        "expirytype": ""
    },
    "inventory": {
        "id": 9,
        "version": 99,
        "activestocktake": false,
        "enableuserbarcode": false,
        "allowcontainermovements": true,
        "barcodeprefix": "AA",
        "containerfieldlayout": null,
        "containerlimit": 0,
        "enablebarcodeprefixedit": false,
        "enablelocationbarcode": false,
        "enableuserdelete": true,
        "name": "Demo Group",
        "renewaldate": "0",
        "restrictcontainers": false,
        "restrictusers": false,
        "tablelayout": "collection|name|size|location|actions",
        "trialexpires": "0",
        "userlimit": 50,
        "enablerecycling": false,
        "country": "226",
        "countryname": "United Kingdom",
        "vatrate": "0",
        "filesizelimit": 10737418240,
        "site": 29,
        "sitename": "Demo Site",
        "enablesso": false,
        "enterprise": 4,
        "enterprisename": "Enterprise Demo",
        "units": [
            {
                "id": 5,
                "unit": "g"
            },
            ...
        ],
        "suppliers": [
            {
                "name": "Sigma Aldrich"
            },
            ...
        ],
        "customfields": {
            "container": [
                {
                    "id": 363,
                    "name": "Expiry Date",
                    "type": "date",
                    "allowedvalues": "",
                    "searchable": 1
                },
                ...
            ],
            "substance": []
        },
        "sharing": [],
        "locations": {
            "9": {
                "name": "Demo Group",
                "locations": [
                    {
                        "id": 381552,
                        "barcode": null,
                        "location": "Stores",
                        "parent": 0,
                        "inventory": 9
                    },
                    ...
                ]
            }
        }
    }
}

/general/retrievesubstanceinfo

Sources chemical information for a new substance, including chemical structure and synonyms. Only applies to substances with a CAS number (i.e. commercially-available).

Body parameters

substance Required Integer. The ID of the substance to be updated.

Returns

The isomeric smiles of the substance. 

"C1C=CC=CC=1"

/general/units

Gets information of container size units that already exist in user's inventory.

Body parameters

None

Returns

An array of objects of existing units available to user. 

[
    {
        "id": 5,
        "unit": "g"
    },
    ...
]

/general/updatestructure

Updates structure for specified substance. If the structure matches an already-existing substance, the existing ID will be returned.

Body parameters
substanceid Required Integer. The ID of the substance to update.
newmolfile Required String. The new structure in the molfile format (or as SMILES).
Returns

A substance ID. This may be different from substanceid, e.g. if newmolfile matches an existing substance. 

459193

/inventorymanagement/audithistory/load

Retrieves activity logs for user's inventory within specified date range.

Body parameters

startdate Required String. The start date of the logs to retrieve (in format YYYY-MM-DD).
enddate Required String. The end date of the logs to retrieve (in format YYYY-MM-DD).

Returns

Array of arrays, representing all logs within date range. Entries may not be listed in chronological order. Timestamps are in the UTC timezone. 

[
    [
        "2022-03-16 01:51:20",
        "Smith, Andrew",
        "Container",
        "Movement",
        "N,N-diisopropyl ethylamine 99% (AEF01028) moved from \"Demo Group > Personal > E. Allen\" to \"Demo Group > Cupboards > Cupboard 1\""
    ],
    ...
]

/inventorymanagement/deletedcontainers/export

Exports full information about all deleted containers, including custom fields.

Body parameters

None

Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/inventorymanagement/deletedcontainers/get

Retrieves a summary list of all deleted container records in user's inventory.

Body parameters

None

Returns

Array of objects summarising deleted container records, including the ID of each container. datedeleted is in the UTC timezone. 

[
    {
        "id": 855552,
        "datedeleted": "2022-04-21 03:29:58",
        "containername": "Gold (I) chloride",
        "barcode": "AEF00120",
        "user": "Andrew Smith (Demo Group)"
    },
    ...
]

/inventorymanagement/deletedcontainers/restore

Restores a deleted container, including its parent location(s).

Body parameters

id Required Integer. The ID of the container to restore.

Returns

None

/inventorymanagement/export

Exports full information about all containers in user's inventory, including custom fields.

Body parameters

None

Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/inventorymanagement/users/add

Creates a new user account in specified inventory.

Body parameters

email Required String. The user's email address.
firstname Required String. The user's first name.
lastname Required String. The user's last name.
accounttype Required Integer. The privilege level of the user account. Must be one of 2 [group administrator], 3 [order handler], 4 [user] or 6 [read-only]
inventory Required Integer. The ID of the inventory to add the user to.
barcode String. The barcode value to assign to the new user account, if applicable.
sso Boolean. Sets whether the new user account should sign in with SSO. Only available to inventories within a site/enterprise license which has SSO enabled.

Returns

The ID of the newly created user. 

23425

/inventorymanagement/users/disable

Removes access for specified user from specified inventory.

Body parameters

id Required Integer. The ID of the user to remove.
inventory Required Integer. The ID of the target inventory.

Returns

None.

/inventorymanagement/users/list

Retrieves user accounts within specified. Available to users with administrator privileges only.

Body parameters

inventory Required Integer. The ID of the inventory to retrieve user data from. Should always be set to user's inventory (unless within site/enterprise).

Returns

Returns array of objects with user data. Account type represents the privilege level of the user, and is one of 2 [group administrator], 3 [order handler], 4 [user] or 6 [read-only] 

[
    {
        "id": 2254,
        "email": "d.matthews@cheminventory.net",
        "accounttype": 4,
        "firstname": "David",
        "lastname": "Matthews",
        "barcode": null,
        "sso": 0
    },
    ...
]

/inventorymanagement/users/resetpassword

Resets the password for specified user. Cannot be used with SSO accounts.

Body parameters

id Required Integer. The ID of the user to set the new password for.
password Required String. The new password with a minimum of 8 characters.

Returns

None.

/inventorymanagement/users/update

Updates details of user account (email, name, etc.).

Body parameters

id Required Integer. The ID of the user to update.
accounttype Required Integer. The privilege level of the user account. Must be one of 2 [group administrator], 3 [order handler], 4 [user] or 6 [read-only]
firstname Required String. The user's first name.
lastname Required String. The user's last name.
email Required String. The user's email address.
inventory Integer. If the target user has access to more than one inventory (within a site/enterprise license), then the target inventory for the change can be included here. This is applicable only when changes are made to the user's accounttype.

Returns

None.

/location/containers/delete

Deletes all containers in specified location.

Body parameters

locationid Required Integer. The ID of the target location.

Returns

None.

/location/containers/get

Retrieves containers in specified location.

Body parameters

locationid Required Integer. The ID of the location to query.

Returns

An object listing summaries of container(s) currently saved in the specified location. The properties of the container entries may change depending on the table column format saved for the user's inventory (more details about table layouts can be found at https://www.cheminventory.net/support/inventory-management/customizing-tables/). To retrieve full information saved for containers, use the /container/information/load endpoint for individual records or the /general/exportbyid endpoint for multiple records.

For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database.

The format of the returned information follows that of search results. 

{
    "orders": [],
    "containers": [
        {
            "id": 6280879,
            "name": "1-adamantanol 99%",
            "location": 381572,
            "size": "25",
            "unitid": 5,
            "unit": "g",
            "substance": 8303,
            "cas": "768-95-6",
            "isomericsmiles": "C1C2CC3CC1CC(C2)(C3)O",
            "needsretrieval": 0,
            "comments": "None",
            "barcode": "AEF01220",
            "supplier": "Sigma",
            "dateacquired": "2012-05-08",
            "inventory": 9,
            "inventoryname": "Demo Group",
            "sitename": "Demo Site",
            "locationtext": "Cupboards > Cupboard 1"
        },
        ...
    ]
}

/location/containers/move

Moves all containers from origin location to destination location.

Body parameters

origin Required Integer. The ID of the origin location (where containers are being moved from).
destination Required Integer. The ID of the destination location (where containers are being moved to).

Returns

None.

/location/load

Retrieves all locations in user's inventory, including IDs.

Body parameters

None

Returns

Array of objects. The id parameter is the ID of the location, parent parameter is the ID of the location's parent (if the location is a child in the locations hierarchy) and numbercontainers is the number of containers currently saved in the location. If the location is at the root level in the hierarchy, parent will be 0. 

[
    {
        "id": 381572,
        "name": "Cupboard 1",
        "barcode": null,
        "parent": 381555,
        "numbercontainers": 94
    },
    ...
]

/mycollection/add

Adds specified container(s) to user's 'My Collection'.

Body parameters

containerid Required Integer, or Array of Integers. The ID(s) of the container(s) to add.

Returns

None.

/mycollection/addbybarcode

Adds containers to user's 'My Collection', identifying container(s) by barcode(s).

Body parameters

barcode Required Array. Array of strings of container barcodes to add. Barcode matching using this endpoint is case-insensitive.

Returns

Returns object. Any barcodes that couldn't be processed, for example if no matching container was found, will be included in the errorBarcodes parameter. 

{
    errorBarcodes: [ "ABC123" ]
}

/mycollection/deleteall

Delete all containers in user's 'My Collection'.

Body parameters

None.

Returns

None.

/mycollection/load

Retrieves containers currently saved in user's 'My Collection'.

Body parameters

None

Returns

Array of objects. The sid property of each container is the substance ID. For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database. 

[
    {
        "id": 6280879,
        "name": "1-adamantanol 99%",
        "location": 381572,
        "inventory": 9,
        "barcode": "AEF01220",
        "disposed": "0",
        "inventoryname": "Demo Group",
        "isomericsmiles": "C1C2CC3CC1CC(C2)(C3)O",
        "needsretrieval": 0,
        "cas": "768-95-6",
        "sid": 8303
    },
    ...
]

/mycollection/moveall

Moves all containers in user's 'My Collection' to a specified location.

Body parameters

destinationid Required Integer. The ID of the destination location.

Returns

None.

/mycollection/remove

Removes specified container from user's 'My Collection'.

Body parameters

containerid Required Integer. The ID of the container to remove.

Returns

None.

/mycollection/removeall

Removes all containers from user's 'My Collection'.

Body parameters

None.

Returns

None.

/navbar/switchinventory

Switches the active inventory for user, if user has access to more than one inventory. Note: this endpoint should rarely be used. It is only available to users within site/enterprise licenses.

Body parameters

newinventory Required Integer. The ID of the inventory to switch into.

Returns

None.

/order/addcontainer

Adds container to inventory, marks order request as arrived. Note: most details for corresponding container record are retrieved automatically from order request (size, supplier, etc.).

Body parameters

orderid Required Integer. The ID of the request to process.
name Required String. The name to be assigned to the new container.
comments String. Any comments to be saved against the order request.
locationid Required Integer. The ID of the location where the new container will be saved.
cf-[id] String. The values for any custom fields can be saved for the container at this time. Replace [id] with the ID of the container custom field to save (e.g. cf-425).

Returns

None.

/order/delete

Deletes specified order request.

Body parameters

orderid Required Integer. The ID of the request to delete.

Returns

None.

/order/edit

Updates specified order request.

Body parameters

orderid Required Integer. The ID of the request to update.
containersize Required String. The container size for the order request.
units Required Integer. The ID of the unit associated with size. List of available units and IDs can be retrieved from the /general/units endpoint
supplier Required String. The supplier name for the order.
comments String. Any comments to be saved against the order request.
destinationlocation Integer. ID of the destination location where it is requested the order's eventual container record is created. Set to 0 (default value) to not specify a location.
cf-[id] String. Only applies if user's inventory has custom container fields set with 'Show for Orders'. Replace [id] with the ID of the container custom field for which to save a value (e.g. cf-425).

Returns

An object listing the values as saved for the request. 

{
    "suppliername": "Sigma Aldrich",
    "supplierid": 53,
    "size": "1000",
    "containersize": "1000",
    "unitid": "5",
    "units": "5",
    "customfield1": "",
    "customfields": "{}",
    "comments": "Product Number: ABC-123\nPurity: 99%",
    "destinationlocation": 0
}

/order/load

Retrieves current active order requests in user's inventory.

Body parameters

None

Returns

Array of objects listing active order requests. For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database. 

[
    {
        "id": 817,
        "name": "Triphenylphosphine",
        "substanceid": 382144,
        "size": "1000",
        "unitid": 5,
        "supplierid": 53,
        "customfield1": "",
        "customfields": {},
        "userid": 178,
        "comments": "Product Number: ABC-123\nPurity: 99%",
        "datesubmitted": "2023-02-04 16:57:31",
        "dateordered": "0",
        "firstname": "ChemInventory",
        "lastname": "Administrator",
        "inventoryid": 9,
        "inventoryname": "Demo Group",
        "destinationlocation": 0,
        "unit": "g",
        "suppliername": "Sigma Aldrich",
        "cas": "603-35-0",
        "isomericsmiles": "C1C=C(P(C2C=CC=CC=2)C2=CC=CC=C2)C=CC=1",
        "needsretrieval": 0,
        "name-value": "triphenylphosphine",
        "user": "ChemInventory Administrator",
        "user-value": "cheminventory administrator",
        "datesubmitted-value": "2023-02-04 16:57:31",
        "dateordered-value": "0"
    },
    ...
]

/order/request

Creates a new order request in user's inventory.

Body parameters

substanceid Required Integer. The ID of the substance associated with the request.
quantity Integer. The number of identical requests to add. Defaults to 1.
supplier Required String. The supplier name for the order.
name Required String. The container name for the order request.
containersize Required String. The container size for the order request.
units Required Integer. The ID of the unit associated with containersize. List of available units and IDs can be retrieved from the /general/units endpoint
comments String. Any comments to be saved against the order request
statuschangeemail Boolean. If set to true, the user will receive an email when the status of the request is updated (marked as placed, or corresponding container added). Defaults to false
destinationlocation Integer. ID of the destination location where it is requested the order's eventual container record is created. Set to 0 (default value) to not specify a location
cf-[id] String. Only applies if user's inventory has custom container fields set with 'Show for Orders'. Replace [id] with the ID of the container custom field for which to save a value (e.g. cf-425).

Returns

None.

/order/toggleordered

Toggles specified request's ordered status.

Body parameters

orderid Required Integer. The ID of the request to update.

Returns

The new value of the dateordered property for the request (either 0 or UTC timestamp). 

"2022-04-22 03:20:59"

Executes search against specified inventory. Processes any results found using the 'limit search to' as saved against user account (this may strip results). The user's 'limit search to' can only be modified through ChemInventory's user interface.

Body parameters

inventory Required Integer or String. The ID of the inventory to search. Usually this is the user's inventory, but can be shared inventories also (more details below).
type Required String. The type of search to execute (more details below).
contents Required String or Object. The contents of the search query to run (more details below).

The inventory parameter is the scope/target of the search. Can be either an integer (the ID of target inventory), or if conducting a search at a site/enterprise level then can be 'site' or 'enterprise'. If recycling is enabled within site, inventory can also be 'recycling'.

The type parameter determines what field/property should be searched against. Can be one of 'name' (which automatically includes substance synonyms), 'cas', 'barcode', 'ghs', 'advanced', 'exactstructure', 'substructure', 'substanceid', 'containerid' or custom fields following the format below.

If running a structure search (type is either 'exactstructure' or 'substructure'), then the contents parameter should be in the molfile format. Isomeric SMILES can also be submitted, but stereocenters may not be respected.

When running a search against a custom field (container or substance), the format of the type parameter differs from other API endpoints: it includes the data type of the field. For example, 'sf-dropdown-[id]' (for an example dropdown substance field) or 'cf-date-[id]' (for a date container field). This is to further speed up search execution server-side.

When running GHS searches (type is 'ghs'), the contents parameter should be an object of the format: 

{
    "searchtype": "or",
    "items": [
        "H200",
        "H201",
        ...
    ]
}

When running advanced searches (type is 'advanced'), the contents parameter should follow the format output by the QueryBuilder library (use the queryBuilder('getRules') method).

Returns

An object listing summaries of container(s) found for the search. The properties of the container entries may change depending on the table column format saved for the user's inventory (more details about table layouts can be found at https://www.cheminventory.net/support/inventory-management/customizing-tables/). To retrieve full information saved for containers, use the /container/information/load endpoint for individual records or the /general/exportbyid endpoint for multiple records.

For any results where needsretrieval is 1 and a CAS number has been assigned (i.e. cas is not "N/A"), then the /general/retrievesubstanceinfo endpoint should be queried to update the core substance record in user's database. 

{
    "orders": [],
    "containers": [
        {
            "id": 856461,
            "name": "N,N-diisopropyl ethylamine 99%",
            "location": 40032,
            "size": "50",
            "unitid": 1,
            "unit": "mL",
            "substance": 4454,
            "cas": "7087-68-5",
            "isomericsmiles": "CCN(C(C)C)C(C)C",
            "needsretrieval": 0,
            "comments": "Red label on bottle.",
            "barcode": "AEF01028",
            "supplier": "Aldrich",
            "dateacquired": "2016-06-30",
            "inventory": 9,
            "inventoryname": "Demo Group",
            "sitename": "Demo Site",
            "molecularformula": "C18H15P",
            "molecularweight": "262.292",
            "locationtext": "Cupboards > Cupboard 1"
        },
        ...
    ]
}

/search/loadadvancedsearch

Loads advanced search options, following format to meet requirements of https://querybuilder.js.org/.

Body parameters

None.

Returns

Array of objects listing available advanced search options, including custom fields. 

[
    {
        "id": "name",
        "label": "Name",
        "type": "string"
    },
    {
        "id": "cf-363",
        "field": "date",
        "label": "Expiry Date",
        "type": "date",
        "plugin": "datepicker",
        "plugin_config": {
            "dateFormat": "d M yy"
        }
    },
    ...
]

/watchlist/checksubstance

Checks whether a specified substance appears on any watchlists.

Body parameters

substanceid Required Integer. The ID of the substance check.

Returns

Array of objects for any applicable watchlists. If the substance doesn't appear on any watchlists, then an empty array will be returned. 

[
    {
        watchlistid: 1,
        watchlistname: 'United States DHS Appendix A Chemicals',
        hassubstance: true
    },
    ...
]

/watchlist/delete

Deletes a custom watchlist.

Body parameters

id Required Integer. The ID of the watchlist to delete.

Returns

None

/watchlist/generatereport

Generates watchlist report for specified watchlist.

Body parameters

id Required Integer. The ID of the watchlist.
scope Required String. One of 'inventory', 'site' or 'enterprise'. Specifies whether the report should be generated at the inventory, site or enterprise level. Should usually be set to 'inventory', unless user is a site or enterprise administrator.

Returns

An object representing a table of results, where the columns property is an array of objects holding information for each column in the table and the rows property is an array of objects representing the rows. The properties of each object in rows map to the key property in columns 

{
    columns: [
        { header: 'Title for column 1', key: key1 },
        { header: 'Title for column 2', key: key2 },
        ...
    ],
    rows: [
        { key1: value, key2: value, ... },
        ...
    ]
}

/watchlist/load

Retrieves watchlists accessible by user (including custom watchlists defined at the site and enterprise levels, if applicable).

Body parameters

None.

Returns

Object listing global (ChemInventory-managed) watchlists as well as custom watchlists defined at the inventory, site and enterprise levels. This includes the search terms which define the watchlist. 

    {
        "global": [
            {
                "id": 117,
                "name": "Chemical Weapons Convention - Schedule 2",
                "terms": [
                    "100-35-6",
                    ...
                ],
                "emailalert": []
            },
            ...
        ],
        "inventory": [ ... ],
        "site": [ ... ],
        "enterprise": [ ... ]
    }

/watchlist/save

Updates the details of a watchlist, or creates a new one if id is 0.

Body parameters

id Required Integer. The ID of the watchlist to update, or set to 0 to create a new watchlist.
scope Required String. One of 'inventory', 'site' or 'enterprise'. Specifies whether the update/creation should occur at the inventory, site or enterprise level. Should usually be set to 'inventory', unless user is a site or enterprise administrator.
name Required String. The name of the watchlist.
terms Required Array of Strings. The search terms of the watchlist.

Returns

None

Example Workflows

The sections below show some example query/request workflows for common activities in ChemInventory. We will add sections over time based on feedback and queries our support team receives.

Adding a new container

New container records can be added to an inventory using the /container/add endpoint. As part of requests to this endpoint, prerequisite information needs to be gathered first, including substance, location and unit IDs.

In Summary
  1. Get location and units ID values (/general/getdetails)
  2. Get substance ID value (/container/getsubstance)
  3. Create container (/container/add)
Step 1 — General Information

As part of your /container/add request, you need to supply information for locationid and units. This information can be retrieved from a couple of different sources:

We recommend that you use the /general/getdetails endpoint, as all location, units and custom field data is returned at the same time. This information can be cached the data for longer-term use which will save you from retrieving information repeatedly for future requests. In this case, the locationid and units values can be sourced from the data.inventory.locations and data.inventory.units properties of the response.

Alternatively, you can retrieve location information from the /location/load endpoint and units information from /general/units.

Step 2 — Substance Information

The next step is to use the /container/getsubstance endpoint to retrieve the substance ID for the container you wish to add.

If the needsretrieval property of the response is 1, and the substance has a CAS number assigned, then you should also send a query to /general/retrievesubstanceinfo. This will prompt ChemInventory to run some background activity to automatically source the structure and synonyms for the substance record.

Step 3 — Custom Fields (optional)

If your inventory has any custom fields, such as "Expiry Date" or "Product Code" in the demo inventory, then you can also prepare this information as part of your request. The example below includes this data. Note that for 'Date' fields, data should be submitted in the "YYYY-MM-DD" format.

Step 4 — Create Container

With all the prerequisite information to hand, you can now send the information to ChemInventory to create the new container record. Use the /container/add endpoint.

For example, the request body below will create one new container of acetone in the demo inventory. 

const axios = require('axios');

axios({
    method: "post",
    url: "https://app.cheminventory.net/api/container/add",
    data: {
        "authtoken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "data": [
            {
                "name": "Acetone",
                "locationid": 40032,        // This is the Cupboards > Cupboard 1 location in the Demo inventory
                "substanceid": 537219,      // This specifies that acetone is the substance
                "supplier": "Sigma Aldrich",
                "barcode": "ABC123",
                "containersize": "250",
                "units": 1,                 // Sets 'mL' as the unit
                "comments": "",
                "dateacquired": "2022-04-25",
                "cf-362": "Sigma: 179124",  // Product code
                "cf-363": "2024-04-25"      // Expiry date
            }
        ]
    }
})
.then(response => console.log(response))

Finding expired chemicals

This example assumes that you have a custom field defined in your inventory in which you store the expiry date for containers. For more information about custom fields, including how to create them through the UI, please refer to the custom fields support page .

In order to search by date range, you need to execute a search with a type of "advanced". ChemInventory expects any data submitted for advanced search requests to follow the format as output from the QueryBuilder library (use the queryBuilder('getRules') method).

In Summary
  1. Get ID of custom field (/general/getdetails)
  2. Execute search (/search/execute)
Step 1 — Get field ID

Before submitting a search using a custom field, you need to identify what its ID number is. This can be achieved from either the /general/getdetails endpoint (custom fields are listed in data.inventory.customfields) or the /customfields/get endpoint.

Step 2 — Execute Search

With the ID of your custom field in hand, you can now build your query. For advanced searches, please follow the format output by the QueryBuilder library (use the queryBuilder('getRules') method) when preparing your contents parameter.

As part of a search you need to specify the ID of the inventory that should be queried. This can be retrieved from the /general/getdetails endpoint.

In the example below, we will retrieve all containers expiring within the month of April 2022 in the demo inventory. Because this is a multi-component query (we specify a start date and end date), an 'advanced' search is executed.

Please note that when handling dates for advanced searches the format should follow what is saved as a preference for the user account associated with authtoken. This could be "YYYY-MM-DD", "D MMM YYYY", etc. The applicable format can be found from /general/getdetails (data.user.dateformat). 

const axios = require('axios');

axios({
    method: "post",
    url: "https://app.cheminventory.net/api/search/execute",
    data: {
        "authtoken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "inventory": 9,                 // This is the ID of the demo inventory
        "type": "advanced",     
        "contents": {
            "condition": "AND",
            "rules": [
                {
                    "id": "cf-363",     // 363 is the ID for the Demo inventory's Expiry Date field
                    "field": "date",
                    "type": "date",
                    "input": "text",
                    "operator": "between",
                    "value": [
                        "1 Apr 2022",   // Note: the format of dates must match the date format saved for the user. This
                        "30 Apr 2022"   // can be found from /general/getdetails (data.user.dateformat)
                    ]
                }
            ]
        }
    }
})
.then(response => console.log(response))