---
title: "Batch match dimension points to rates"
method: POST
path: "/api/fee-schedules/v3/batch-match"
tags: ["v3"]
---

# Batch match dimension points to rates

`POST /api/fee-schedules/v3/batch-match`

## Request

- Base URL: `https://pre-api.joincandidhealth.com`
- URL: `https://pre-api.joincandidhealth.com/api/fee-schedules/v3/batch-match`
- Auth: HTTP bearer

Gets the rate that matches each of a list of dimension points, using the same matching as the service line match endpoint.
Useful for showing rates before a service line exists in Candid.

Results are returned in request order, one per point. A point with no matching rate has a null `match`.

An omitted optional dimension only matches rates that have no restriction on that dimension. CPT codes are matched
case-insensitively, and ZIP codes are matched on their first 5 digits.

## Request body

- FeeSchedulesV3BatchMatchPoint[]
  - `payer_uuid` string, uuid, required
  - `organization_billing_provider_id` string, uuid, required
  - `cpt_code` string, required: Matched case-insensitively.
  - `date_of_service` string, date, required: The rate entry in effect on this date is used.
  - `modifiers` CommonsProcedureModifier[]: Defaults to no modifiers.
  - `facility_type_code` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '31' | '32' | '33' | '34' | '41' | '42' | '49' | '50' | '51' | '52' | '53' | '54' | '55' | '56' | '57' | '58' | '60' | '61' | '62' | '65' | '71' | '72' | '81' | '99': Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here: https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set
  - `state` 'AA' | 'AE' | 'AP' | 'AL' | 'AK' | 'AS' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DC' | 'DE' | 'FL' | 'FM' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MH' | 'MI' | 'MN' | 'MP' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'PW' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VI' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'FC'
  - `zip_code` string: Only the first 5 digits are used, so ZIP+4 values are accepted.
  - `license_type` 'MD' | 'NP' | 'PA' | 'LMFT' | 'LCPC' | 'LCSW' | 'PMHNP' | 'FNP' | 'LPCC' | 'DO' | 'RD' | 'SLP' | 'APRN' | 'LPC' | 'PHD' | 'PSYD' | 'LMSW' | 'LMHC' | 'OTHER_MASTERS' | 'BCBA' | 'UNKNOWN' | 'RPH' | 'PHT' | 'LAC' | 'LMT' | 'DC' | 'ND' | 'MA' | 'PT' | 'IBCLC' | 'RN' | 'DPT' | 'LCMHC' | 'CNM' | 'RNFA' | 'ACSW' | 'APC' | 'BCABA' | 'BHA' | 'OD' | 'DPM' | 'DA' | 'DDS' | 'DEH' | 'DMD' | 'PTA' | 'LCADC' | 'LCAT' | 'LCMHCS' | 'LCMHCA' | 'LCSWA' | 'LICSW' | 'LISW' | 'LMFTS' | 'LMFTA' | 'LPCI' | 'LSCSW' | 'MHCA' | 'MHT' | 'RBT' | 'RCSWI' | 'RHMCI' | 'LPN' | 'OTD' | 'OMS' | 'MFTA' | 'APCC' | 'DNP' | 'AGNPBC' | 'ANP' | 'FNPPP' | 'LCSWR' | 'ALC' | 'RMFTI' | 'LAMFT' | 'LPCA' | 'LSWI' | 'CSW' | 'CPC' | 'LGMFT' | 'LLPC' | 'PLPC' | 'PLMFT' | 'LMHCA' | 'CIT' | 'CT' | 'MFT' | 'LSW' | 'PLMHP' | 'PCMSW' | 'LMHP' | 'OTR/L' | 'RPA' | 'COTA' | 'CRNP' | 'SLP-CF' | 'NP-C' | 'PA-C' | 'AMFT' | 'CDN' | 'CGC' | 'CNS' | 'MDPHD' | 'AuD' | 'ATC' | 'LAT' | 'OTA' | 'LSSP' | 'SLPA' | 'EdD' | 'SWT' | 'IMFT' | 'RT'
  - `network_types` CommonsNetworkType[]
  - `payer_plan_group_id` string, uuid
  - `quantity` string: String representation of a Decimal that can be parsed by most libraries.

## Response `200`

Response with status 200

