API Reference

verifications

Welcome to the Medallion Verifications API!

The Primary Source Verification (PSV) API allows you to quickly and automatically verify provider credentials at scale. This API directly integrates with hundreds of primary source sites to pull the verification information you need to keep your provider workflows moving and cut out costly manual steps. Whether you choose to integrate this API as part of a scheduled batch workflow, or call it on demand to power individual checks, we have you covered for all your automated verification needs.

The PSV API currently automatically verifies sources such as:

  • NPI number
  • State licenses
  • CDS state licenses
  • OIG sanctions
  • SAM sanctions
  • Medicare opt-out
  • DEA registrations
  • NPDB reports
  • Board certificates from ABMS

Like all Medallion products, the API is backed by realtime application monitoring to ensure you get reliable, accurate responses every time you use it.

Using the Verifications API

Step 1: Get your credentials

You'll need your an API key to use the Verifications API. Contact your CSM to get that information for your organization.

Step 2: Send a request

Send a request to this endpoint to create a verification request. Here's an example using cURL:

curl -X POST \
  https://verifications.medallion.co/p/api/v1/verifications/ \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api_key>' \
  -d '{"includes":["state_license", "dea"],"provider":{"first_name":"John", "last_name": "Doe", "state_license": [{"state": "NY", "number": 12345}], "dea_registrations": [{"state": "NY", "dea_registration_number": 54321}] }}'

A successful response will include a top-level id:

{
  "id": "8cb277f4-c168-4eca-8d77-aba8da20427b",
  "includes": ["state_license", "dea"],
  "status": "PROCESSING",
  "provider": {
    "first_name":"John",
    "last_name": "Doe",
    "state_licenses": [
      {
        "state": "NY",
        "number": "12345"
      }
    ],
    "dea_registrations": [
      {
        "state": "NY",
        "dea_registration_number": "54321"
      }
    ]
  }
}

Keep this ID; you'll need it to query for your results!

Step 3: Poll the Verifications API for results

Use the ID you saved above to query the Verifications API for a request's results. Here's another example using cURL:

curl -X GET \
  https://verifications.medallion.co/p/api/v1/verifications/<request_id> \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api_key>'

Check the status on the response you receive from this call. If status is pending or processing, the Verifications API hasn't completed all of the verifications you requested yet.

Poll the Verifications API at regular intervals. Once status is done, all the verifications you requested will have results available in the results field of the response.

Here's a sample response:

{
  "id": "8cb277f4-c168-4eca-8d77-aba8da20427b",
  "include": ["state_license", "dea"],
  "status": "DONE",
  "provider": {
    "first_name":"John",
    "last_name": "Doe",
    "date_of_birth": "1953-02-25",
    "ssn": "123456789",
    "npi": "0123456789",
    "state_licenses": [
      {
        "state": "NY",
        "number": "12345"
      }
    ],
    "dea_registrations": [
      {
        "state": "NY",
        "number": "54321"
      }
    ]
  },
  "verifications": {
    "state_licenses": [
      {
        "status": "FOUND",
        "input_license": {
          "state": "CO",
          "number": "CDRH.0054832"
        },
        "sourced_at": "2022-06-03T22:31:58+0000",
        "outcome": "VERIFIED",
        "results": [
          {
            "source": {
              "source_name": "NY State License Board",
              "method_of_retrieval": "WEB",
              "url": "https://www.health.ny.gov/professionals/doctors/conduct/license_lookup.htm",
              "version_date": "2022-06-03T22:31:58+0000",
              "is_primary": true
            },
            "sourced_at": "2022-06-03T22:31:58+0000",
            "issued_by": "NY State License Board",
            "matching_criteria": {
              "first_name: "John",
              "last_name": "Doe",
              "license_number": "12345"
            },
            "record": {
              "url": "http://www.nysed.gov/coms/abc/abc?profcd=12&plicno=12345&namechk=abc"
              "screenshot_url": "https:cdn.medallion/12345-abcd-1234-abcd",
              "expiration_date": "2025-10-25",
              "is_active": true,
              "status": "Primary Status: Active",
              "has_disciplinary_action": false,
            }
          }
        ]
      }
    ],
    "dea": [
      {
        "status": "FOUND",
        "outcome": "VERIFIED",
        "sourced_at": "2023-05-11T19:25:14Z",
        "input_registration": {
          "state": null,
          "dea_registration_number": "12345",
          "state_license_numbers": [],
          "expiration_date": null,
          "active": null
        },
        "results": [
          {
            "source": {
              "source_name": "Drug Enforcement Agency",
              "method_of_retrieval": "FLAT_FILE",
              "url": "https://www.dea.gov",
              "version_date": "2023-05-08T00:00:00Z",
              "is_primary": true
            },
            "sourced_at": "2022-06-03T22:31:58+0000",
            "matching_criteria": {
              "first_name":"John",
              "last_name": "Doe",
              "certificate_number": "54321",
              "state": "NY"
            },
            "record": {
              "name": "JOHN DOE",
              "dea_registration_number": "12345",
              "state_license_number": "12345",
              "state_cs_license_number": "12345",
              "state": "NY",
              "certificate_number": "54321",
              "expiration_date": "2022-06-03",
              "drug_schedules": "22n 33n 4 5",
            }
          }
        ]
      }
    ]
  }
}