Payer Finder FAQs



Please see the Optum API FAQs section for tips and solutions to some of the most common questions asked by customers, developer community, and internal staff about the use of our APIs.



See the API Examples section on the left panel in the developer portal.

What is Payer Finder v1 API?

Developers can use Payer Finder v1 API to programmatically search for the right payer in each transaction. It is a complete re-write of Trading Partner v7 API with a new database supporting a better data model resulting in increased accuracy. Furthermore, a server-less infrastructure that delivers better performance.



Works with NPD (also internally known as Legacy Change Healthcare, Emdeon, or Ark) payer list and Revenue Performance Advisor (RPA)/Capario (known internally as RPA or Capario) that are now in the Payer Profile Database.



The Trading Partner v7 API is no longer supported. The Trading Partner v7 API requests will not work from August 15, 2023. You should update any code that uses it, to use Payer Finder v1 API. We strongly encourage you to make the transition to Payer Finder API as soon as possible, as it is more accurate and more robust.

How can I access the Payer Finder APIs?

Payer Finder APIs allow you to retrieve individual Payer information, including any or all services offered by that Payer.

  • Use GET /payerfinder/v1/payers request to query our Payer Performance Database to obtain more specific information.
  • Use the GET request to build a query and filter for subsets of Payer Finder information from the payer list.


The API paths are the requests you send to the API engine to perform lookup tasks to the database. See the API Examples section on the left panel in the developer portal.

For more information, see Payer Finder APIs.

What information needs to be included in the API request header?

Use this header information for these eligibility operations unless otherwise noted: Eligibility, Eligibility EDI, and Eligibility Views. We use two standard HTTP headers in our API requests: Authorization and Content-Type.

The API request uses the following header format:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>
  • Content-Type header always defaults to application/json
  • Bearer authorization token in the Authorization header
    Get an authorization token by making a request Generate authorization token.

What does typical Payer Finder API request look like?

The Payer Finder API provides two methods for querying payers:

  • Queries using the HTTP URL path;
  • Queries defined by a question mark (?) followed by a structured statement as an extended argument in the path.



In general, API queries are not case sensitive. However, the key portions of a key-value pair search parameters are case-sensitive while the value portions are not. The key (a field name)) should be in camel case as while the value can be entered anyway. So, for example, serviceName=eligibility or serviceName=ELIGIBILITY both work while servicename=eligibility does not.

Sending the following request downloads the entire payer list. From this point, add the attributes and arguments to the URL path to query for more-specific information.

What does a typical Payer Finder v1 API response look like?

