User Tools

Site Tools


ultimate-api

Mcule ULTIMATE API

API base url: https://ultimateapp.mcule.com/api/v1/

Do not call this base URL directly, it will result in a 404 Not Found response for now. You can find in the examples below the full URLs you have to use.

Examples are demonstrated with HTTPie.

Only the most important request/response headers are shown in the examples below.

Response status codes

  • 200 OK - Success response
  • 400 Bad Request - A validation error typically
  • 401 Unauthorized
  • 403 Forbidden - Permission denied
  • 404 Not Found
  • 429 Too Many Requests - Request was throttled
  • 500 Internal Server Error - Something went wrong

Rate limits

For anonymous (not authenticated) users:

  • 10 searches / minute
  • 100 searches / day

For authenticated users (access token required, see below):

  • 100 searches / minute
  • 1000 searches / day

Authentication

Authentication is currently a token based authentication. If you would like to get an access token, please drop us an email at support@mcule.com including a brief summary on why and how you would like to use the API. We'll review your request, and if accepted, we'll provide you with an access token which you can use to call the API as an authenticated user and enjoy the less strict limits.

Once you have a valid token you have to send it in the Authorization header:

Authorization: Token <your_token>

Example:

Authorization: Token 905050288b9e786a4d60gc2fe2e5007000b7f17c

Search API

Query types

The supported query types are currently: SMILES, InChIKey, Molfile or SDF string (V2000), IUPAC name, CAS number, Std InChI, ZINC ID, CHEMBL ID.

We recommend to send your queries in SMILES format. Example SMILES query:

C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1

InChIKey support is limited to the case where the query compound is part of the Ultimate database. Example InChIKey query:

IHHITLNORGKBTP-UHFFFAOYSA-N

Example Molfile string query:

\n  -INDIGO-04112011472D\n\n 30 33  0  0  0  0  0  0  0  0999 V2000\n  -11.0851    4.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -11.0851    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -12.4708    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -12.4708    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -11.0851    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -9.6995    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -9.6995    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -8.3138    3.2000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -6.9282    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -6.9282    0.8000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0\n   -5.5426    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -4.1569    2.4000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -4.1569    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.7713    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856    0.8000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.7713    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    2.7713    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    4.1569    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    4.1569    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    2.7713    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000   -1.6000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856   -2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856   -4.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000   -4.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856   -4.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856   -2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  1  2  1  0  0  0  0\n  2  3  1  0  0  0  0\n  3  4  2  0  0  0  0\n  4  5  1  0  0  0  0\n  5  6  2  0  0  0  0\n  6  7  1  0  0  0  0\n  7  2  2  0  0  0  0\n  7  8  1  0  0  0  0\n  8  9  1  0  0  0  0\n  9 10  2  0  0  0  0\n  9 11  1  0  0  0  0\n 11 12  1  0  0  0  0\n 12 13  1  0  0  0  0\n 13 14  1  0  0  0  0\n 14 15  1  0  0  0  0\n 15 16  1  0  0  0  0\n 16 17  1  0  0  0  0\n 17 12  1  0  0  0  0\n 15 18  1  0  0  0  0\n 18 19  1  0  0  0  0\n 19 20  1  0  0  0  0\n 20 21  2  0  0  0  0\n 21 22  1  0  0  0  0\n 22 23  2  0  0  0  0\n 23 24  1  0  0  0  0\n 24 19  2  0  0  0  0\n 18 25  1  0  0  0  0\n 25 26  1  0  0  0  0\n 26 27  2  0  0  0  0\n 27 28  1  0  0  0  0\n 28 29  2  0  0  0  0\n 29 30  1  0  0  0  0\n 30 25  2  0  0  0  0\nM  END\n

IUPAC name resolution don't always work. Example IUPAC name query:

1-(2-aminoethyl)-N-(2-methoxyethyl)-6-(methylsulfanyl)-1H-pyrazolo[3,4-d]pyrimidin-4-amine

Resolving CAS numbers happens via an external service and don't always work or might be unstable. Example CAS number query:

