Skip to main content
Skip table of contents

API Guide

Introduction

Common Behaviour and Types

  • Anywhere string values are accepted by API endpoints, their comparison is case insensitive.

  • Datetime values, where accepted, should be provided in ISO 8601 format.

Resource Query Parameters

All resource endpoints, spor/rms/lists, spor/oms/locations etc. are paged and accept the following query parameters:

Name

Description

Default

page

The page to return.

1

pageSize

The number of items to include in the paged result. Must be between 1 and 100

20

sortBy

The field by which the resource is sorted. Default sortBys are resource specific.

sortOrder

Used with sortBy to apply sorting. Must be one of: “asc”, “desc”.

“asc”

Normalise Query Parameter

All endpoints that return EMA SPOR data take an optional query parameter, normalise, that defaults to false. When it is set to true, Sporify will perform a series of operations to fix some of the known issues with the EMA SPOR JSON data. Currently, those operations are:

Force an array wherever there should be a collection.

EMA SPOR’s API appears to serialize collections containing one element as objects and collections containing more than one element as arrays. Consider the following examples of simplified EMA SPOR JSON where a term has either one or two names:

CODE
{
  "term-names": {
    "term-name": {
      "text": "Name 1"
    }
  }
}

{
  "term-names": {
    "term-name": [
      {
        "text": "Name 1"
      },
      {
        "text": "Name 2"
      }
    ]
  }
}

Sporify fixes this problem by wrapping single elements in an array:

CODE
{
  "term-names": {
    "term-name": [
      {
        "text": "Name 1"
      }
    ]
  }
}

Convert all datetimes to UTC

Datetimes from the EMA SPOR API can appear in a variety of timezones, these are converted to UTC.

Convert alternative name strings to objects

An organisation’s alternative names can sometimes appear as strings rather than objects, particularly in older versions of an organsation, therefore we convert the string to the expected object type. This change occurs at JSON Paths organisation.alternative-names.alternative-name and organisation.versions.organisation-version[*].alternative-names.alternative-name. For example:

CODE
{ 
  "alternative-names": {
    "alternative-name": [
      "Name 1"      
    ]
}

Should become:

CODE
{ 
  "alternative-names": {
    "alternative-name": [
      {
        "text": "Name 1"
      }
    ]
}

Authentication

POST api/Account

Sporify uses a username and password to generate Bearer tokens. A successful authentication request will receive a Bearer token that should be included as an Authorization header in subsequent requests. Note that the string “Bearer” should prefix the received token value in the Authorization header, e.g. “Bearer LtE0tDSbUNkmAdQ…”. Issued tokens will be valid for 24 hours after which time the authentication process should be repeated.

Name

Description

Required

tenancyName

Sporify is a multi-tenant system.

true

usernameOrEmailAddress

Username or email address can be used.

true

password

Insert appropriate password.

true

Sample Request Payload

Content-type: application/json

CODE
{
  "tenancyName": "CorrIT",
  "usernameOrEmailAddress": "admin",
  "password": "password"
}

SPOR RMS

Get RMS Lists

GET spor/rms/lists

This endpoint allows sorting on:

  • listId (default)

  • name

  • shortName

  • status

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

modifiedAfter

List has changed since this date.

name

List’s name or short name contains this value.

tags

List has been tagged with any of these values.

favouritesOnly

Restrict Lists to those that have been favourited.

false

Sample Request

GET spor/rms/lists?tags=approved&tags=complete&sortBy=modifiedOn&sortOrder=desc&modifiedAfter=2017-01-01&name=med

This query fetches the first page of RMS Lists, with the most recently modified lists first, that:

  • have been tagged with either ‘approved’ or ‘complete’, and

  • have been modified since 01/01/2017, and

  • have a name or short name containing ‘med’

Get RMS List by RMS List ID

GET spor/rms/lists/{listID}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

Get Terms by RMS List ID

GET spor/rms/lists/{listId}/terms

This endpoint allows sorting on:

  • termId (default)

  • createdOn

  • modifiedOn

  • status

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

domain

Term’s domain is in this comma-separated list of domains. Domains can be specified by Term ID or short name.

‘h,v,hv’

modifiedAfter

Term has changed since this date.

name

Term’s name or short name contains this value.

status

Term has any of these status. Allowed values: Current, Non_Current, Provisional, Nullified.

tags

Term has been tagged with any of these values.

dataGovernanceStage

Term must be in this data governance stage (1, 2 or 3)

dataGovernanceStatus

Term must have a data governance status with this name

Sample Request

GET spor/rms/lists/100000000006/terms?page=2&domain=100000000012&modifiedAfter=2017-01-01&name=elbow&status=current

This query fetches the second page of terms from list 100000000006 (Medical Dictionary For Regulatory Activities) that:

  • are in the 100000000012 domain (Human use),

  • have been modified since 01/01/2017,

  • have a name or short name containing ‘elbow’, and

  • have a status of ‘current’

Get Term by RMS List ID and Term ID

GET spor/rms/lists/{listId}/terms/{termId}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

Get Terms

GET spor/rms/terms

This endpoint is almost identical to the spor/rms/lists/{listId}/terms endpoint. The only difference is that we don’t have to specify a listId in the path.

Get Term by Term ID

GET spor/rms/terms/{termId}

This endpoint is almost identical to spor/rms/lists/{listId}/terms/{termId} but does not need to specify the listId in the path.

Get Term Summaries by RMS List ID

GET spor/rms/lists/{listId}/term-summaries

This endpoint is similar to spor/rms/lists/{listId}/terms but returns the SPOR Term Summary type instead of the SPOR Term type.

Get Term Summary by RMS List ID and Term ID

GET spor/rms/lists/{listId}/term-summaries/{termId}

Get Term Summaries

GET spor/rms/term-summaries

This endpoint is almost identical to the spor/rms/lists/{listId}/term-summaries endpoint. The only difference is that we don’t have to specify a listId in the path.

Get Term by Term ID

GET spor/rms/term-summaries/{termId}

Almost identical to spor/rms/lists/{listId}/term-summaries/{termId} but without needing to specify the listId in the path.

SPOR OMS

Get Organisations

GET spor/oms/organisations

This endpoint allows sorting on:

  • orgId (default)

  • acronym

  • name

  • status

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

modifiedAfter

Organisation has changed since this date.

name

Organisation’s name, acronym or alternate name contains this value.

status

Organisation has this status. Must be one of: Active, Inactive, Provisional.

favouritesOnly

Restrict Organisations to those that have been favourited.

false

dataGovernanceStage

Organisation must be in this data governance stage (1, 2 or 3)

dataGovernanceStatus

Organisation must have a data governance status with this name

Sample Request

GET spor/oms/organisations?name=pharma&status=active

This query fetches the first page of organisations that:

  • have a name containing ‘pharma’, and

  • have a status of active

Get Organisation by ID

GET spor/oms/organisations/{orgId}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

Get Locations

GET spor/oms/locations

This endpoint allows sorting on:

  • locId (default)

  • country

  • status

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

address

Location’s address contains this value.

modifiedAfter

Location has changed since this date.

status

Location has this status. Must be one of: Active, Inactive, Provisional.

tags

Location has been tagged with any of these values.

Sample Request

GET spor/oms/locations?address=Dublin,Ireland&status=active

This query fetches the first page of locations that:

  • have an address containing ‘Dublin,Ireland’, and

  • have a status of active

Get Location by ID

GET spor/oms/locations/{locId}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

SPOR SMS

Get Substances

GET spor/sms/substances

This endpoint allows sorting on:

  • smsId (default)

  • name

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

modifiedAfter

Substance has changed since this date.

name

Substance’s name contains this value.

status

Substance has this status.

domain

Substance belongs to this domain. Must be one of: “Human use”, “Veterinary use”

tags

Substance has been tagged with any of these values.

dataGovernanceStage

Substance must be in this data governance stage (1, 2 or 3)

dataGovernanceStatus

Substance must have a data governance status with this name

Sample Request

GET spor/sms/substances?name=aspirin&status=Current

This query fetches the first page of substances that:

  • have a name containing ‘aspirin’, and

  • have a status of ‘Current’

Get Substance by ID

GET spor/sms/substances/{smsId}

G-SRS Substances

Get G-SRS Substances

GET gsrs/substances

This endpoint allows sorting on:

  • unii (default)

  • name

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

modifiedAfter

Substance has changed since this date.

name

Substance’s name or other name contains this value.

unii

Substance’s UNII code contains this value.

tags

Substance has been tagged with any of these values.

dataGovernanceStage

Substance must be in this data governance stage (1, 2 or 3)

dataGovernanceStatus

Substance must have a data governance status with this name

Sample Request

GET gsrs/substances?name=atorvastatin

This query fetches the first page of substances that:

  • have a name containing ‘atorvastatin’

Get G-SRS Substance by ID

GET gsrs/substances/{unii}

Get Substance by ID With Specific Version

GET gsrs/substances/{unii}/versions/{version}

EUTCT Substances

Get EUTCT Human Substances

GET eutct/substances

This endpoint allows sorting on:

  • termId (default)

  • createdOn

  • modifiedOn

  • status

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

modifiedAfter

Substance has changed since this date.

name

Substance’s name or other name contains this value.

termId

Substance’s Term Id contains this value.

status

Term has any of these statuses. Allowed values: Current, Non_Current, Provisional, Nullified.

tags

Substance has been tagged with any of these values.

dataGovernanceStage

Substance must be in this data governance stage (1, 2 or 3)

dataGovernanceStatus

Substance must have a data governance status with this name

Get EUTCT Human Substance by ID

GET eutct/substances/{termId}

Get EUTCT Human Substance by ID With Specific Version

GET eutct/substances/{termId}/versions/{version}

Get EUTCT Veterinary Substances

GET eutct/veterinary-substances

This endpoint is similar to eutct/substances but returns veterinary substances instead of human substances.

Get EUTCT Veterinary Substance by ID

GET eutct/substances/{termId}

Get EUTCT Veterinary Substance by ID With Specific Version

GET eutct/substances/{termId}/versions/{version}

Source Systems

Get Source Systems

GET source/systems

This endpoint allows sorting on:

  • name (default)

  • id

  • createdOn

  • modifiedOn

Get Source System by ID

GET source/systems/{systemId}

Resolution Status

Get Resolution Status

GET source/resolution-status

This endpoint allows sorting on:

  • name (default)

  • id

Get Resolution Status by ID

GET source/resolution-status/{statusId}

Source Referentials

Get Referential Source Lists

GET source/referentials/lists

This endpoint allows sorting on:

  • name (default)

  • id

  • systemId

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

systemId

Source List belongs to this system.

modifiedAfter

Source List has changed since this date.

name

Source List name contains this value.

Create Referential Source List

POST source/referentials/lists

To create a Source List, the following JSON keys are required:

Name

Description

Required

systemId

The ID of the system with which this list will be associated.

true

name

A name by which to identify this list.

true

rmsListId

The list ID of the target RMS List.

true

language

An ISO 639-1 two-letter code specifying the language.

true

Sample Request Payload

Content-type: application/json

CODE
{
    "systemId": "c5c5c5c7-62a9-3a0f-bb70-3e3a5346013a",
    "name": "countries",
    "rmsListId": 100000000002,
    "language": "en"
}

Get Referential Source List by ID

GET source/referentials/lists/{listId}

Delete Referential Source List

DELETE source/referentials/lists/{listId}

Warning: this operation cannot be undone and will delete the Source List and any Source Terms that it contains.

Update Referential Source List

PATCH source/referentials/lists/{listId}

To update a Source List, the following JSON keys may be provided:

Name

Description

Required

systemId

The ID of the system with which this list will be linked.

false

name

The new name of the list.

false

Sample Request Payload

Content-type: application/json

CODE
{
  "name": "european_countries"
}

Map Referential Source List

POST source/referentials/lists/{listId}/map

Trigger mapping to be performed for this source list against the RMS List specified at list creation.

Get Unmapped Terms by Source List ID

GET source/referentials/lists/{listId}/unmapped

This endpoint returns the unmapped RMS Terms from the RMS List that this Source List is targeting. This is equivalent to querying the targeted RMS List when the Source List has no Source Terms, but once an RMS Term is mapped against it, it will not be included in the result.

It accepts the same query parameters as the spor/rms/lists/{listId}/terms and spor/rms/terms endpoints.

Get Source Terms by Source List ID

GET source/referentials/lists/{listId}/elements

This endpoint allows sorting on:

  • sourceId (default)

  • id

  • name

  • createdOn

  • modifiedOn

  • rmsTermStatus

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

resolutionStatusId

Source Term has this status.

modifiedAfter

Source Term has been changed since this date.

name

Source Term’s name contains this value.

rmsTermStatus

Mapped RMS Term has any of these status. Allowed values: Current, Non_Current, Provisional, Nullified.

tags

Source Term has been tagged with any of these values.

Create Source Term

POST source/referentials/lists/{listId}/elements

To create a Source Term, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this Term in your Source System

true

name

The Term name.

true

shortName

The Term’s short name.

false

otherName

The Term’s other name.

false

description

The Term’s description.

false

comment

A comment regarding this Term

false

Sample Request Payload

Content-type: application/json

CODE
{
  "sourceId": "1890",
  "name": "France"
}

Get Source Term by ID

GET source/referentials/lists/{listId}/elements/{elementId}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

Delete Source Term

DELETE source/referentials/lists/{listId}/elements/{elementId}

Warning: this operation cannot be undone and will delete the term.

Update Source Term

PATCH source/referentials/lists/{listId}/elements/{elementId}

To update a Source Term, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this Term in your Source System.

false

name

The Term name.

false

shortName

The Term’s short name.

false

otherName

The Term’s other name.

false

description

The Term’s description.

false

comment

A comment regarding this Term

false

Sample Request Payload

Content-type: application/json

CODE
{
  "sourceId": "1891"
}

Source Organisations

Get Organisation Source Lists

GET source/organisations/lists

This endpoint allows sorting on:

  • name (default)

  • id

  • systemId

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

systemId

Source List belongs to this system.

modifiedAfter

Source List has changes since this date.

name

Source List name contains this value.

Create Organisation Source List

POST source/organisations/lists

To create a Source List, the following JSON keys are required:

Name

Description

Required

systemId

The ID of the system with which this list will be associated.

true

name

A name by which to identify this list .

true

Sample Request Payload

Content-type: application/json

CODE
{
    "systemId": "c5c5c5c7-62a9-3a0f-bb70-3e3a5346013a",
    "name": "orgs"
}

Get Organisation Source List by ID

GET source/organisations/lists/{listId}

Delete Organisation Source List

DELETE source/organisations/lists/{listId}

Warning: this operation cannot be undone and will delete the Source List and any Source Organisations that it contains.

Update Organisation Source List

PATCH source/organisations/lists/{listId}

To update a Source List, the following JSON keys may be provided:

Name

Description

Required

systemId

The ID of the system with which this list will be linked.

false

name

A name by which to identify this list.

false

Sample Request Payload

Content-type: application/json

CODE
{
  "name": "organisations"
}

Map Organisation Source List

POST source/organisations/lists/{listId}/map

Trigger mapping to be performed for this source list against OMS Organisations.

Get Source Organisations by Source List ID

GET source/organisations/lists/{listId}/elements

This endpoint allows sorting on:

  • sourceId (default)

  • id

  • name

  • address

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

resolutionStatusId

Source Org has this status.

modifiedAfter

Source Org has been changed since this date.

name

Source Org’s name or address contains this value.

tags

Source Org has been tagged by any of these values.

Create Source Organisation

POST source/organisations/lists/{listId}/elements

To create a Source Organisation, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this term in your Source System.

true

name

The organisation’s name.

true

address

The organisation’s address.

true

comment

A comment regarding this Organisation

false

Sample Request Payload

Content-type: application/json

CODE
{
  "sourceId": "1",
  "name": "CorrIT Limited",
  "address": "64 Mount Street Lower, Dublin 2, Ireland"
}

Get Source Organisation by ID

GET source/organisations/lists/{listId}/elements/{elementId}

This endpoint accepts a single query parameter:

Name

Description

Default

normalise

Fix known issues with returned EMA SPOR JSON

false

Delete Source Organisation

DELETE source/organisations/lists/{listId}/elements/{elementId}

Update Source Organisation

PATCH source/organisations/lists/{listId}/elements/{elementId}

To update a Source Organisation, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this Organisation in your Source System.

false

name

The Organisation’s name.

false

address

The Organisation’s address.

false

comment

A comment regarding this Organisation

false

Sample Request Payload

Content-type: application/json

CODE
{
  "name": "CorrIT Ltd",
}

Source Substances

Get Substance Source Lists

GET source/substances/lists

This endpoint allows sorting on:

  • name (default)

  • id

  • systemId

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

systemId

Source List belongs to this system.

modifiedAfter

Source List has changed since this date.

name

Source List name contains this value.

Create Substance Source List

POST source/substances/lists

To create a source list, the following JSON keys are required:

Name

Description

Required

systemId

The ID of the system with which this list will be associated.

true

name

A name by which to identify this list.

true

language

An ISO 639-1 two-letter code specifying the language.

true

Sample Request Payload

Content-type: application/json

CODE
{
    "systemId": "c5c5c5c7-62a9-3a0f-bb70-3e3a5346013a",
    "name": "acids",
    "language": "en"
}

Get Substance Source List by ID

GET source/substances/lists/{listId}

Delete Substance Source List

DELETE source/substances/lists/{listId}

Warning: this operation cannot be undone and will delete the Source List and any Source Substances that it contains.

Update Substance Source List

PATCH source/substances/lists/{listId}

To update a Source List, the following JSON keys may be provided:

Name

Description

Required

systemId

The ID of the system with which this list will be linked.

false

name

The new name of the list.

false

Sample Request Payload

Content-type: application/json

CODE
{
  "name": "organic acids"
}

Map Substance Source List

POST source/substances/lists/{listId}/map

Trigger mapping to be performed for this Source List against Target Substances.

Get Source Substances by Source List ID

GET source/substances/lists/{listId}/elements

This endpoint allows sorting on:

  • sourceId (default)

  • id

  • name

  • createdOn

  • modifiedOn

In addition to the common resource query parameters, this endpoint accepts:

Name

Description

resolutionStatusId

Source substance has this status.

modifiedAfter

Source substance has been changed since this date.

name

Source substance’s name contains this value.

tags

Source substance has been tagged with any of these values.

Create Source Substance

POST source/substances/lists/{listId}/elements

To create a source term, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this substance in your source system

true

name

The substance name

true

substanceId

A local substance ID

false

molecularFormula

The molecular formula of this substance

false

nameType

Classification of the substance’s name

false

substanceType

Classification of the substance

false

eutctId

An EUTCT ID linked to this substance

false

evCode

An EV Code linked to this substance

false

unii

A UNII code linked to this substance

false

casNumber

A CAS Number linked to this substance

false

inchi

An InChI Key linked to this substance

false

inn

A WHO INN ID linked to this substance

false

smiles

A SMILES string linked to this substance

false

atcCode

An ATC Code linked to this substance

false

comment

A comment regarding this substance

false

Sample Request Payload

Content-type: application/json

CODE
{
  "sourceId": "12345",
  "name": "aspirin"
}

Get Source Substance by ID

GET source/substances/lists/{listId}/elements/{elementId}

Delete Source Substance

DELETE source/substances/lists/{listId}/elements/{elementId}

Warning: this operation cannot be undone and will delete the term.

Update Source Substance

PATCH source/substances/lists/{listId}/elements/{elementId}

To update a source substance, the following JSON keys may be provided:

Name

Description

Required

sourceId

The primary key of this substance in your source system

false

name

The substance name

false

substanceId

A local substance ID

false

molecularFormula

The molecular formula of this substance

false

nameType

Classification of the substance’s name

false

substanceType

Classification of the substance

false

eutctId

An EUTCT ID linked to this substance

false

evCode

An EV Code linked to this substance

false

unii

A UNII code linked to this substance

false

casNumber

A CAS Number linked to this substance

false

inchi

An InChI Key linked to this substance

false

inn

A WHO INN ID linked to this substance

false

smiles

A SMILES string linked to this substance

false

atcCode

An ATC Code linked to this substance

false

comment

A comment regarding this substance

false

Sample Request Payload

Content-type: application/json

CODE
{
  "name": "acetylsalicylic acid"
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.