API

Documentation:

The medcode API allows you to fetch data of target Diagnoses and Procedures. In this documentation the term resource stands for a specific procedure or diagnosis (e.g. PCS or CHOP)

Currently, our API implements the following three types of requests:

GET the catalog names of a target resource
GET a resource by its catalog and code
GET all resources in a certain catalog that match a given search-query.

The search query can either be a code prefix, a term or even a text that is associated with the corresponding resource. For further information please have a look at the specific API endpoint documentations.

Authentication

To use our API you need to be authenticated using a token. You can obtain an API token by sending an email to info@medcode.ch

Locale

Most requests respect a locale parameter that will determine the language of the parsed query and the language of the descriptions within the results. For example, you can set the language to italian using &locale=it. Supported locales are de, fr, it, en Unless specified, the default language is en (English).

Requests

Catalog

Find:

METHOD: GET
Description: Get all catalogs of a certain resource
INFO: This request can only be performed when passing your API token. However, when not providing a token, the requests are throttled.
URL: /api/v1/catalogs/:resource
PARAMS:

client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/catalogs/icd/PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/catalogs/icd?client_access_token=TOKEN'
Response: {
   "message":"OK",
   "data":[
     "icd10-2010","icd-10-cm-2017","icd-10-cm-2016",
     "icd-10-cm-2015","icd-10-cm-2018","icd10-gm-2017",
     "icd10-2008","icd10-2016","icd10-gm-2014",
     "icd10-gm-2016","icd10-gm-2015","icd10-gm-2012",
     "icd10-gm-2011","icd10-gm-2013","icd10-gm-2010",
     "icd10-gm-2008"
  ]
}
Error Responses:

401 Unauthorized
404 MODEL with code CODE not found: In case there is no given record for the given model with the provided params.

ICD

Search:

METHOD: GET
Description: Get all ICDs that match a certain search criterion.
INFO: This request can only be performed when passing your API token.
URL: /api/v1/icds/:catalog
PARAMS:

search: a search term that should match the target resource
client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: Search by code prefix "A00"
CURL: curl -X GET 'https://medcode.ch/api/v1/icds/icd-10-cm-2018?search=A00&client_access_token=TOKEN'
Response
{
  "message":"OK",
  "data":"[
    {
      "id":506672,
      "catalog":"ICD-10-CM-2018",
      "code":"A00",
      "text":"Cholera",
      "inclusions":[],
      "exclusions":[],
      "coding_hint":null,
      "note":null,
      "terminal":false,
      "synonyms":[],
      "subclasses":["A00.0","A00.1","A00.9"],
      "usage":null,
      "most_relevant_drgs":[]
    },
    {
      "id":506674,
      "catalog":"ICD-10-CM-2018",
      "code":"A00.0",
      "text":"Cholera due to Vibrio cholerae 01, biovar cholerae",
      "inclusions":[],
      "exclusions":[],
      "coding_hint":null,
      "note":null,
      "terminal":true,
      "synonyms":["Classical cholera"],
      "subclasses":[],
      "usage":null,
      "most_relevant_drgs":[]
    },
    {
      "id":506676,
      "catalog":"ICD-10-CM-2018",
      "code":"A00.1",
      "text":"Cholera due to Vibrio cholerae 01, biovar eltor",
      "inclusions":[],
      "exclusions":[],
      "coding_hint":null,
      "note":null,
      "terminal":true,
      "synonyms":["Cholera eltor"],
      "subclasses":[],
      "usage":null,
      "most_relevant_drgs":[]
    },
    {
      "id":506677,
      "catalog":"ICD-10-CM-2018",
      "code":"A00.9",
      "text":"Cholera, unspecified",
      "inclusions":[],
      "exclusions":[],
      "coding_hint":null,
      "note":null,
      "terminal":true,
      "synonyms":[],
      "subclasses":[],
      "usage":null,
      "most_relevant_drgs":[]
    }
  ]"
}