64-17-5

Example Std InChI query:

InChI=1S/C24H32N4O5/c1-18(15-26-11-13-32-14-12-26)22(29)28-21(17-25(2)24(28)31)23(30)33-20-9-6-10-27(16-20)19-7-4-3-5-8-19/h3-5,7-8,20-21H,1,6,9-17H2,2H3

Resolving ZINC IDs happens via http://zinc.docking.org and might be unstable. Example ZINC ID query:

ZINC3589203

Resolving CHEMBL IDs happens via https://www.ebi.ac.uk/chembl/ and might be unstable. Example CHEMBL ID query:

CHEMBL2165209

Exact searches allow you to specify multiple queries. Check the supported query types.

The maximum number of allowed queries is 10000 in a single API call. If you have more queries you have to slice them into multiple chunks and send them as separate API calls. Be aware of the rate limits in this case.

Example API request:
echo '{"query": {"type": "exact", "queries": ["C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1", "O(C1=CN(N=C1)C)CC1C=CC2C=CC=CC=2C=1", "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C1CC2=CC=CC(OC)=C2SC1"]}}' | http https://ultimateapp.mcule.com/api/v1/searches/ --print HBhb

You have to use the value exact in the type parameter.

Request:
POST /api/v1/searches/ HTTP/1.1
Content-Type: application/json

{
    "query": {
        "type": "exact",
        "queries": [
            "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1",
            "O(C1=CN(N=C1)C)CC1C=CC2C=CC=CC=2C=1",
            "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C1CC2=CC=CC(OC)=C2SC1"
        ]
    }
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1",
                "inchi_key": "IHHITLNORGKBTP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "query": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1",
            "idx": 1
        },
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C1CC2=CC=CC(OC)=C2SC1",
                "inchi_key": "CTQJGCXDDNMNMJ-UHFFFAOYSA-N",
                "archived_at": null
            },
            "query": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C1CC2=CC=CC(OC)=C2SC1",
            "idx": 3
        }
    ],
    "count": 2
}

The idx value in the response corresponds to the index of the query in the queries list. As you can see from the above response, the first and the third query resulted in a hit, while the second query did not give any hits.

Similarity and substructure searches allow you to specify only one query at a time for now. Check the supported query types.

If you have more queries you have to send them separately. Be aware of the rate limits in this case. Also note that similarity and substructure searches can take more time and the response time can depend on many things.

Example API request:
echo '{"query": {"type": "sim", "query": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1", "limit": 5}}' | http https://ultimateapp.mcule.com/api/v1/searches/ --print HBhb

You have to use the value sim in the type parameter.

You can limit the number of hits with the limit parameter. In this example we fetched the 5 most similar hits. The maximum allowed number of limit is 1000.

Request:
POST /api/v1/searches/ HTTP/1.1
Content-Type: application/json

{
    "query": {
        "type": "sim",
        "query": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1",
        "limit": 5
    }
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(=C)CN1CCOCC1",
                "inchi_key": "IHHITLNORGKBTP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "tan": 1.0
        },
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)CCN1CCOCC1",
                "inchi_key": "HADABMIDSQYLHL-UHFFFAOYSA-N",
                "archived_at": null
            },
            "tan": 0.9384858044164038
        },
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)CCN1CCN(C)CC1",
                "inchi_key": "SLXHLSHIUZZOAD-UHFFFAOYSA-N",
                "archived_at": null
            },
            "tan": 0.9024767801857585
        },
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(C)=CC",
                "inchi_key": "CLFNXMQIKUMINQ-UHFFFAOYSA-N",
                "archived_at": null
            },
            "tan": 0.8996913580246914
        },
        {
            "compound": {
                "smiles": "C(N1C(C(OC2CCCN(C3=CC=CC=C3)C2)=O)CN(C)C1=O)(=O)C(C)CN1CCOCC1",
                "inchi_key": "YQTFCLLDUKSEQA-UHFFFAOYSA-N",
                "archived_at": null
            },
            "tan": 0.8974358974358975
        }
    ],
    "count": 5
}

