Alpha Sophia API Docs

Guides

Introduction Authorization

Resources

Search HCPs Search Filters
Introduction

This is the API documentation for the Alpha Sophia API. The Alpha Sophia API is a RESTful API that allows you to access the Alpha Sophia database of healthcare providers and organizations. Please be aware that this API is still in beta and may change in the future.

API Base URL:

https://api.alphasophia.com/v1/

Talk to Customer Success if you have any questions or feedback, or want to give it a try.
🚨 Please make sure all requests are URL encoded.

Authentication

All API requests need to be authenticated. If you have a valid Alpha Sophia subscription with the API Module enabled, you can click here đź”— to generate an API key.

This can be done by passing the API key in the x-api-key header.

  • Name
    x-api-key
    Type
    string
    Description

    The header x-api-key needs to contain the API key you have received from Alpha Sophia.

Search HCPs

This search endpoint allows you to retrieve a paginated list of all healthcare providers (HCP) in the United States, based on a variety of filters. By default, 10 HCPs are shown per page.

ℹ️ The easiest way to construct a search query is to use the Alpha Sophia platform 🔗 . Once you have constructed your search, you can copy the URL and use it as the search query for this API.

Filter basics
  • All filters are optional and can be combined to create a custom search.
  • All filters need to be passed as query strings (see details below).
  • Multiple filters are combined with a logical AND (e.g. speciality “Dermatologist” and located in “New York City”).
  • Multiple values within a filter are by default combined with a logical OR (e.g. speciality “Dermatologist” or “Cardiologist”). However, this can be changed for some filters by adding “$and” to the filter query (see below).