Example: Search by the term "Unspecified injury of ovary"
CURL: curl -X GET 'https://medcode.ch/api/v1/icds/icd-10-cm-2018?search=Unspecified injury of ovary&client_access_token=TOKEN'
Response
{
  "message":"OK",
  "data":"[
    {
      "id":528259,
      "catalog":"ICD-10-CM-2018",
      "code":"H71.90",
      "text":"Unspecified cholesteatoma, unspecified ear"
      ...
    },
    ...,
    {
      "id":576344,
      "catalog":"ICD-10-CM-2018",
      "code":"S73.003",
      "text":"Unspecified subluxation of unspecified hip",
      ...
    }
  ]"
}

Error Responses:

400 Bad Request": In case no search param is provided
401 Unauthorized": In case no credentials were provided

Find:

METHOD: GET
Description: Get the data of a ICD that belong to a given catalog and code.
INFO: This request can only be performed when passing your API token. However, when not providing a token, the requests are throttled.
URL: /api/v1/icds/:catalog/:code
PARAMS:

client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/icds/ICD-10-CM-2018/A00?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/icds/icd-10-cm-2018/A00?client_access_token=TOKEN'
Response
{
  "message":"OK",
  "data":"{
    "id":506672,
    "catalog":"ICD-10-CM-2018",
    "code":"A00",
    "text":"Cholera",
    "inclusions":[],
    "exclusions":[],
    "coding_hint":null,
    "note":null,
    "terminal":false,
    "synonyms":[],
    "subclasses":["A00.0","A00.1","A00.9"],
    "usage":null,
    "most_relevant_drgs":[]
  }"
}

Error Responses:

400 Bad Request": In case no search param is provided
404 MODEL with code CODE not found: In case there is no given record for the given model with the provided params.

PCS

Search:

METHOD: GET
Description: Get all PCS that match a certain search term.
INFO: This request can only be performed when passing your API token.
URL: /api/v1/pcs/:catalog
PARAMS:

search: a search term that should match the target resource
client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources. 

Example: Search by code prefix "XY0VX"
CURL: curl -X GET 'https://medcode.ch/api/v1/pcs/ICD-10-PCS-2018?search=XY0VX&client_access_token=TOKEN'
Response: {
  "message": "OK",
  "data":"[
    {
      "id":380350,
      "catalog":"ICD-10-PCS-2018",
      "terminal":false,
      "code":"XY0VX",
      "text":"External",
      "axis":5,
      "subclasses":["XY0VX8"],
      "inclusions":[],
      "exclusions":[],
      "synonyms":["External"]
    },
    {
      "id":380352,
      "catalog":"ICD-10-PCS-2018",
      "terminal":true,
      "code":"XY0VX83",
      "text":"Extracorporeal Introduction of Endothelial Damage Inhibitor to Vein Graft, New Technology Group 3",
      "axis":7,
      "subclasses":[],
      "inclusions":[],
      "exclusions":[],
      "synonyms":[]
    },
    {
      "id":380351,
      "catalog":"ICD-10-PCS-2018",
      "terminal":false,
      "code":"XY0VX8",
      "text":"Endothelial Damage Inhibitor",
      "axis":6,
      "subclasses":["XY0VX83"],
      "inclusions":[],
      "exclusions":[],
      "synonyms":["Endothelial Damage Inhibitor","DuraGraft(R) Endothelial Damage Inhibitor"]
    }
  ]"
}