In case of similarity searches the tan value contains the similarity value.

Similarity and substructure searches allow you to specify only one query at a time for now. Check the supported query types.

If you have more queries you have to send them separately. Be aware of the rate limits in this case. Also note that similarity and substructure searches can take more time and the response time can depend on many things.

Example API request:
echo '{"query": {"type": "sss", "query": "C1=CC2=C(C=C1)C=NC=C2", "limit": 5}}' | http https://ultimateapp.mcule.com/api/v1/searches/ --print HBhb

You have to use the value sss in the type parameter.

You can limit the number of hits with the limit parameter. In this example we fetched maximum 5 hits. The maximum allowed number of limit is 1000.

Request:
POST /api/v1/searches/ HTTP/1.1
Content-Type: application/json

{
    "query": {
        "type": "sss",
        "query": "C1=CC2=C(C=C1)C=NC=C2",
        "limit": 5
    }
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 756

{
    "results": [
        {
            "compound": {
                "smiles": "N1(CC2C3=C(C=CC=C3)C3C(=CC=CC=3)N=2)CCCN(C(=O)C2=CC=CC(F)=C2)CC1",
                "inchi_key": "YTIUNGFRKPDPPS-UHFFFAOYSA-N",
                "archived_at": null
            }
        },
        {
            "compound": {
                "smiles": "N1(CC2C3=C(C=CC=C3)C3C(=CC=CC=3)N=2)C(C)C2=C(C=CC=C2)OCC1",
                "inchi_key": "SSEIGWFVYLDHEH-UHFFFAOYSA-N",
                "archived_at": null
            }
        },
        {
            "compound": {
                "smiles": "C(N1CCN(C2=C(C)C=CC(Cl)=C2)CC1)(=O)C1C2C(=CC=CC=2)C=CN=1",
                "inchi_key": "BFPRURCGOWXZHV-UHFFFAOYSA-N",
                "archived_at": null
            }
        },
        {
            "compound": {
                "smiles": "N1(CC2C3=C(C=CC=C3)C3C(=CC=CC=3)N=2)CCN(CC2=CC=C3C(OCO3)=C2)CC1",
                "inchi_key": "IBHAWHNMRZUDAW-UHFFFAOYSA-N",
                "archived_at": null
            }
        },
        {
            "compound": {
                "smiles": "C1(C2N=C(C3C4C(=CC=CC=4)C=CN=3)ON=2)C=C(OC)C=C(OC)C=1",
                "inchi_key": "ZMXORVYVGMNALO-UHFFFAOYSA-N",
                "archived_at": null
            }
        }
    ],
    "count": 5
}

Pricing API

You can use the following fields in the API call:

  • compounds: you can specify this field in multiple ways:
    • list of InChIKeys (which you get from search results for example). For example:
      {"compounds": ["VKCCTPSYCYARFI-UHFFFAOYSA-N", "DVPXLZBGJCHMEO-UHFFFAOYSA-N"]}
    • list of InChIKey, amount pairs. This is useful if you want to get pricing data for different amounts. For example:
      {"compounds": [{"inchi_key": "VKCCTPSYCYARFI-UHFFFAOYSA-N", "amount": 1}, {"inchi_key": "DVPXLZBGJCHMEO-UHFFFAOYSA-N", "amount": 5}]}
  • amount: the amount value in mg. Default: 1, Min: 1, Max: 100. The amount can be specified for some, or all items in the compounds list. If the amount is not specified for an item in the compounds list, the “global” amount value is used for that item.
  • currency: Valid values are “USD”, “EUR”, “GBP”. The default is “USD”.
  • individual: If true you will get individual prices for the compounds. If false you will get “collective” prices for the compounds which means you will get prices in the context when you intend to “order” the compounds together. These “collective” prices take into account possible price jumps or other factors that might result in lower prices. The default value is false.
Example API request:
echo '{"compounds": ["VKCCTPSYCYARFI-UHFFFAOYSA-N", "DVPXLZBGJCHMEO-UHFFFAOYSA-N", "XKJIOIJSLLCDOZ-UHFFFAOYSA-N", "XVWBPPRZAKJXSY-UHFFFAOYSA-N", "ZNOWNQHKOHUYLP-UHFFFAOYSA-N", "IEJBADVRNXRNLB-UHFFFAOYSA-N", "LZRUMHHZJMDZLR-UHFFFAOYSA-N", "PTKVKZOBUQFOJX-UHFFFAOYSA-N", "LFHNTOJEMXUDKP-UHFFFAOYSA-N", "SICGQCSMIMRHLF-UHFFFAOYSA-N", "YGLRUSPDEQEHKM-UHFFFAOYSA-N"], "amount": 1, "currency":"USD", individual": true}' | http https://ultimateapp.mcule.com/api/v1/pricing/ --print HBhb
Request:
POST /api/v1/pricing/ HTTP/1.1
Content-Type: application/json

{
    "compounds": [
        "VKCCTPSYCYARFI-UHFFFAOYSA-N",
        "DVPXLZBGJCHMEO-UHFFFAOYSA-N",
        "XKJIOIJSLLCDOZ-UHFFFAOYSA-N",
        "XVWBPPRZAKJXSY-UHFFFAOYSA-N",
        "ZNOWNQHKOHUYLP-UHFFFAOYSA-N",
        "IEJBADVRNXRNLB-UHFFFAOYSA-N",
        "LZRUMHHZJMDZLR-UHFFFAOYSA-N",
        "PTKVKZOBUQFOJX-UHFFFAOYSA-N",
        "LFHNTOJEMXUDKP-UHFFFAOYSA-N",
        "SICGQCSMIMRHLF-UHFFFAOYSA-N",
        "YGLRUSPDEQEHKM-UHFFFAOYSA-N"
    ],
    "amount": 1,
    "currency": "USD",
    "individual": true
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "compound": {
                "smiles": "O(C(=O)CCCC1C(C)=NN(C)C=1C)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "VKCCTPSYCYARFI-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1C=CC=C(C#N)C=1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "DVPXLZBGJCHMEO-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)COC1=CC=C(OC)C=C1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "XKJIOIJSLLCDOZ-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1C(C2=CC=CC=C2)=NN2C=CN(CC(NC3C=C(OC)C(OC)=C(OC)C=3)=O)C(=O)C=12",
                "inchi_key": "XVWBPPRZAKJXSY-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1N=NN(CC2=CC=C(OC)C=C2)C=1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "ZNOWNQHKOHUYLP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1C(C2=CC=CC=C2)=NN2C=CN(CC(NC3C=C(C)C=CC=3OC)=O)C(=O)C=12",
                "inchi_key": "IEJBADVRNXRNLB-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)CCN1CCN(C)CC1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "LZRUMHHZJMDZLR-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1=C2N(C=CN(C2=O)CC(NC2=CC=C3C(OCCO3)=C2)=O)N=C1C1=CC=CC=C1",
                "inchi_key": "PTKVKZOBUQFOJX-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)CN1C(=O)CCC1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "LFHNTOJEMXUDKP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=CC=C(C)C=C1C)CC(OC)C1=C(I)C=CC=C1",
                "inchi_key": "SICGQCSMIMRHLF-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=CN(C2=NC=CC=C2)N=C1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "YGLRUSPDEQEHKM-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 176.63972004034355,
            "currency": "USD",
            "amount": 1
        }
    ]
}