All filters
  • Name
    page
    Type
    integer
    Description

    The page number to return. Defaults to 1.

    Example:

    ?page=1

  • Name
    pageSize
    Type
    integer
    Description

    The number of items to return per page. Defaults to 10. Can either be 10, 25, 50, or 100.

    Example:

    ?pageSize=10

  • Name
    order-by
    Type
    string
    Description

    The field to order the results by. Defaults to ap-volume (All-Payor Procedure Volume). Options are:

    • sales (Medicare Part B Procedure Charges)
    • volume (Medicare Part B Procedure Volume)
    • ap-volume (All-Payor Procedure Volume)
    • ap-patients (All-Payor Procedure Patients)
    • licenses (Number of State Licenses)
    • rx-cost (Medicare Part D Prescription Drug Costs)
    • rx-volume (Medicare Part D Prescription Drug Volume)
    • op-amount (OpenPayments Payments Amount)
    • op-count (OpenPayments Payments Frequency)
    • ccsr-volume (All-Payor Diagnosis Volume)
    • ccsr-patients (All-Payor Diagnosis Patients)
    Example:

    ?order-by=ap-volume

  • Name
    time
    Type
    string
    Description

    Time parameter for filtering results based on the order by parameter (e.g. Medicare Part B procedure volumes). Defaults to the most recent year for which data is available (last-year). You can use another year instead (e.g. 2022).

    Example:

    ?time=last-year

    Example:

    ?time=2022

  • Name
    npi
    Type
    string
    Description

    Filter results by National Provider Identifier (NPI) đź”— . The filter values are the NPI numbers. This filter supports include and exclude.

    Example:

    ?npi=+1234567890,+9876543210

  • Name
    deactivated
    Type
    string
    Description

    You can decide to also include deactivated NPIs in the results. By default, only active NPIs are included. Setting this to true will include deactivated NPIs.

    Example:

    ?deactivated=true

  • Name
    name
    Type
    string
    Description

    Filter results by healthcare provider name. The filter values are string values and need to be enclosed in quotes. This filter supports include and exclude.

    Example:

    ?name=+“PAUL”,“JOHN”

  • Name
    taxonomy
    Type
    string
    Description

    Filter results by using the standard NUCC taxonomy code đź”— . The filter values are the taxonomy codes. This filter supports include and exclude.

    Example:

    ?taxonomy=+207X00000X,+2B207XX0801X

    Example:

    ?taxonomy=$and,+207X00000X,+2B207XX0801X

  • Name
    classification
    Type
    string
    Description

    Filter by classification. This filter will only return results for HCPs whose taxonomy are within the specified classification according to their NPPES data. The filter values are the Alpha Sophia classification IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?classification=+2,+4

  • Name
    grouping
    Type
    string
    Description

    Filter by grouping. This filter will only return results for HCPs whose taxonomy are within the specified grouping according to their NPPES data. The filter values are the Alpha Sophia grouping IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?grouping=+2,+4

  • Name
    taxonomy-primary
    Type
    string
    Description

    Setting this to true will ensure that the filters taxonomy, classification, and grouping filters are only applied to the primary taxonomy of the HCP. By default, all provider taxonomies (in case of multiple taxonomies) are used. Setting this to true will only use the primary taxonomy.

    Example:

    ?taxonomy-primary=true

  • Name
    license
    Type
    string
    Description

    Filter by state license. This filter will only return results for HCPs that are licensed in the specified state according to their NPPES data or another license source (e.g. state boards). The filter values are the USPS 2 digit state abbreviations. This filter supports include and exclude.

    Example:

    ?license=+NY,+CA,+TX

  • Name
    license-count
    Type
    string
    Description

    Filter by license count. This filter will only return results for HCPs that have a license count between the specified range. This filter supports a range, between a minimum or a maximum number of licenses (or both).

    Example:

    ?license-count=3-5

    Example:

    ?license-count=3

    Example:

    ?license-count=-5

  • Name
    past-license
    Type
    string
    Description

    Setting this to true will ensure that the filters license and license-count also include historic licenses. By default, only active licenses are included.

    Example:

    ?past-license=true

  • Name
    territory
    Type
    string
    Description

    Filter by a specific territory already defined by your organization on the Alpha Sophia platform. Our customer support team can help you with this. The filter values are the territory IDs. This filter supports include and exclude.

    Example:

    ?territory=+cef69ab1-8b82-4b2b-a7e2-52ff3c3aa020

  • Name
    city
    Type
    string
    Description

    Filter by city. This filter will only return results for HCPs that are located in the specified city according to their NPPES data. The filter values are the Alpha Sophia ity IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?city=+3,+28,+42

  • Name
    state
    Type
    string
    Description

    Filter by US state. This filter will only return results for HCPs that are located in the specified state according to their NPPES data. The filter values are the USPS 2 digit state abbreviations. This filter supports include and exclude.

    Example:

    ?state=+NY,+CA,+TX

  • Name
    zip5
    Type
    string
    Description

    Filter by 5-digit ZIP code. This filter will only return results for HCPs that are located in the specified ZIP code according to their NPPES data. The filter values are the 5 digit ZIP codes. This filter supports include and exclude.

    Example:

    ?zip5=+90210,+90211

  • Name
    cbsa
    Type
    string
    Description

    Filter by Core Based Statistical Area (CBSA). This filter will only return results for HCPs that are located in the specified CBSA according to their NPPES data. The filter values are the CBSA codes. This filter supports include and exclude.

  • Name
    location-ruca
    Type
    string
    Description

    Filter by Rural-Urban Commuting Area (RUCA) code.

  • Name
    hco
    Type
    string
    Description

    Filter by Healthcare Organization (HCO).

  • Name
    soc
    Type
    string
    Description

    Filter by Standard Occupational Classification (SOC).

  • Name
    hco-primary
    Type
    string
    Description

    Filter by primary Healthcare Organization.

  • Name
    sole-proprietor
    Type
    string
    Description

    Filter by sole proprietor status.

  • Name
    diagnosis
    Type
    string
    Description

    Filter by CCSR diagnosis across All-Payors. This filter will only return results for HCPs that have made diagnosis within the specified CCSR code according to their Alpha Sophia All-Payor data. The filter values are the CCSR codes. This filter supports include and exclude.

    Example:

    ?diagnosis=+SKN001,+SKN002

  • Name
    procedure
    Type
    string
    Description

    Filter by Medicare part B procedure. This filter will only return results for HCPs that have performed the specified procedure according to their Medicare Part B data. The filter values are the CPT or HCPCS 2 codes. This filter supports include and exclude.

    Example:

    ?procedure=+27447,+27448

  • Name
    procedure-all-payor
    Type
    string
    Description

    Filter by procedure across All-Payors. This filter will return results for HCPs that have performed the specified procedure according to their Alpha Sophia All-Payor data, as well as other payors. The filter values are the CPT or HCPCS 2 codes. This filter supports include and exclude.

    Example:

    ?procedure-all-payor=+27447,+27448

  • Name
    prescription-brand
    Type
    string
    Description

    Filter by Medicare Part D prescription brand name. This filter will only return results for HCPs that have prescribed the specified prescription brand according to their Medicare Part D data. The filter values are brand names. This filter supports include and exclude.

    Example:

    ?prescription-brand=+TODO

  • Name
    prescription-generic
    Type
    string
    Description

    Filter by Medicare Part D generic brand name. This filter will only return results for HCPs that have prescribed the specified prescription generic according to their Medicare Part D data. The filter values are brand names. This filter supports include and exclude.

    Example:

    ?prescription-brand=+TODO

  • Name
    openpayments-manufacturer
    Type
    string
    Description

    Filter by OpenPayments manufacturer. This filter will only return results for HCPs who received payments from the specified manufacturers according to the Sunshine Act. The filter values are the Sunshine Act manufacturer IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?openpayments-manufacturer=+ TODO FILL OUT

  • Name
    openpayments-natures-of-payment
    Type
    string
    Description

    Filter by OpenPayments manufacturer. This filter will only return results for HCPs who received payments from the specified nature of payment category according to the Sunshine Act. The filter values are the Alpha Sophia nature of payments IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?openpayments-natures-of-payment=+ TODO FILL OUT

  • Name
    openpayments-product
    Type
    string
    Description

    Filter by OpenPayments product. The filter will only return results for HCPs who received payments for the specified product names according to the Sunshine Act data. The filter values are the product name values and need to be enclosed in quotes. This filter supports include and exclude.

    Example:

    ?openpayments-product=+“DAVINCI”,+“DA VINCI”

  • Name
    openpayments-amount
    Type
    string
    Description

    Filter by OpenPayments minimum amount. This filter will only return results for HCPs for which the total payments based on the other OpenPayments filters fall within the specified range. This filter supports a range, between a minimum or a maximum payment amount (or both).

    Example:

    ?openpayments-amount=30000-50000

    Example:

    ?openpayments-amount=30000

    Example:

    ?openpayments-amount=-500000

  • Name
    medschool
    Type
    string
    Description

    Filter by medical school / education. This filter will only return results for HCPs who have been educated at the specified medical school according to the Alpha Sophia database. The filter values are the Alpha Sophia medical school IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?medschool=+23,+24

  • Name
    seniority
    Type
    string
    Description

    Filter by seniority level (i.e. years since graduation). This filter will return HCPs who have a seniority level between the specified range. This filter supports a list of less than 5 years <5, between five and ten years 5-10, between ten and twenty years 10-20, or more than twenty years >20.

    Example:

    ?seniority=5-10,10-20

  • Name
    graduation-year
    Type
    string
    Description

    Filter by graduation year. This filter will return HCPs who graduated between the specified year range. This filter supports a range, between a minimum or a maximum year (or both).

    Example:

    ?graduation-year=2000-2010

    Example:

    ?graduation-year=2000-

    Example:

    ?graduation-year=-2012

  • Name
    primary-degree
    Type
    string
    Description

    Setting this to true will ensure that the medschool and other education filters are restricted to only the primary medical school degree (no fellowships etc.). By default, all education data points will be searched. Setting this to true will only use the primary degree data points.

    Example:

    ?primary-degree=true

  • Name
    fellowship
    Type
    string
    Description

    Setting this to true will ensure that the medschool and other education filters are restricted to only the fellowship data point (no primary degree etc.). By default, all education data points will be searched. Setting this to true will only use the fellowship data points.

    Example:

    ?fellowship=true

  • Name
    residency
    Type
    string
    Description

    Setting this to true will ensure that the medschool and other education filters are restricted to only the residency data point (no primary degree etc.). By default, all education data points will be searched. Setting this to true will only use the residency data points.

    Example:

    ?residency=true

  • Name
    publications
    Type
    string
    Description

    Return only results for HCPs that have published at least one publication according to the Alpha Sophia publications database. Setting this to true will return only results for HCPs that have published at least one publication.

    Example:

    ?publications=true

  • Name
    clinical-trials
    Type
    string
    Description

    Return only results for HCPs that have participated in at least one clinical trial according to the Alpha Sophia clinical trials database. Setting this to true will return only results for HCPs that have participated in at least one clinical trial.

    Example:

    ?clinical-trials=true

  • Name
    contact
    Type
    string
    Description

    Filter by contact information. Available values are: email (Email), phone (Phone).

    Example:

    ?contact=email,phone

  • Name
    social
    Type
    string
    Description

    Filter by social media presence. Available values are: twitter (Twitter / X), linkedin (LinkedIn), instagram (Instagram), doximity (Doximity), zocdoc (Zocdoc).

    Example:

    ?social=twitter,doximity

  • Name
    language
    Type
    string
    Description

    Filter by additional languages. This filter will return results for HCPs that speak the specified language (not English). The filter values are the Alpha Sophia language IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?language=+6,+7

  • Name
    foreign-language
    Type
    string
    Description

    Setting this to true will return results for HCPs that speak a language other than English.

    Example:

    ?foreign-language=true

  • Name
    female
    Type
    string
    Description

    Filter results by female gender. Setting this to true will return only HCPs identified as female.

    Example:

    ?female=true

  • Name
    male
    Type
    string
    Description

    Filter results by male gender. Setting this to true will return only HCPs identified as male.

    Example:

    ?male=true

  • Name
    gender-unspecified
    Type
    string
    Description

    Filter results by unspecified gender. Setting this to true will return only HCPs with unspecified gender.

    Example:

    ?gender-unspecified=true

  • Name
    telehealth
    Type
    string
    Description

    Filter by telehealth availability. Setting this to true will return only HCPs that offer telehealth services.

    Example:

    ?telehealth=true

  • Name
    society
    Type
    string
    Description

    Filter by medical society membership (e.g. medical associations, boards, societies). This filter will only return results for HCPs who are members of that society according to the Alpha Sophia database. The filter values are the Alpha Sophia medical society IDs that you can find using the search filter endpoint đź”— . This filter supports include and exclude.

    Example:

    ?society=+13,+27

  • Name
    leadlist
    Type
    string
    Description

    Filter by a specific lead list already defined by your organization on the Alpha Sophia platform. Our customer support team can help you with this. The filter values are the lead list IDs. This filter supports include and exclude.

    Example:

    ?leadlist=+cef69ab1-8b82-4b2b-a7e2-52ff3c3aa020

  • Name
    crm
    Type
    string
    Description

    This filter allows you to filter HCPs based on their lead list status. You can choose HCPs which have notes in Alpha Sophia has-notes, which are on any lead list is-lead or which are not on any lead list not-lead.

    Example:

    ?crm=has-notes,is-lead,not-lead