Example:Search by the term "Endothelial Damage"
CURL: curl -X GET 'https://medcode.ch/api/v1/pcs/ICD-10-PCS-2018?search=Endothelial&nbspDamage&client_access_token=TOKEN'
Response: {
{
  "message":"OK",
  "data":"[
    {
      "id":380351,
      "catalog":"ICD-10-PCS-2018",
      "terminal":false,
      "code":"XY0VX8",
      "text":"Endothelial Damage Inhibitor",
      "axis":6,
      "subclasses":["XY0VX83\"],
      "inclusions":[],
      "exclusions":[],
      "synonyms":["Endothelial Damage Inhibitor","DuraGraft(R) Endothelial Damage Inhibitor"]
    },
    {
      "id\":380352,
      "catalog":"ICD-10-PCS-2018",
      "terminal":true,
      "code":"XY0VX83",
      "text":"Extracorporeal Introduction of Endothelial Damage Inhibitor to Vein Graft, New Technology Group 3",
      "axis":7,
      "subclasses":[],
      "inclusions":[],
      "exclusions":[],
      "synonyms":[]
    }
  ]"
}

Error Responses:

400 Bad Request": In case no search param is provided
401 Unauthorized": In case no credentials were provided

Find:

METHOD: GET
Description: Get the data of a PCS that belong to a given catalog and code.
INFO: This request can only be performed when passing your API token. However, when not providing a token, the requests are throttled.
URL: /api/v1/pcs/:catalog/:code
PARAMS:

client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/pcs/ICD-10-PCS-2018/XY0VX83?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/pcs/ICD-10-PCS-2018/XY0VX83?client_access_token=TOKEN'
Response
{
  "message":"OK",
  "data":"{
    "id":380352,
    "catalog":
    "ICD-10-PCS-2018",
    "terminal":true,
    "code":"XY0VX83",
    "text":"Extracorporeal Introduction of Endothelial Damage Inhibitor to Vein Graft, New Technology Group 3",
    "axis":7,
    "subclasses":[],
    "inclusions":[],
    "exclusions":[],
    "synonyms":[]
  }"
}

Error Responses:

400 Bad Request": In case no search param is provided
404 MODEL with code CODE not found: In case there is no given record for the given model with the provided params.

CHOP

Search:

METHOD: GET
Description: Get all CHOPs that match a certain search criterion.
INFO: This request can only be performed when passing your API token.
URL: /api/v1/chops/:catalog
PARAMS:

search: a search term that should match the target resource
client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/chops/CHOP 2011?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/chops/chop&nbsp2011?search=99.B5.49&client_access_token=TOKEN'
Error Responses:

400 Bad Request": In case no search param is provided
401 Unauthorized": In case no credentials were provided

Find:

METHOD: GET
Description: Get the data of a CHOP that belong to a given catalog and code.
INFO: This request can only be performed when passing your API token. However, when not providing a token, the requests are throttled.
URL: /api/v1/chops/:catalog/:code
PARAMS:

client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/chops/CHOP 2011/99.B5.49?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/chops/chop&nbsp2011/99·B5·/'
Error Responses:

400 Bad Request": In case no search param is provided
404 MODEL with code CODE not found: In case there is no given record for the given model with the provided params.

OPS

Search:

METHOD: GET
Description: Get all OPS that match a certain search criterion.
INFO: This request can only be performed when passing your API token.
URL: /api/v1/ops/:catalog
PARAMS:

search: a search term that should match the target resource
client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/ops/OPS-2013?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/ops/OPS-2013?search=1-10&client_access_token=TOKEN'
Error Responses:

400 Bad Request": In case no search param is provided
401 Unauthorized": In case no credentials were provided

Find:

METHOD: GET
Description: Get the data of a OPS that belong to a given catalog and code.
INFO: This request can only be performed when passing your API token. However, when not providing a token, the requests are throttled.
URL: /api/v1/ops/:catalog/:code
PARAMS:

client_access_token: your credentials

Response

message: a string that contains the response status message 
data: an array that contains the fetched resources 

Example: api/v1/ops/OPS-2013/1-10?PARAMS
CURL: curl -X GET 'https://medcode.ch/api/v1/ops/OPS-2013/1-10?client_access_token=TOKEN'
Error Responses:

400 Bad Request": In case no search param is provided
404 MODEL with code CODE not found: In case there is no given record for the given model with the provided params.