Let's see the above example request with

"indvididual": false
Example API request:
echo '{"compounds": ["VKCCTPSYCYARFI-UHFFFAOYSA-N", "DVPXLZBGJCHMEO-UHFFFAOYSA-N", "XKJIOIJSLLCDOZ-UHFFFAOYSA-N", "XVWBPPRZAKJXSY-UHFFFAOYSA-N", "ZNOWNQHKOHUYLP-UHFFFAOYSA-N", "IEJBADVRNXRNLB-UHFFFAOYSA-N", "LZRUMHHZJMDZLR-UHFFFAOYSA-N", "PTKVKZOBUQFOJX-UHFFFAOYSA-N", "LFHNTOJEMXUDKP-UHFFFAOYSA-N", "SICGQCSMIMRHLF-UHFFFAOYSA-N", "YGLRUSPDEQEHKM-UHFFFAOYSA-N"], "amount":1, "individual": false}' | http https://ultimateapp.mcule.com/api/v1/pricing/ --print HBhb
Request:
POST /api/v1/pricing/ HTTP/1.1
Content-Type: application/json

{
    "compounds": [
        "VKCCTPSYCYARFI-UHFFFAOYSA-N",
        "DVPXLZBGJCHMEO-UHFFFAOYSA-N",
        "XKJIOIJSLLCDOZ-UHFFFAOYSA-N",
        "XVWBPPRZAKJXSY-UHFFFAOYSA-N",
        "ZNOWNQHKOHUYLP-UHFFFAOYSA-N",
        "IEJBADVRNXRNLB-UHFFFAOYSA-N",
        "LZRUMHHZJMDZLR-UHFFFAOYSA-N",
        "PTKVKZOBUQFOJX-UHFFFAOYSA-N",
        "LFHNTOJEMXUDKP-UHFFFAOYSA-N",
        "SICGQCSMIMRHLF-UHFFFAOYSA-N",
        "YGLRUSPDEQEHKM-UHFFFAOYSA-N"
    ],
    "amount": 1,
    "currency": "USD",
    "individual": false
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "compound": {
                "smiles": "O(C(=O)CCCC1C(C)=NN(C)C=1C)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "VKCCTPSYCYARFI-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1C=CC=C(C#N)C=1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "DVPXLZBGJCHMEO-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)COC1=CC=C(OC)C=C1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "XKJIOIJSLLCDOZ-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1C(C2=CC=CC=C2)=NN2C=CN(CC(NC3C=C(OC)C(OC)=C(OC)C=3)=O)C(=O)C=12",
                "inchi_key": "XVWBPPRZAKJXSY-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1N=NN(CC2=CC=C(OC)C=C2)C=1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "ZNOWNQHKOHUYLP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1C(C2=CC=CC=C2)=NN2C=CN(CC(NC3C=C(C)C=CC=3OC)=O)C(=O)C=12",
                "inchi_key": "IEJBADVRNXRNLB-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)CCN1CCN(C)CC1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "LZRUMHHZJMDZLR-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=C(NS(C2=CC=C(OC)C=C2)(=O)=O)C=CS1)CC1=C2N(C=CN(C2=O)CC(NC2=CC=C3C(OCCO3)=C2)=O)N=C1C1=CC=CC=C1",
                "inchi_key": "PTKVKZOBUQFOJX-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)CN1C(=O)CCC1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "LFHNTOJEMXUDKP-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=CC=C(C)C=C1C)CC(OC)C1=C(I)C=CC=C1",
                "inchi_key": "SICGQCSMIMRHLF-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        },
        {
            "compound": {
                "smiles": "O(C(=O)C1=CN(C2=NC=CC=C2)N=C1)C(CN1N=NC(C(OCC)=O)=C1)C1=CC=CC(Cl)=C1",
                "inchi_key": "YGLRUSPDEQEHKM-UHFFFAOYSA-N",
                "archived_at": null
            },
            "price": 145.55112931324305,
            "currency": "USD",
            "amount": 1
        }
    ]
}

