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:

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:

{
  "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:

{
  "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:

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

Should become:

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

Base URL

The SPORIFY application programming interface is available on the production and validation environment. The Base URLs for these environments are:

• Validation: https://v.sporify.eu/api/v1/

• Production: https://sporify.eu/api/v1/

Any further explanation of SPOR related URLs in this documentation refers to the base URL and the specific endpoint. For instance, “spor/rms/lists” refers to the full qualified URL on production https://sporify.eu/api/v1/spor/rms/lists

Swagger Interface

To support developers in the process of interacting with the API, a swagger interface is available:

• Validation: https://v.sporify.eu/swagger/ui/index

• Production: https://sporify.eu/swagger/ui/index

Import Swagger API with Postman

To import the API definition of SPORIFY into Postman, use the import function of Postman and enter the URL https://www.sporify.eu/swagger/docs/v1.

After the successful import, the API definition is available in Postman under API:

Import Developer Collection with Postman

In addition to the API definition, there is a developer collection for Postman available.

To import the Developer Collection, download the collection and perform the same steps as mentioned previous section to import the API definition.

SPORIFY v1.0.postman_collection.json

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.

Note: The endpoint is not aligned under SPOR endpoint and therefore available directly at the root level of the host. For production the URL is https://sporify.eu/api/Account

Sample Request Payload

Content-type: application/json

{
  "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:

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:

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:

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:

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:

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:

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:

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:

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:

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}

SPOR Documents

Get Documents

GET spor/documents

This endpoint allows sorting on:

• sporDocumentId (default)

• name

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

Sample Request

GET spor/documents?name=quality&applicationDomain=RMS

This query fetches the first page of documents that:

• have a name containing ‘quality’, and

• belong to the Application Domain of ‘RMS’

Get Document by ID

GET spor/document/{documentId}

Get Document Download by ID

GET spor/document/{documentId}/download

Get Document Version Download by ID

GET spor/document/{documentId}/versions/{versionId}/download

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:

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:

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:

Create Referential Source List

POST source/referentials/lists

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

Sample Request Payload

Content-type: application/json

{
    "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:

Sample Request Payload

Content-type: application/json

{
  "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:

Create Source Term

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

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

Sample Request Payload

Content-type: application/json

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

Get Source Term by ID

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

This endpoint accepts a single query parameter:

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:

Sample Request Payload

Content-type: application/json

{
  "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:

Create Organisation Source List

POST source/organisations/lists

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

Sample Request Payload

Content-type: application/json

{
    "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:

Sample Request Payload

Content-type: application/json

{
  "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:

Create Source Organisation

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

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

Sample Request Payload

Content-type: application/json

{
  "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:

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:

Sample Request Payload

Content-type: application/json

{
  "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:

Create Substance Source List

POST source/substances/lists

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

Sample Request Payload

Content-type: application/json

{
    "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:

Sample Request Payload

Content-type: application/json

{
  "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:

Create Source Substance

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

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

Sample Request Payload

Content-type: application/json

{
  "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:

Sample Request Payload

Content-type: application/json

{
  "name": "acetylsalicylic acid"
}