In a sandbox environment, if you want to query for payers that start with business name blue and service name Claims, send a GET request to the following endpoint with your authorization header.


    "start": 0,
    "size": 50,
    "total": 542,
    "payers": [
            "businessName": "Blue Cross Blue Shield of Testing",
            "alias": "Test Alias",
            "planType": "Test",
            "serviceName": "Claims",
            "lineOfBusiness": "Dental",
            "serviceDate": "2007-10-19T00:00:00",
            "serviceId": "61474",
            "clearingHouse": "NPD",
            "acceptsSecondary": "N",
            "reportLevel": "4-Clm Level A/R",
            "serviceModified": "2007-11-01T00:00:00",
            "enrollmentStatus": "No Enrollment Required",
            "serviceNotes1": "Dental Blue Select Product",
            "passThroughFee": "N"
            "businessName": "Blue Cross Blue Shield of Testing 2",
            "planType": "Test 2 Alias",
            "states": "MS",
            "serviceName": "Claims",
            "lineOfBusiness": "Hospital",
            "serviceDate": "2002-04-12T00:00:00",
            "serviceId": "12B82",
            "clearingHouse": "NPD",
            "acceptsSecondary": "Y",
            "reportLevel": "4-Clm Level A/R",
            "serviceModified": "2012-03-23T00:00:00",
            "enrollmentStatus": "Enrollment Required",
            "enrollmentType": "Registration",
            "enrollmentMethod": "OKC/POSI Setup",
            "passThroughFee": "N"

Which data fields/JSON attributes can I use in the Payer Finder API for searching?

You can search using any of these query parameters.

You can string together multiple values for the same parameter.

  • Create an OR clause to return the records with a Claims or Eligibility service name:
  • Sort using the field name and asc or desc separated by a comma (,) symbol assigned to the sort parameter:
  • Control how many records and which to start from, using the size and start parameters:

This query returns 25 records having businesName with aetna starting with record number 50.

Which data fields/JSON elements are returned by a Payer Finder API search?

The Payer Finder API returns a list of payers with these data fields/JSON elements.

What are the Payer Finder API error types and their format?

If you are searching to see if a particular service is supported by a payer, and you do not specify the serviceName argument in the correct case, you will get a Nothing Found error:

   [ ]

Querying for a value using the serviceId or with any other supported attribute that does not match anything in the database, will yield the same result.

Can I get the .csv of the Eligibility Payer Guide comprising the Payer Name, Payer ID, and X12 requirements?

Yes, you can export the payers to .csv file.

Where can I get a list has the more universal payer ID that I am looking for?

You can find the payer list here: NPD or RPA/Capario payer list.

How I can make payer list more user friendly, I want to show it like the Change Healthcare has?

You can take the payer list (download it as a CSV file) and use it. For more information, see Payer Finder. Otherwise, you are limited to the the ConnectCenter view.

Do your APIs send the payer actual allowable amount for the claimed services in any variable, kindly tell the name of that variable (if any)?

The payer's actual allowable amount would come through in the 835 file from the payer. This is the payment file when the claim has been completely processed.

How to download the payer list to a .csv file?

  1. Go to NPD or RPA/Capario payer list.



If you do not provide /npd or /cap option, it defaults to /npd.

  1. Enter the payer name in the text box and click Enter.
  2. Click Export.
    The CSV file for the selected payer name downloads.

How can I look up the Provider NPI, Trading Partner Service ID? The API expects these values?

  • Control Number: 000000001 — is set by you, this is a unique number that follows the transaction from start to finish
  • Trading Partner Service ID: serviceId — is a payer ID, review a payer list: RPA/Capario or NPD.
  • Provider organization name: happy_doctors_group and Provider npi: 0123456789 — Provided by you. For example, if you are checking eligibility for a patient, what physician or facility is the patient seeing or going to or who did they see if you are checking post visit. You need that to check eligibility.
    Use the Payer Finder API to view the payer list.

How can payers be mapped from one EMR to another?

The main method of mapping payer information would be a manual effort by using the ConnectCenter Payer List. We recently launched our Payer Finder v1 API, which allows you to search and filter through our entire clearinghouse. It is a read-only API service that you can use without any financial obligations to query for information in our payer database for key pieces of information. Please review our clearinghouse endpoint, v1/payers/fields/clearinghouses and evaluate your enrollment with Optum, and understand which payer list you need to filter by, to avoid mix and matching of our payer list data and to avoid errors when using the payer data in other application to submit eligibility, claims, claim status, and other transactions. A complete list of the API URLs associated with your account can be found here.

How to download payer list that includes the required address/city/state information of the payers in the ConnectCenter?

Our transactions route based on the electronic ID submitted on the transaction, and hence we do not store or maintain payer address records on our end. Please work with the payers directly to confirm their physical address information.

Payer list does not include payer address?

Our transactions route based on the electronic ID submitted on the transaction, and hence we do not store or maintain payer address records at our end. Please work with the payers directly to confirm their physical address information. This information is stated here on our dev portal.

In regards to eligibility requests, is there a way to use a payer ID that searches an entire company (i.e. Blue Cross)? Blue Cross has many subsidiaries, all with different eligibility IDs, and patients will regularly list Blue Cross Blue Shield as their insurer. I want to know if there is a way to send an eligibility request with that information without know if its specifically Texas Blue Cross or California Blue Cross, etc.

Blue Cross Blue Shield functions differently than other payers; it has the blue exchange. Provider's are able to send their Eligibility request to there local blue, and the exchange will return the insured policy. This would mean that the state the provider themselves is located in, should be the blue ID that you are sending to, regardless of the policy of the actual member.

If I (the provider) am located in California and someone has Texas Blue Cross, i could still send the CABC eligibility ID? Will the response note that they actually have Texas Blue Cross or will it return California Blue Cross?

You are correct, if you (the provider) are located in California and someone has Texas Blue Cross, you could still send the CABC eligibility ID. The response would come back with the payer the request was sent to. The case listed above would be returned with California.

Related Topics