You can notice that you get lower prices but those prices are only valid in the context where you order the compounds together.

Quote Request API

Endpoint:
/iquote-queries/
Example API request:
echo '{"compounds": ["RAQLVHPPDXCQDS-UHFFFAOYSA-N", "QWPFQODIGUYSLE-UHFFFAOYSA-N"], "amount": 1, "customer_name": "John Doe", "delivery_country": "US"}' | http https://ultimateapp.mcule.com/api/v1/iquote-queries/ "Authorization: Token <your_token>" --print HBhb

Mandatory fields:

  • compounds: you can specify this field in multiple ways:
    • list of InChIKeys (which you get from search results for example). For example:
      {"compounds": ["VKCCTPSYCYARFI-UHFFFAOYSA-N", "DVPXLZBGJCHMEO-UHFFFAOYSA-N"]}
    • list of InChIKey, amount pairs. This is useful if you want to request quote for different amounts. For example:
      {"compounds": [{"inchi_key": "VKCCTPSYCYARFI-UHFFFAOYSA-N", "amount": 1}, {"inchi_key": "DVPXLZBGJCHMEO-UHFFFAOYSA-N", "amount": 5}]}
  • customer_name: The customer's full name. It is optional if the name of the user who is making the API request (defined by the token) is specified.
  • delivery_country: ISO 3166-1 alpha-2 code of the delivery country.