- FeeSchedulesV3BatchMatchResult[]
  - `point` FeeSchedulesV3BatchMatchPoint, required: The dimension values to match a rate against, equivalent to a service line. An omitted optional dimension only matches rates that have no restriction on that dimension.
    - `payer_uuid` string, uuid, required
    - `organization_billing_provider_id` string, uuid, required
    - `cpt_code` string, required: Matched case-insensitively.
    - `date_of_service` string, date, required: The rate entry in effect on this date is used.
    - `modifiers` CommonsProcedureModifier[]: Defaults to no modifiers.
    - `facility_type_code` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '31' | '32' | '33' | '34' | '41' | '42' | '49' | '50' | '51' | '52' | '53' | '54' | '55' | '56' | '57' | '58' | '60' | '61' | '62' | '65' | '71' | '72' | '81' | '99': Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here: https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set
    - `state` 'AA' | 'AE' | 'AP' | 'AL' | 'AK' | 'AS' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DC' | 'DE' | 'FL' | 'FM' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MH' | 'MI' | 'MN' | 'MP' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'PW' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VI' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'FC'
    - `zip_code` string: Only the first 5 digits are used, so ZIP+4 values are accepted.
    - `license_type` 'MD' | 'NP' | 'PA' | 'LMFT' | 'LCPC' | 'LCSW' | 'PMHNP' | 'FNP' | 'LPCC' | 'DO' | 'RD' | 'SLP' | 'APRN' | 'LPC' | 'PHD' | 'PSYD' | 'LMSW' | 'LMHC' | 'OTHER_MASTERS' | 'BCBA' | 'UNKNOWN' | 'RPH' | 'PHT' | 'LAC' | 'LMT' | 'DC' | 'ND' | 'MA' | 'PT' | 'IBCLC' | 'RN' | 'DPT' | 'LCMHC' | 'CNM' | 'RNFA' | 'ACSW' | 'APC' | 'BCABA' | 'BHA' | 'OD' | 'DPM' | 'DA' | 'DDS' | 'DEH' | 'DMD' | 'PTA' | 'LCADC' | 'LCAT' | 'LCMHCS' | 'LCMHCA' | 'LCSWA' | 'LICSW' | 'LISW' | 'LMFTS' | 'LMFTA' | 'LPCI' | 'LSCSW' | 'MHCA' | 'MHT' | 'RBT' | 'RCSWI' | 'RHMCI' | 'LPN' | 'OTD' | 'OMS' | 'MFTA' | 'APCC' | 'DNP' | 'AGNPBC' | 'ANP' | 'FNPPP' | 'LCSWR' | 'ALC' | 'RMFTI' | 'LAMFT' | 'LPCA' | 'LSWI' | 'CSW' | 'CPC' | 'LGMFT' | 'LLPC' | 'PLPC' | 'PLMFT' | 'LMHCA' | 'CIT' | 'CT' | 'MFT' | 'LSW' | 'PLMHP' | 'PCMSW' | 'LMHP' | 'OTR/L' | 'RPA' | 'COTA' | 'CRNP' | 'SLP-CF' | 'NP-C' | 'PA-C' | 'AMFT' | 'CDN' | 'CGC' | 'CNS' | 'MDPHD' | 'AuD' | 'ATC' | 'LAT' | 'OTA' | 'LSSP' | 'SLPA' | 'EdD' | 'SWT' | 'IMFT' | 'RT'
    - `network_types` CommonsNetworkType[]
    - `payer_plan_group_id` string, uuid
    - `quantity` string: String representation of a Decimal that can be parsed by most libraries.
  - `match` FeeSchedulesV3MatchedRate: A rate that matched a dimension point, with the entry in effect on the point's date of service.
    - `rate_id` string, uuid, required
    - `dimensions` FeeSchedulesV3Dimensions, required: Dimension values that qualify a rate. For the optional dimensions, a null value signifies "all apply". For set-type dimensions, an empty set signifies "all apply". Only one of, but not both, of `network_types` and `payer_plan_group_id` may be populated.
      - `payer_uuid` string, uuid, required
      - `organization_billing_provider_id` string, uuid, required
      - `states` CommonsState[], required
      - `zip_codes` string[], required
      - `license_types` OrganizationProvidersV2LicenseType[], required
      - `facility_type_codes` CommonsFacilityTypeCode[], required
      - `network_types` CommonsNetworkType[], required
      - `payer_plan_group_ids` CommonsPayerPlanGroupId[], required
      - `cpt_code` string, required
      - `modifiers` CommonsProcedureModifier[], required
    - `version` integer, required: The version of this rate in the system.
    - `updated_at` string, date, required
    - `updated_by` string, uuid, required
    - `entries` FeeSchedulesV3RateEntry[], required
      - `start_date` string, date, required
      - `end_date` string, date
      - `rate_cents` integer, required
      - `is_deactivated` boolean, required
    - `matched_entry` FeeSchedulesV3RateEntry, required: A rate value in cents for a specific time range. Rate entries can be deactivated, which is set by using the delete_rate endpoint. Deactivated rate entries are not considered when matching against service lines.
      - `start_date` string, date, required
      - `end_date` string, date
      - `rate_cents` integer, required
      - `is_deactivated` boolean, required
    - `total_cents` integer, required: The matched entry's rate_cents multiplied by the point's quantity, rounded to the nearest cent (half to even).

## Changes

- **2026-10-15** `97de8fddb088`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/joincandidhealth/apis/api-reference/changes/api/fee-schedules/v3/batch-match/post.md)

---

[API](https://skmtc.dev/joincandidhealth/apis/api-reference.md) - [All operations](https://skmtc.dev/joincandidhealth/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/joincandidhealth/apis/api-reference/revisions/d8b0a61873e2?raw)