Quickstart Guide: REST API Documentation

The Trust.med REST API allows you to gather and edit multiple different facets of data within your Trust.med account.

  • Manufacturers will be able to gather information about recalls and the notifications sent for those recalls. They will also be able to add a GTIN/NDC to the account, assign resolvers to those GTIN/NDCs and create/edit Resolver Links tied to those resolvers.
  • Distributors and Dispensers will be able to gather the notifications sent to them and acknowledge those recall notifications.
  • Third Party Logistic Providers will be able to do the above for the appropriate type of account that they are responsible for.

Last Updated: 08/22

Our API uses token based authentication. Other forms of authentication, ATP for example, may be added later and this document will be updated accordingly. This document will show all API calls with examples in both Python and CURL. The Python version is expected to use the latest version of the Python library.

Using the API

Authentication

The Trust.med API uses Token based Authentication. In order to use the API, you will need to be provided with a username and password by your Trust.med Representative.

Sandbox Testing

In order to test the Trust.med API within a Sandbox environment, there are a few extra steps:

  1. You will need to have your Trust.med representative provision a TESTING API username and password for the system. This is a different set of credentials than those mentioned in the “Before You Begin” section.
  2. You will need to provide the IP addresses for all of the test machines to your Trust.med representative.
  3. ⚠️ All endpoints in this document will need to have the “https://atp.med” replaced with “https://staging.atp.med”⚠️

Generating an Access Token

POST /token

The Trust.med API uses the Authorization token sent in the Header of a request to authenticate a user.

Accepted Method(s): POST

The header will look like the following:

"Authorization: Bearer 123abc...987zyx"

In order to generate the access token, follow these steps:

  1. Gather your username and password.
  2. Send a request to the Access Token Generation endpoint.
  3. You will send the username, password, scope, grant_type and client_id as Post Body elements.

Example Body

import requests

{
  "client_id": "dotmed",
  "grant_type": "password",
  "scope": "openid",
  "username": "your-username",
  "password": "your-password",
}

import requests

payload = { 
    'client_id': 'dotmed', 
    'grant_type': 'password', 
    'scope': 'openid', 
    'username': 'your-username', 
    'password': 'your-password', 
}

r = requests.post("https://atp.med/api/v1.0/token", data=payload)
cURL
curl --request POST \ 
--url 'http://api.med/api/v1.0/token' \ 
--header 'content-type: application/json' \ 
--data '{"client_id": "dotmed", "grant_type": "password", "scope": "openid", "username": "your-username", "password": "your-password"}'

Response Data

The Response to this endpoint will return with the following schema:

Item Format Description
access_tokenStringThe access token value
expires_inIntegerHow long the token lives, in seconds
token_typeStringBearer

Recall Enpoints

List Manufacturer Recalls

GET /recall

This endpoint provides a list of active recalls.

  • Manufacturers engaging with this endpoint will receive a list of their active recalls.
  • Dispensers and Wholesalers engaging with this endpoint will receive a list of active recalls initiated by manufacturers.

Example Requests

Python

Import Requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint
url = f'https://atp.med/api/v1.0/recall/'
headers = {'Authorization': f'Bearer {token}'}

r = requests.get(url, headers=headers)
cURL
curl --request GET \ 
--url 'http://atp.med/api/v1.0/recall/' \
--header 'Authorization: Bearer abc123...x_yz'

Response Data

This endpoint will return a list of recall objects. Each will have the following schema:

Item Format Description
idIntegerThe numerical ID for the Notification
recall_idIntegerThe numerical ID for the Recall
acknowledgeBooleanIf the notification has been acknowledged
ack_dateDateTimeWhen the notification was first acknowledged
created_atDateTimeWhen the notification was created
last_notifiedDateTimeDate Time of last notification
companyObjectThe Company info the notification was sent to
locationObjectThe location info the notification was sent to

List Recall Notifications

GET /recall/{id([0-9]+)}/notification

This endpoint uses an “id” that corresponds to the identifier for the recall that you wish to gather the notifications for.

This endpoint is used to generate a list of all of the notifications distributed for a particular recall.

When notifications are gathered via this endpoint by a third-party, the notification is auto-acknowledged for the user. The expectation is that the third-party is sending the information to the distributor or dispenser and is taking responsibility for the delivery of the notification downstream.

Examples

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint recall_id = 123 url = f'https://atp.med/api/v1.0/recall/{recall_id}/notification/' headers = {'Authorization': f'Bearer {token}'} r = requests.get(url, headers=headers)
cURL
curl --request GET \
--url 'https://atp.med/api/v1.0/recall/:recall_id/notification/' \
--header 'Authorization: Bearer abc123...x_yz'

Response Data

The response to this endpoint will return with the following schema:

Item Format Description
idIntegerThe numerical ID for the Notification
recall_idIntegerThe numerical ID for the Recall
acknowledgeBooleanIf the notification has been acknowledged
ack_dateDateTimeWhen the notification was first acknowledged
created_atDateTimeWhen the notification was created
last_notifiedDateTimeDate Time of last notification
companyObjectThe Company info the notification was sent to
locationObjectThe location info the notification was sent to

