API Basics

Authentication

The Medallion API requires authentication to ensure the security of your data.

In order to access any of the available API endpoints, you need to pass your unique, secret key in the request header.

"x-api-key": "YOUR_API_KEY"

curl --request GET \
     --url 'https://api.medallion.co/api/v1/org/licenses?limit=200' \
     --header 'Accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

If you are making a request using our API Reference page you will need to enter your API key in the field shown below.

Please reach out to your Medallion Customer Success Manager if you are interested in having an API key.

Error Handling

Below are some common error messages that you may encounter as well as their corresponding meanings.

Response	Name	Meaning	Troubleshoot
400	Bad Request	The 400 status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error.	- Correct any errors mentioned in the response body. - Check the correctness of your path parameters (e.g. valid provider id). - Verify that you are using the correct format for the parameters. (e.g. dates are not of the form YYYY-DD-MM).
403	Unauthorized	The 403 status code indicates that your x-api-key header is missing or invalid.	- Check that you have provided an x-api-key header. - Verify that your API Key is correct. - If you need an API Key, please reach out to your Medallion Representative.
404	Not Found	The 404 status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.	- You may be trying to access a provider or organization that does not exist or you are not authorized to access. Please verify the id you pass to the path parameter. - If you are trying to get, patch or delete a specific object, you might have passed the wrong path parameter id or that id might not be for the correct endpoint (e.g. if you pass an id that matches a training object but you are requesting '/educations').
500	Internal Server Error	The 500 status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.	Please reach out to your Medallion Representative.

Please refer to RFC 9110 for a more comprehensive list of statuses that can be returned.

Recommended Usage

Only Ingest Necessary Fields

We recommend that you only ingest the fields you need for your records from our API responses. This will reduce ETL failures from unnecessary data and the work needed by your team to make updates when our API changes. If you are ingesting all fields returned by our API, you will need to update your integration any time a backwards incompatible change is released. As our API is actively developed, breaking changes may be released as often as once a month. If we make a breaking change you will be notified via email at least 30 days in advance so you have time to update your integration (API Versioning).