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"
}