List New Recall Notifications

GET /recall-notifications

Utilize this endpoint to gather all new recall notifications tied to an account. This can be used to gather the new recall notifications in bulk without the need to gather each recall identifier and hit the recall notification endpoint multiple times.

Once a notification is returned via this endpoint, it will not be part of the data returned if the endpoint is hit a second time since it only returns “fresh” data.

Examples

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint
url = f'https://atp.med/api/v1.0/recall-notifications/'
headers = {'Authorization': f'Bearer {token}'}

r = requests.get(url, headers=headers)
cURL
curl --request GET \
--url 'https://atp.med/api/v1.0/recall-notifications/' \
--header 'Authorization: Bearer abc123...x_yz'

Response Data

The response to this endpoint will return with the following schema:

Item Format Description
idIntegerThe numerical ID for the Notification
identifierStringThe manufacturer provided name for the Recall
manufacturerStringThe Manufacturer's name
manufacturer_event_numberStringThe Manufacturer's event number
manufacturer_phoneStringThe contact number for the manufacturer
initiation_dateDateTimeThe initiation date of the Recall
root_causeStringObjectURL for Root Cause document
reasonStringThe reason for the Recall
recall_classStringThe class of the Recall
recall_levelStringThe level of the Recall
stop_immediatelyBooleanStop Immediately status
letter_wholesaleStringThe URL for the Wholesale Letter if available
letter_pharmacyStringThe URL for the Pharmacy Letter if available
letter_patientStringThe URL for the Patient Letter if available
productsArrayA list of products, NDCs, Lots included in the Recall
companyIntegerThe Company ID for the Recall
created_byIntegerThe User ID for the created Recall
creator_emailStringThe email for the Recall Initator

Resolver Endpoints

List/Create Resolver Objects

GET /company/{company_id}([0-9])/resolver
POST /company/{company_id}([0-9])/resolver

This endpoint can accept both a GET or a POST request. The GET  request will return all resolvers tied to the specified company identifier. The POST request will create a new Resolver with the provided name for the company tied to the identifier.

Example Requests

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint
url = f'https://atp.med/api/v1.0/company/1/resolver/'
headers = {'Authorization': f'Bearer {token}'}

# Example GET
r = requests.get(url, headers=headers)

# Example POST
r2 = requests.post(url, headers+headers, data=payload)
cURL
curl --request GET \
--url 'https://atp.med/api/v1.0/company/1/resolver/' \
--header 'Authorization: Bearer abc123...x_yz'

curl --request POST \
--url 'https://atp.med/api/v1.0/company/1/resolver/' \
--header 'Authorization: Bearer abc123...x_yz'
--data '{"name": "My New Resolver"}'

Response Data

The response to this endpoint will return either a list of resolvers or a single resolver with the following schema:

Item Format Description
id([a-zA-Z0-9-)+The UUID4 id for the Resolver
nameStringThe name of the Resolver
company_idIntegerThe Identifier for the Company
created_atDateTimeWhen the Resolver was created
resolver_linksList: Resolver LinkList of the Resolver Link objects tied to this Resolver

List/Create Resolver Links

GET /company/{company_id}([0-9])/resolver/{resolver_id}([a-zA-z0-9-]+)/links
POST /company/{company_id}([0-9])/resolver/{resolver_id}([a-zA-z0-9-]+)/links

This endpoint will allow a company to gather the Resolver Links or create a brand new Resolver Link tied to a resolver. This link is the actual URL that will show within the Linkset for the specific GS1 Linktype (Appendix A).

Example Requests

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint
url = f'https://atp.med/api/v1.0/company/1/resolver/b0c8cc3f-deeb-4333-8874-2d7480334455/links/' 
headers = {'Authorization': f'Bearer {token}'}

# Example GET
r = requests.get(url, headers=headers)

# Example POST

payload = {
  'title': 'Master Data',
  'href': 'https://my.masterdata.endpoint/',
'hreflang': 'en',
'link_type': 'gs1:masterData'
}
r2 = requests.post(url, headers=headers, data=payload)
cURL
curl --request GET \
--url 'http://atp.med/api/v1.0/company/1/resolver/b0c8cc3f-deeb-4333-8874-2d7480334455/links/' \
--header 'Authorization: Bearer abc123...x_yz'

curl --request POST \
--url 'http://atp.med/api/v1.0/company/1/resolver/b0c8cc3f-deeb-4333-8874-2d7480334455/links/' \
--header 'Authorization: Bearer abc123...x_yz' \
--data '{"title": "Master Data", "href": "https://my.masterdata.endpoint/","hreflang":"en","link_type":"gs1:masterData" }'

Response Data

The following is the response data schema:

Note: The GET request returns a paginated result with a total result count as “count” and the following schema as a list under the “results” item.

Item Format Description
id([a-zA-Z0-9-)+The UUID4 id for the Resolver Link
titleStringThe title of the Resolver Link
hrefStringThe URL for the data endpoint
hreflangStringThe language the data endpoint is in (default: en)
link_typeStringThe GS1 Link Type for this Resolver Link
created_atDateTimeWhen the Resolver Link was created

Update Resolver Link Data URL

PATCH
/company/{company_id}([0-9])/resolver/{resolver_id}([a-zA-z0-9-]+)/links/{link_id}([a-zA-z0-9-]+)

Use this endpoint to update the Data URL for the Resolver Link.

Example Requests

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint
url = 
f'https://atp.med/api/v1.0/company/1/resolver/b0c8cc3f-deeb-4333-8874-2d7480334455/links/b0c8cc3f-deeb-4333-8874-2d7480445566/' 
headers = {'Authorization': f'Bearer {token}'} 

# Example PATCH
payload= { 'href': 'https://my.new.url/' }
r2 = requests.patch(url, headers=headers, data=payload)
cURL
curl --request PATCH \
--url
'http://atp.med/api/v1.0/company/1/resolver/b0c8cc3f-deeb-4333-8874-2d7480334455/links/b0c8cc3f-deeb-4333-8874-2d7480445566/' \
--header 'Authorization: Bearer abc123...x_yz' \
--data '{"href": "https://my.new.url/" }'

Response Data

The following is the response data schema:

Item Format Description
id([a-zA-Z0-9-)+The UUID4 id for the Resolver Link
titleStringThe title of the Resolver Link
hrefStringThe URL for the data endpoint
hreflangStringThe language the data endpoint is in (default: en)
link_typeStringThe GS1 Link Type for this Resolver Link
created_atDateTimeWhen the Resolver Link was created

VRS Endpoints

Add Products to VRS by GTIN

POST /vrs/company/{company_id}([0-9])/gtin/{gtin}([0-9])

Use this endpoint to add a product to the Trust.Med Lookup Directory, which will be synced to all working VRS partners.

NOTE: This endpoint is currently under development. More methods may become available as development continues.

Request Data

The following is the request data schema, expected as a JSON payload passed in the body:

Item Format Required Description
recordOwnerStringYThe Global Company Prefix (GCP) of the record owner
ciStringYThe connectivity information (e.g. URL, IP address) of the responder
startExpDateDateTimeYLowerd bound of expiration date value
endExpDateDateTimeNUpper bound of expiration date value
statusStringY"active", "inactive", or "deleted"
nextRecordOwnerStringNThe GCP of the next record owner if the product is being transferred. This should match recordOwner if not in transfer

 

Example Requests

Python
import requests

token = getAccessToken() # Defined by GenerateAccessToken endpoint 
url = f'https://atp.med/api/v1.0/vrs/company/1/gtin/12345678901234' 
headers = {'Authorization': f'Bearer {token}'}

 
# Example POST
payload= {
  'recordOwner': '123456',
  'ci': 'https://vrs-endpoint.med/vrs',
  'startExpDate': '200101',
  'endExpDate': '251231',
  status: 'active',
  'nextRecordOwner': '123456'
}
r2 = requests.post(url, headers=headers, data=payload)
cURL
curl --request POST \
--url 'http://atp.med/api/v1.0/vrs/company/1/gtin/12345678901234' \
--header 'Authorization: Bearer abc123...x_yz' \
--data '{"recordOwner": "123456", "ci": "https://vrs-endpoint.med/vrs", 
"startExpDate": "200101", "endExpDate": "251231", "status":"active", "nextRecordOwner": "123456" }'curl

Response Data

The following is the response data schema:

Item Format Description
id([a-zA-Z0-9-)+The UUID4 id for the record
gtinStringThe GTIN value for the product
recordOwnerStringThe Global Company Prefix (GCP) of the record owner
ciStringThe connectivity information (e.g. URL, IP address) of the responder
startExpDateDateTimeThe earliest point for product expiration
endExpDateDateTimeThe latest point for product expiration
nextRecordOwnerStringThe GCP of the next record owner if the product is being transferred

Appendix

Appendix A: Accepted GS1 Link Types

Name Code
Allergy Informationgs1:allergenInfo
Brand Homepage Progs1:brandHomepageClinical
Brand Homepage Patientgs1:brandHomepagePatient
Consumer Handling & Storagegs1:consumerHandlingStorageINfo
EPCISgs1:epcis
Patient Information Leafletgs1:epil
Frequently Asked Questionsgs1:faqs
Org Info Pagegs1:homepage
Ingredients Informationgs1:ingredientsInfo
Instructionsgs1:instructions
Location Informationgs1:locationInfo
Master Datags1:masterData
Product Info Pagegs1:pip
Recall Statusgs1:recallStatus
Related Videogs1:relatedVideo
Reviewsgs1:review
Safety Informationgs1:safetyInfo
Smart Label Pagegs1:smartLabel
Summary Product Characteristicsgs1:smpc
Support Pagegs1:support