Overview

Our API Reference page contains endpoint specific documentation to allow users to explore our functionality and understand the breadth of data and actions available for integration with their internal systems. This page will explain how to navigate and read this documentation.

Navigation

On the left side of the API Reference page you will see a menu with several sections. Each section represents an available API such as the Medallion API which provides functionality available in the Medallion platform. Within these APIs, endpoints are organized under "tags" representing resources within the Medallion platform. You can expand a tag to view the endpoints available for a particular resource. For instance, the providers tag includes an endpoint to GET all providers in your organization as well as an endpoint to GET and PATCH those providers by id.

Endpoint Documentation

When you click on a specific endpoint in the navigation menu, the documentation for that endpoint will appear in the page content. The endpoint documentation is shown in two columns. On the left is the main panel including details about the fields available in the request and response. On the right is a tool for easily testing your request and viewing a response preview. The history of your tested requests and responses is shown at the top of the left column.

Fields

The endpoint documentation consists of fields that are available as request parameters and response data. There are several attributes of each field that are indicated by the documentation.

Name

All fields will have a name. Names should be descriptive and explain the meaning of the field. They will also be used in query parameters and the request body to identify the meaning of the accompanying value.

Type

Each field will display a type next to its name. The type can be any of the following: string, integer, boolean, array, date, date-time, uri, object.

📘

In general fields that represent the primary key of a record will be documented as a string type but will expect a uuid.

The object type indicates a json object with one or more nested fields. We recognize that obscured fields can be frustrating and complete documentation is important. We are always improving our documentation and we aim to fully document all objects.

Required

Fields may be required in a URL path, as query parameter, or in a request body. If a field is required it will be indicated by the word "required" in red to the right of the type.

Allowed Values

In some cases null will be displayed to the right of the type. This means that null or empty is a valid value for this field.

If a request parameter is an enum the possible values will be indicated by a dropdown rather than a free text field.

If a response field is an enum the possible values will be indicated by tags listed under the field name.

Request

Path Parameters

Path parameters are values that appear within an endpoint URL. These are most often used to identify a particular object by primary key and are therefore either a uuid or integer value. Path parameters appear at the top of the endpoint documentation directly below your test history. For example the provider_pk field is shown below as part of the URL and is editable within the Path Params section of the documentation

Query Parameters

Query parameters are shown for GET requests directly below path parameters. Query parameters can be used to specify filtering, search, ordering, or pagination of the API response. To add a query parameter to your request you can use the following format:

{endpoint_path}?{query_param_1}={value1}&{query_param_2}={value2}

# Example shown in image
"https://api.medallion.co/api/v1/providers/?accepting_new_patients=true&active_request_products=Payer"

Body Parameters

Body parameters are shown for POST and PATCH requests. These fields specify the values that will be used to create or modify a new object. They should be included in a data field within the request.

# Example shown in image
curl --request PATCH \
     --url https://app.medallion.co/api/v1/org/providers/provider_pk/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: {your_api_key}' \
     --data '
{
  "first_name": "test"
}
'

Response

Responses are shown below all request parameters. You can click on a response item to view the fields returned in that response.

Descriptions and resolution of error responses are available in our API Basics section

Try It

You will notice that all request parameters have an editable value field next to them. Values entered in these fields will automatically appear in the testing tool in the right column of our endpoint documentation. This tool allows you to preview your request and send the request to Medallion's servers. To authenticate your request you will need to enter your API Key in the field at the top of the right column. Once you submit the request the response will be shown below the request preview. You can review previous tests in the request history at the top of the left column.

🚧

Note that if you use the "Try It" feature with a production API key you will modify your data in production. If you need a testing environment please reach out to your Medallion Representative.