Optional fields:

  • customer_email: The customer's email address. By default it will be filled with the email address associated with the user making the API request (defined by the token).
  • currency: Valid values are “USD”, “EUR”, “GBP”. The default is “USD”.
  • scheme: If you have access to predefined quote request schemes, you can specify here which one you want to use. A quote query scheme is essentially a template that contains predefined quote query parameters, or even include private parameters that affect quote generation in various ways (e.g.: discounts, predefined custom prices). These parameters can be customized for your use case. The scheme might already contain mandatory fields like delivery_country. In this case you don't have to specify them again, they will be applied from the scheme. Any explicitly specified public parameter during the request will override the one that comes from the specified scheme.
Example request:
POST /api/v1/iquote-queries/ HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Content-Type: application/json

{
    "amount": 1, 
    "customer_name": "John Doe", 
    "delivery_country": "US", 
    "compounds": [
        "RAQLVHPPDXCQDS-UHFFFAOYSA-N",
        "QWPFQODIGUYSLE-UHFFFAOYSA-N"
    ]
}
Example response:
HTTP/1.1 201 CREATED
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "amount": 1,
    "api_url": "https://ultimateapp.mcule.com/api/v1/iquote-queries/9/",
    "created_at": "2020-07-20T14:01:30.412763Z",
    "currency": "USD",
    "customer_email": "foo@bar.com",
    "customer_name": "John Doe",
    "delivery_country": {
        "code": "US",
        "name": "United States of America"
    },
    "delivery_format": 0,
    "delivery_format_display": "Dry powder/film in supplier vial",
    "ended_at": null,
    "extra_amount": null,
    "id": 9,
    "notes": "",
    "purity": null,
    "scheme": 1,
    "started_at": null,
    "state": 10,
    "state_display": "Pending",
    "target_cc": null,
    "target_volume": null,
    "user": 2
}

Quote Request Status API

Since processing a quote request and generating suitable quotes can take some time it is an asynchronous process. You can query the status of a quote request by calling the detail API endpoint of the quote request. It is returned in the api_url field when you create the quote request. You can also use the id field to construct the url of the API call. You can check the state field of the response whether the async quote request processing is finished.

States:

  • 10 / Pending: The quote query is queued but the processing has not started yet.
  • 20 / Running: The processing of the quote query is in progress.
  • 30 / Done: The processing of the quote query is finished. For one quote request query we might generate multiple quotes or it is also possible that we could not generate any quotes for a particular quote request. If there are quotes they will appear in the quotes field that contains a list of the generated quotes and some basic info about them. You can get detailed data of a particular quote by calling the endpoint specified in the api_url field.
  • 40 / Error: An error happened during the processing of the quote query.

Following the above example where the ID of the quote request is 9 we query the status of the quote request:

http https://ultimateapp.mcule.com/api/v1/iquote-queries/9/ "Authorization: Token <your_token>" --print HBhb
Example request:
GET /api/v1/iquote-queries/9/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Example response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json