Request
GET
•
/v1/search/hcp
curl \
  -G "https://api.alphasophia.com/v1/search/hcp" \
  -d "order-by=ap-volume" \
  -d "time=last-year" \
  -d "procedure-all-payor=+27447" \
  -d "state=+NY" \
  -d "taxonomy=+207X00000X" \
  -H "x-request-api: alphasophia_your_api_key" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "data": [{
    "id": "1234567890",
    "npi": "1234567890",
    "name": "John Doe",
    "profilePicture": "https://cdn.example.com/profile/1234567890.jpg",
    "taxonomy": {
      "code": "207Q00000X",
      "description": "Family Medicine",
      "count": 1
    },
    "kpi": 15321,
    "location": {
      "city": "New York",
      "state": "NY"
    },
    "affiliation": {
      "name": "General Hospital",
      "count": 2,
      "isSoleProprietor": false
    },
    "contact": {
      "email": [
        "john.doe@generalhospital.org"
      ],
      "phone": [
        "1234567890",
        "1234567890"
      ],
      "linkedin": null,
      "twitter": null,
      "doximity": [
        "https://www.doximity.com/pub/john-doe-md"
      ]
    },
    "licensure": [
      "CT",
      "NJ",
      "NY"
    ],
  }],

}
Search Filters

This endpoint allows you to retrieve the correct IDs for more complex search filters. You can send a text query against the endpoint for a specific filter (with the same IDs as in the Search HCP above), and will get paginated suggestions for the filter. You can then use these IDs in the Search HCP endpoint to filter the results.



Query parameters
  • Name
    query
    Type
    string
    Description

    The query string to search for (e.g. “dermatologist”, “harvard”, “new york”).

  • Name
    page
    Type
    string
    Description

    The page number to return. Defaults to 1. By default, 10 items are returned.

  • Name
    filter
    Type
    string
    Description

    The filter to search for (e.g. “speciality”, “medical-school”, “state”). This corresponds to the name of the filter in Search HCP (e.g. “procedure”).

Request
GET
•
/v1/search/filter
curl \
  -G "https://api.alphasophia.com/v1/search/filter" \
  -d "query=dermatology" \
  -d "filter=classification" \
  -d "page=1" \
  -H "x-request-api: alphasophia_your_api_key" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "data": [{
    "id": 2,
    "name": "Dermatology"
  }]
}
Copyright © 2025 Alpha Sophia Technologies GmbH. All rights reserved. Alpha Sophia® is Registered in the U.S. Patent Office and/or other countries.