Public API
The public API of azuma hokoku allows you to create new PV cases, which we in turn will propagate to the relevant pharma companies.
Getting access
To be able to use the azuma hokoku public API, a valid access token with the scope azmhokoku_pv_case_ext is required.
Please contact us for information on how to get a client with that scope.
Documentation
The documentation of the mutation createPvCase can be found in "Developer API"
Relevant APIs
Mutations:
- createPvCase: Used to create a new PV case
Queries:
- Get Case by ID
query {
pv {
case (id: '**your_case_id**')
{
...
}
}
}
The primary use case is to create PV cases by using the client credentials flow. You can, however, create cases in "Developer Portal" on the PIE environment.
Data model
Every PV case in azuma consists of the following:
- Source of the case
- Drug associated with the case
- Patient data
- Reporters (1-n)
- Events (1-n)
Case source
This is required to identify the primary source of the case. The following values are currently available:
- Patient
- Doctor
Case source is used to trigger the appropriate workflow to propagate the data to the pharma company.
Drug and Company
Information for the drug that is suspected to have a type of interaction.
The important information here are
- Drug name
- Drug company
- Company contacts, if available
- Custom Identifiers, if available
Identification: Drug
azuma hokoku has a management system for drugs to identify drugs and to avoid duplication.
Should your system be able to identify drugs based on a certain ID or PZN, please also provide that ID/PZN during case creation like this:
customIdentifiers: [
{
identifier:"**your_id**",
type: EXTERNAL_ID
}
]
or
customIdentifiers: [
{
identifier:"**pzn**",
type: PZN
}
]
Identification: Company
azuma hokoku has a management system for companies to identify companies and to avoid duplication.
Should your system be able to identify companies based on a certain ID or VAT_NR, please also provide that ID/VAT_NR during case creation like this:
customIdentifiers: [
{
identifier:"**your_id**",
type: EXTERNAL_ID
}
]
or
customIdentifiers: [
{
identifier:"**pzn**",
type: VAT_NR
}
]
Patient
Patient data are for the person who experienced one or several adverse events/reactions.
Identification
azuma hokoku has a management system for patients to identify patients and to avoid duplication. Patient data passed in during case creation is saved for the created case.
Should your system be able to identify patients based on a certain ID, please also provide that ID during case creation like this:
customIdentifiers: [
{
identifier:"**your_id**",
type: EXTERNAL_ID
}
]
Reporters (1-n)
Reporters are people who provided the facts about the case and can be regarded as the primary source of information.
Classification
Reporters are classified as primary and secondary. The primary reporter is the primary source for regulatory purposes.
Exactly one reporter per case has to be marked as primary.
Identification
azuma hokoku has a management system for reporters to identify reporters and to avoid duplication. Reporter data passed in during case creation is saved for the created case.
Should your system be able to identify reporters based on a certain ID, please also provide that ID during case creation like this:
customIdentifiers: [
{
identifier:"**your_id**",
type: EXTERNAL_ID
}
]
Events (1-n)
Events describe the reaction of the patient. At least one event needs to be provided.
Each event consists of
- Side effect data
- Reaction data
- Medication data
- Outcome data
Side effect data
Side effects in PV context are classified by the MedDRA terminology. If available, please use the MedDRA code. If not please provide the ICD-10 or Snomed CT code if present. In any case, please provide the original description in the "originalTerm" field.
Example
Request token
Token url:
curl --location '**token url**' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=**your_client_id**' \
--data-urlencode 'client_secret=**your_client_secret**' \
--data-urlencode 'scope=azmhokoku_pv_case_ext'
with the following result:
{
"access_token": "...",
"expires_in": 3599,
"scope": "azmhokoku_pv_case_ext",
"token_type": "bearer"
}
Create PV Case
API url:
curl --location '*api url**' \
--header 'Authorization: Bearer **access_token**' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation {\r\n createPvCase(\r\n input: {\r\n source: PATIENT,\r\n reportedAt: \"2023-05-12 16:52:51\",\r\n drug: {\r\n name: \"Test drug\",\r\n identifiers: [{\r\n identifier: \"My unique identifier\",\r\n type: EXTERNAL_ID\r\n }\r\n ],\r\n company: {\r\n name: \"Test company\",\r\n contacts: [{\r\n type: EMAIL,\r\n data: \"test@test-company.de\"\r\n }\r\n ],\r\n identifiers: [{\r\n identifier: \"my great unique company identifier\",\r\n type: EXTERNAL_ID\r\n }\r\n ]\r\n }\r\n },\r\n patient: {\r\n patientData: {\r\n age: 33,\r\n sex: MALE\r\n }\r\n },\r\n reporters: [{\r\n reporterData: {\r\n givenName: \"Reporter\",\r\n familyName: \"One\"\r\n },\r\n classification: PRIMARY\r\n }\r\n ],\r\n events: [{\r\n originalTerm: \"Kopfschmerzen\"\r\n \r\n reaction:{\r\n startOfReaction:\"2023-05-12 16:52:51\",\r\n }\r\n }\r\n ]\r\n }) {\r\n id\r\n linkUrl\r\n }\r\n}\r\n","variables":{}}'
with the following result:
{
"data": {
"createPvCase": {
"id": "*case_id*",
"linkUrl": "*case_link*"
}
}
}
the query from the request looks like this:
mutation {
createPvCase(
input: {source: PATIENT, reportedAt: "2023-05-12 16:52:51", drug: {name: "Test drug", identifiers: [{identifier: "My unique identifier", type: EXTERNAL_ID}], company: {name: "Test company", contacts: [{type: EMAIL, data: "test@test-company.de"}], identifiers: [{identifier: "my great unique company identifier", type: EXTERNAL_ID}]}}, patient: {patientData: {age: 33, sex: MALE}}, reporters: [{reporterData: {givenName: "Reporter", familyName: "One"}, classification: PRIMARY}], events: [{originalTerm: "Kopfschmerzen", reaction: {startOfReaction: "2023-05-12 16:52:51"}}]}
) {
id
linkUrl
}
}