{
    "amount": 1,
    "api_url": "https://ultimateapp.mcule.com/api/v1/iquote-queries/9/",
    "created_at": "2020-07-20T14:01:30.412763Z",
    "currency": "USD",
    "customer_email": "foo@bar.com",
    "customer_name": "John Doe",
    "delivery_country": {
        "code": "US",
        "name": "United States of America"
    },
    "delivery_format": 0,
    "delivery_format_display": "Dry powder/film in supplier vial",
    "ended_at": "2020-07-20T14:01:30.514096Z",
    "extra_amount": null,
    "id": 9,
    "notes": "",
    "purity": null,
    "quotes": [
        {
            "additional_document_notes": "",
            "api_url": "https://ultimateapp.mcule.com/api/v1/iquotes/9/",
            "avg_product_price": "667.74",
            "avg_product_price_currency": "USD",
            "coverage_percent": 100,
            "created_at": "2020-07-20T14:01:30.506962Z",
            "id": 9,
            "modified_at": "2020-07-20T14:01:30.506997Z",
            "product_discount_price": null,
            "product_discount_price_currency": "USD",
            "products_price": 1335.48,
            "products_price_currency": "USD",
            "query": 9,
            "reference_id_full": "UI-9",
            "reformatting_price": null,
            "reformatting_price_currency": "USD",
            "selection_criteria": 10,
            "selection_criteria_display": "Best price",
            "shipping_price": 51.09,
            "shipping_price_currency": "USD",
            "state": 10,
            "state_display": "Displayed",
            "total_discount_price": null,
            "total_discount_price_currency": "USD",
            "total_price": 1386.57,
            "total_price_currency": "USD",
            "valid_until": "2020-08-19T14:01:30.506962Z"
        }
    ],
    "scheme": 1,
    "started_at": "2020-07-20T14:01:30.464496Z",
    "state": 30,
    "state_display": "Done",
    "target_cc": null,
    "target_volume": null,
    "user": 2
}

Check for the quotes field. If it is there and contains some items in the list, we could generate some quotes for your quote query. As you can see from the above result, we could generate 1 quote for the quote query. A “Best price” quote.

Quote API

In order to get the detailed data of an individual quote, you can call the detail API endpoint of a quote, for example for the quote with ID 9:

http https://ultimateapp.mcule.com/api/v1/iquotes/9/ "Authorization: Token <your_token>" --print HBhb
Example request:
GET /api/v1/iquotes/9/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Example response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "additional_document_notes": "",
    "api_url": "https://ultimateapp.mcule.com/api/v1/iquotes/9/",
    "avg_product_price": "667.74",
    "avg_product_price_currency": "USD",
    "coverage_percent": 100,
    "created_at": "2020-07-20T14:01:30.506962Z",
    "id": 9,
    "items": [
        {
            "amount": 1,
            "compound": {
                "archived_at": null,
                "inchi_key": "RAQLVHPPDXCQDS-UHFFFAOYSA-N",
                "smiles": "C(NC1=C(C#N)C=C(C#N)C=N1)(=O)C1N=C(N2CCN(C3=CC=CC=C3)CC2)SC=1"
            },
            "product_price": 637.27,
            "product_price_currency": "USD",
            "purity_percent": 90
        },
        {
            "amount": 1,
            "compound": {
                "archived_at": null,
                "inchi_key": "QWPFQODIGUYSLE-UHFFFAOYSA-N",
                "smiles": "C(N(C(CSCC1OC=CC=1)=O)C1=C(C(F)(F)F)C=CC=C1)(=O)CCC1=NOC=C1"
            },
            "product_price": 698.21,
            "product_price_currency": "USD",
            "purity_percent": 90
        }
    ],
    "payment_due_days": 30,
    "price_items": [
        {
            "attr": "products_price",
            "name": "Products price",
            "price": 1335.48,
            "price_currency": "USD"
        },
        {
            "attr": "product_discount",
            "name": "Product discount (0%)",
            "price": 0.0,
            "price_currency": "USD"
        },
        {
            "attr": "shipping_price",
            "name": "Shipping & package consolidation",
            "price": 51.09,
            "price_currency": "USD"
        },
        {
            "attr": "reformatting_price",
            "name": "Reformatting",
            "price": 0.0,
            "price_currency": "USD"
        },
        {
            "attr": "total_discount_price",
            "name": "Total discount (0%)",
            "price": 0.0,
            "price_currency": "USD"
        }
    ],
    "product_discount_price": null,
    "product_discount_price_currency": "USD",
    "products_price": 1335.48,
    "products_price_currency": "USD",
    "query": {
        "amount": 1,
        "api_url": "https://ultimateapp.mcule.com/api/v1/iquote-queries/9/",
        "created_at": "2020-07-20T14:01:30.412763Z",
        "currency": "USD",
        "customer_email": "foo@bar.com",
        "customer_name": "John Doe",
        "delivery_country": {
            "code": "US",
            "name": "United States of America"
        },
        "delivery_format": 0,
        "delivery_format_display": "Dry powder/film in supplier vial",
        "ended_at": "2020-07-20T14:01:30.514096Z",
        "extra_amount": null,
        "id": 9,
        "notes": "",
        "purity": null,
        "scheme": 1,
        "started_at": "2020-07-20T14:01:30.464496Z",
        "state": 30,
        "state_display": "Done",
        "target_cc": null,
        "target_volume": null,
        "user": 2
    },
    "reference_id_full": "UI-9",
    "reformatting_price": null,
    "reformatting_price_currency": "USD",
    "selection_criteria": 10,
    "selection_criteria_display": "Best price",
    "shipping_price": 51.09,
    "shipping_price_currency": "USD",
    "state": 10,
    "state_display": "Displayed",
    "total_discount_price": null,
    "total_discount_price_currency": "USD",
    "total_price": 1386.57,
    "total_price_currency": "USD",
    "valid_until": "2020-08-19T14:01:30.506962Z"
}
Fields:
  • additional_document_notes: Additional document notes
  • avg_product_price: Average product price
  • avg_product_price_currency: Currency of average product price
  • coverage_percent: How many of the query molecules appear in the quote. E.g. if your query contains 10 molecules and you get a quote for 9, it is 90%.
  • created_at: The creation datetime of the quote.
  • id: The ID of the Instant Quote.
  • items: list of product level data
    • amount: Quoted amount (mg)
    • compound: the quoted compound
    • product_price: product price
    • product_price_currency: currency of product price
    • purity_percent: Guaranteed purity (%)
  • payment_due_days: Payment terms. Number of days net or prepayment by credit card
  • price_items: The list of price items. They are only used for display purposes basically.
  • product_discount_price: Discount of products price
  • product_discount_price_currency: Currency of discount of products price
  • products_price: Price of products
  • products_price_currency: Currency of price of products
  • query: The quote query fields
  • reference_id_full: The full reference ID of the instant quote.
  • reformatting_price: Reformatting price (USD)
  • reformatting_price_currency: Currency of reformatting price
  • selection_criteria: Selection criteria code of the quote.
  • selection_criteria_display: Human readable selection criteria of the quote.
  • shipping_price: Shipping & handling cost
  • shipping_price_currency: Currency of Shipping & handling cost
  • state: State code of the quote.
  • state_display: Human readable state of the quote.
  • total_discount_price: Total discount price
  • total_discount_price_currency: Currency of total discount price
  • total_price: Total price of quote
  • total_price_currency: Currency of the total price
  • valid_until: The datetime until the quote is valid.

Download quote as PDF

You can download a quote as a PDF file. Please note that the PDF file generation can take some time, the more item it contains the more time it will take to generate the file.

The HTTP response contains a Content-Disposition attachment; filename=“<filename>” header indicating that it should be downloaded.

http https://ultimateapp.mcule.com/api/v1/iquotes/9/download-pdf/ "Authorization: Token <your_token>" --download

Download quote as Excel (.xlsx) file

You can download a quote as an Excel file. Please note that the file generation can take some time, the more item it contains the more time it will take to generate the file.

The HTTP response contains a Content-Disposition attachment; filename=“<filename>” header indicating that it should be downloaded.

http https://ultimateapp.mcule.com/api/v1/iquotes/9/download-excel/ "Authorization: Token <your_token>" --download
ultimate-api.txt · Last modified: 2020/07/21 12:26 by flack