Whether you are a startup or multi-office DSO, learn how Onederful APIs enable modern RESTful connections into dental insurances companies without having to have prior knowledge of integrating with EDI, faxbacks, SFTP, etc.
Once your credentials are set up, within minutes, you'll be able to send eligibility and benefit queries to submitting claims right within your own application.
Onederful APIs are built on top of Aptible and AWS and are built for scale while also providing first class security for all data flowing through.
Our APIs utilize HTTPS and encrypt all data traffic in transit and at rest.
Authentication (OAuth2 )
In order to ping any of the Onederful APIs, you must get a JWT to pass in the header of every request.
The following request shows how the OAuth2 flow works to use your CUSTOMER_CLIENT_ID and CUSTOMER_CLIENT_SECRET to get a JWT.
To authorize, use this code and make sure to replace <CUSTOMER_CLIENT_ID> and <CUSTOMER_CLIENT_SECRET> with your keys:
# With shell, you can just pass the correct header with each request
curl -X POST https://production.onederful.co/oauth2/token \
-H 'content-type: application/json'\
-d '{
"client_id":"<CUSTOMER_CLIENT_ID>",
"client_secret":"<CUSTOMER_CLIENT_SECRET>"
}'
(EXAMPLE RESPONSE) The above command returns JSON structured like this:
The dependent (if any) of the benefits you are requesting. Typically, the dependent member id is the same as the subscriber member id. When requesting for a dependent, you do not have to include the subscriber object (i.e. subscriber is not required to query for a dependent).
Extra filtering parameters when querying for eligibility and benefits
procedure_codes
false
[String]
Example: ["D0120", "D8080"]. Currently, only Aetna and certain Delta Dental states (like CA) allow for specific procedure code lookup. Can look up to at most 10 procedure codes at a time.
Patient Request Schema
Parameter
Required
Description
first_name
true
First name of the patient
last_name
true
Last name of the patient
dob
true
Date of birth of the patient. Format must be in (MM/DD/YYYY) where MM = month, DD = day, YYYY = year.
member_id
true
Member ID of the patient (can also be the SSN of the patient, however, many insurances are moving away from SSN towards member IDs).
group_number
false
Group number of the plan you are searching for. Some insurances require this parameter in order to filter down to the correct patient. As such, if you have this data on hand, please include in the request as all insurances will take this parameter.
Provider Request Schema
Parameter
Required
Description
npi
true
10-digit Provider National Provider Identifier (NPI). Can utilize the public NPI registry lookup tool to make sure you are passing a valid NPI.
tax_id
true
Tax ID
Payer Request Schema
Parameter
Required
Description
id
true
Onederful payer ID. The payer ID must match exactly to one on the Payer List
The default is dental for generic dental eligibility and benefits. For specific benefits like orthodontics, you can use the orthodontics value. Note: some payers will ignore this parameter as this functionality is not built into their system.
Response Eligibility and Benefits
(EXAMPLE RESPONSE) Response from insurance (note: data has been abbreviated for length)
{"patient":{"name":"JOHN DOE","first_name":"JOHN","last_name":"DOE","dob":"02/15/2011","member_id":"123456789","address":{"street1":"123 CALIFORNIA ST","city":"SAN FRANCISCO","zip":"94101","state":"CA"},"coverage":{"effective_date":"01/01/2020","status":"active"}},"subscriber":{"name":"JOHN DOE","first_name":"JOHN","last_name":"DOE","dob":"02/15/2011","member_id":"123456789","address":{"street1":"123 CALIFORNIA ST","city":"SAN FRANCISCO","zip":"94101","state":"CA"},"coverage":{"effective_date":"01/01/2020","status":"active"}},"plan":{"name":"ACME INC.","number":"1234567","type":"PRINCIPAL POS","group_number":"12345","state":"CA"},"deductible":[{"network":"in_network","category":"preventive","plan_period":"calendar","amount":"0.00","coverage_level":"individual"},{"network":"in_network","category":"basic_and_major","plan_period":"calendar","amount":"50.00","coverage_level":"individual"},{"network":"in_network","category":"preventive","plan_period":"remaining","amount":"0.00","coverage_level":"individual"},{"network":"in_network","category":"basic_and_major","plan_period":"remaining","amount":"26.00","coverage_level":"individual"},{"network":"in_network","category":"preventive","plan_period":"calendar","amount":"0.00","coverage_level":"family"},...],"maximums":[{"network":"in_network","category":"preventive_basic_and_major","plan_period":"calendar","amount":"1500.00"},{"network":"in_network","category":"preventive_basic_and_major","plan_period":"remaining","amount":"1470.00"},{"network":"out_of_network","category":"preventive_basic_and_major","plan_period":"calendar","amount":"1500.00"},{"network":"out_of_network","category":"preventive_basic_and_major","plan_period":"remaining","amount":"1470.00"},...],"coinsurance":[{"network":"in_network","category":"preventive","plan_period":"calendar","percent":"100"},{"network":"in_network","category":"basic","plan_period":"calendar","percent":"80"},{"network":"in_network","category":"major","plan_period":"calendar","percent":"50"},{"network":"in_network","category":"orthodontics","plan_period":"calendar","percent":"50"},{"network":"out_of_network","category":"preventive","plan_period":"calendar","percent":"80"},{"network":"out_of_network","category":"basic","plan_period":"calendar","percent":"40"},{"network":"out_of_network","category":"major","plan_period":"calendar","percent":"20"},{"network":"out_of_network","category":"orthodontics","plan_period":"calendar","percent":"50"},...],"limitations":[{"category":"preventive","service_type":"examinations","limitation":"2 per calendar year","limitation_applies_to":["D0120","D0145","D0150","D0160","D0170","D0180","D9430"],"service_dates":[{"procedure_code":"D0120","service_date":"02/15/2020"},{"procedure_code":"D0150","service_date":"02/15/2014"},{"procedure_code":"D0150","service_date":"02/15/2019"}],"services_remaining":1},{"category":"preventive","service_type":"limited_examinations","limitation":"2 per calendar year","limitation_applies_to":["D0140"],"service_dates":[{"procedure_code":"D0120","service_date":"02/15/2020"},{"procedure_code":"D0150","service_date":"02/15/2014"},{"procedure_code":"D0150","service_date":"02/15/2019"}],"services_remaining":1,"disclaimers":["Limited oral evaluation is considered with or without other procedures on same date of service."]},{"category":"preventive","service_type":"full_mouth","limitation":"1 per 60 consecutive months to the exact day","limitation_applies_to":["D0210","D0330"],"services_remaining":1},{"category":"preventive","service_type":"periapicals","limitation":"4 per calendar year","limitation_applies_to":["D0220","D0230"],"service_dates":[{"procedure_code":"D0210","service_date":"02/15/2019"},{"procedure_code":"D0220","service_date":"02/15/2019"},{"procedure_code":"D0230","service_date":"02/15/2019"}],"services_remaining":4},{"category":"preventive","service_type":"bitewings","limitation":"1 per calendar year","limitation_applies_to":["D0270","D0272","D0273","D0274","D0277"],"service_dates":[{"procedure_code":"D0210","service_date":"02/15/2019"},{"procedure_code":"D0272","service_date":"02/16/2020"}],"services_remaining":0},{"category":"preventive","service_type":"prophylaxis","limitation":"2 per calendar year","limitation_applies_to":["D1110","D1120"],"service_dates":[{"procedure_code":"D1110","service_date":"02/15/2019"}],"services_remaining":2,"disclaimers":["Not covered if less than 90 days have passed since active periodontal therapy was completed.","If under age 14, benefit limited to child prophylaxis (D1120)"]},{"category":"preventive","service_type":"periodontal_maintenance","limitation":"2 per calendar year","limitation_applies_to":["D4910"],"service_dates":[{"procedure_code":"D1110","service_date":"02/15/2019"}],"services_remaining":2,"disclaimers":["This procedure is only covered by us if at least 90 days have passed since the active periodontal therapy was completed."]},{"category":"preventive","service_type":"fluoride","limitation":"1 per calendar year","limitation_applies_to":["D1208","D1206"],"services_remaining":1,"disclaimers":["Covered for dependent children and adults. No age limitation."]},{"category":"preventive","service_type":"sealants","limitation":"1 per 36 consecutive months to the exact day","limitation_applies_to":["D1351","D1352","D1353"],"services_remaining":0,"disclaimers":["Covered for dependent children and adults. No age limitation.","Applicable only to the occlusal surface of first and second permanent molars."]},{"category":"basic","service_type":"space_maintainers","limitation":"Covered once per site per lifetime","limitation_applies_to":["D1510","D1520","D1526","D1527","D1575","D1516","D1517"],"services_remaining":0,"disclaimers":["Covered for dependent children and adults. No age limitation."]},{"category":"basic","service_type":"fillings","limitation":"1 replacement every 24 months to the exact day","limitation_applies_to":["D2330","D2331","D2332","D2335","D2140","D2150","D2160","D2161","D2390","D2391","D2392","D2393","D2394"],"services_remaining":0,"disclaimers":["Composites are considered at an amalgam rate for posterior teeth which includes molars and pre-molars (bicuspids).","Restorations replacing tooth structure lost from abrasion, attrition, abfraction and erosion are not covered.","These services are subject to Individual and/or Consultant review. See Submission Guidelines here: https://secure02.principal.com/publicvsupply/GetFile?fm=GP58750A&ty=PDF&EXT=.PDF"]},{"category":"major","service_type":"crowns_and_onlays","limitation":"120 month replacement","limitation_applies_to":["D2710","D2712","D2720","D2721","D2722","D2740","D2750","D2751","D2752","D2780","D2781","D2782","D2783","D2790","D2791","D2792","D2794","D2542","D2543","D2544","D2642","D2643","D2644","D2662","D2663","D2664","D2753"],"services_remaining":0,"disclaimers":["These services are subject to Individual and/or Consultant review. See Submission Guidelines here: https://secure02.principal.com/publicvsupply/GetFile?fm=GP58750A&ty=PDF&EXT=.PDF","Covered services are paid on seat date","Molars/Pre-molars are based upon the alternate benefit of a noble metal cast crown. Anterior teeth are based upon the alternate benefit of a porcelain fused to noble metal cast crown.","These codes are covered services only if placed to restore a tooth broken down due to tooth decay or injury resulting in the loss of tooth structure. (Injury does not include damage to teeth that results from chewing or biting food, substances or objects)."]},{"category":"basic","service_type":"stainless_steel_crowns","limitation":"120 month replacement","limitation_applies_to":["D2929","D2930","D2931","D2932","D2933","D2934"],"services_remaining":0,"disclaimers":["Crowns replacing tooth structure lost from abrasion, attrition, abfraction and erosion are not covered.","If used as a temporary, not covered","If a permanent crown replaces a stainless steel/resin/prefabricated crown at a later date but before replacement restrictions allow, all new charges will be reduced by those already paid."]},{"category":"major","service_type":"crown_recements","limitation":"1 per 24 consecutive months to the exact day","limitation_applies_to":["D2920"],"services_remaining":0,"disclaimers":["Covered only if done more than 12 months after initial insertion of crown/onlay"]},{"category":"major","service_type":"buildups","limitation":"120 month replacement","limitation_applies_to":["D2950"],"services_remaining":0,"disclaimers":["These services are subject to Individual and/or Consultant review. See Submission Guidelines here: https://secure02.principal.com/publicvsupply/GetFile?fm=GP58750A&ty=PDF&EXT=.PDF","Considered only when required for retention and preservation of tooth. No benefits payable if restorative procedures are not covered."]},{"category":"basic","service_type":"pulpotomy","limitation":"Covered once per site per lifetime","limitation_applies_to":["D3220"],"services_remaining":0,"disclaimers":["Not to be construed as the first stage of root canal therapy."]},{"category":"basic","service_type":"simple_endodontic_therapy","limitation":"Covered once per site per lifetime","limitation_applies_to":["D3310","D3320"],"services_remaining":0,"disclaimers":["Includes intra-operative x-rays."]},{"category":"basic","service_type":"complex_endodontic_therapy","limitation":"Covered once per site per lifetime","limitation_applies_to":["D3330"],"service_dates":[{"procedure_code":"D3330","service_date":"02/15/2014","tooth_code":"14"}],"services_remaining":0,"disclaimers":["Includes intra-operative x-rays."]},...],"disclaimers":["A missing tooth clause applies to services such as the initial placement of full or partial dentures, fixed bridges, implants, and implant crowns. These services are only covered if the natural teeth being replaced were extracted while covered under this plan.","The patient should see a Principal Point of Service (POS) EPO dentist for the best benefit. Lesser benefits are available by visiting a Principal POS PPO or a non-participating dentist. A different fee schedule may apply according to leased agreements. Benefits for non-participating Dentists are subject to Usual, Customary and Reasonable Fees (UCR). Call 800-832-4450 to check participation. ","Orthodontic treatment is covered only if the bands/appliances were placed prior to age 19."...],"onederfulId":"1b2cdfr1-341x-25exb-ad15-454d513456af","api_count":1}
Response Schema
Parameter
Type
Description
onederfulId
String
Unique UUID passed back by Onederful in every response. You can just pass the onederfulId when emailing support@onederful.co for any questions about a specific transaction.
The patient that was searched on (i.e. if subscriber was the primary search, the patient will be the subscriber, if the dependent was primary search, the patient will be the dependent). You can use this as primary object of knowing who the benefits relate to as well as the coverage status (i.e. active/inactive).
List of benefit data about deductibles. In dental, deductibles are amount a patient must pay for certain covered services before insurance starts paying.
List of benefit data about maximums. In dental, maximums are the total amount that insurance will pay for dental coverage. Once a patient hits the maximum, all expenses must be paid out of pocket (insurance will not cover any more expenses).
List of benefit data about coinsurance. In dental, coinsurances are the percentage insurance will cover for a procedure (i.e. D0120, D8080, etc.) / category (i.e. basic, major, etc.).
List of benefit data about waiting period. In dental, waiting periods are the period of time a patient must be enrolled in a plan before they are eligible for benefits.
List of benefit data about limitations. In dental, limitations are descriptions about time or frequency (i.e. no more than 2 cleanings in 12 months) for certain procedures. As dental plans typically don't cover every dental procedure, each plan has a list of conditions that limit or exclude services from coverage.
List of benefit data about not covered benefits. In dental, not covered means procedures/categories in this section are not covered by insurance (i.e. insurance will not pay out for these procedures/categories).
List of benefit data that is specific for a payer. This section is an area where insurances may place unstructured data into. The long term goal for Onederful is to normalize this section out to remove this section entirely. If you see this section in any payer and would like Onederful to normalize it into the rest of the schema, please email support@onederful.co with the onederfulId of the transaction.
List of benefit data about copayment. In dental, copayment is the fixed dollar amount a patient will pay for a covered service. Typically this is only relevant for HMO plans, where a patient is attached to a HMO provider.
List of benefit data about out of pocket info. In dental, out of pocket data relates to amount patient must pay out of pocket for certain procedures/categories (this section is rarely sent).
disclaimers
[String]
Free text section insurance companies will include disclaimers such as Missing Tooth Clause, UCR, specific info about the plan, etc. There is no universal dictionary for this section as each insurance has their own lexicon for disclaimers and as such is a free text section.
payer_uuid
String
Payer specific UUID (if any) that gets attached to the response.
Benefit Response Schema
Parameter
Type
Description
network
String
The network related to this benefit. Typical values are: in_network, out_of_network, epo, unkown, applies_all. Certain insurance companies may put free text values here. Refer here for a more detailed list.
category
String
Category of service (if any). Typical values are: basic, orthodontics, etc. Certain insurance companies may put free text values here. Refer here for a more detailed list.
insurance_type
String
Type of insurance coverage. Typical values are: group_policy, hmo, etc. Certain insurance companies may put free text values here. Refer here for a more detailed list.
service_type
String
Service type of this benefit. Typical values are tmj, dental_implants, etc. Certain insurance companies may put free text values here. Refer here for a more detailed list.
The time period that applies to this benefit. Example: calendar means the benefit period relates to January 1 to December 31 of the current year.
amount
String
Dollar amount of this benefit. In context of maximums, the amount is the maximum dollar amount insurance will pay for. In context of deductible, the amount is the amount a patient must pay before insurance pays out.
The coverage level this benefit applies to. Example: family would relate to the benefit in the family context (i.e. family deductible amount typically will be 3x the time of the individual deductible).
percent
String
Percent always in context of how much the insurance company will pay. Example: if 100%, insurance will pay out 100% of this procedure/category. Note: you still need the Fee Schedule to make sure you are using the correct fee when submitting the claim (i.e. you can't submit a claim for a cleaning of $1,000,000 and expect insurance companies to pay 100%, they will usually pay 100% of the UCR fee / negotiated fee on the fee schedule that each provider has typically in a PDF or printed out file).
procedure_code
String
Specific procedure code this benefit relates to. Example: D0120
limitation
String
Descriptive limitation such as frequency limitation for this benefit. Example: 1 visits in 60 month (in context of full mouth x-rays)
limitation_applies_to
[String]
List of procedure codes that the limitation also applies to. Service history on any of these procedure codes will affect all their frequencies.
Specific information about the limitation including broken out values for frequency.
payer_specific_description
String
Free text description about this benefit. Some insurances may put network specific info like PPO in here. Our long term goal is to codify and eliminate this section. Please reach out to support@onederful.co if you think any values in this section should be codified or put into another parameter.
The plan status such as active to know if the plan is active or not
end_date
String
The end date for the plan
Address
Parameter
Type
Description
street1
String
The first line of an address
street2
String
The second line of an address
city
String
The city of an address
zip
String
The zipcode of an address
state
String
The state of an address
Payer
Parameter
Type
Description
id
String
The returned payer ID from the insurance (will look different from onederful payer ID as the onederful payer IDs are abstracted IDs depending on the data source)
The value which reads as age up to (i.e. age_high_limit: 18 == up to age 18)
age_low_value
String
The value which reads as age minimum is (i.e. age_low_value: 5 == minimum age of 5)
Health Service Description
Parameter
Type
Description
quantity_qualifier
String
quantity_qualifier and quantity go together.
quantity
String
quantity_qualifier and quantity go together.
unit_qualifier
String
unit_qualifier and unit go together.
unit
String
unit_qualifier and unit go together.
time_period_qualifier
String
time_period_qualifier and time_period_value go together.
time_period_value
String
time_period_qualifier and time_period_value go together.
delivery_frequency
String
delivery_frequency and delivery_pattern_time go together.
delivery_pattern_time
String
delivery_frequency and delivery_pattern_time go together.
Service History
Parameter
Type
Description
procedure_code
String
Procedure code related to this service date
service_date
String
The actual service date (MM/DD/YYYY)
tooth_code
String
Tooth code of the service date
tooth_surfaces
String
Tooth surface of the service date
type
String
type and value go together. Descriptor of the service.
value
String
type and value go together. Value related to the descriptor of the service.
Metadata
Parameter
Type
Description
type
String
type and value go together. Descriptor.
value
String
type and value go together. Value related to the descriptor.
Claim Submission API
Claim submission API is a RESTful API (no SFTP needed) enabling submission of dental claims. As the process is asynchronous and can take up to a couple days before insurance companies adjudicate the claim, notifications will be sent through webhooks (i.e. no need to poll, Onederful will push notifications directly to you).
The dependent (if any) of the benefits you are requesting. Typically, the dependent member id is the same as the subscriber member id. When requesting for a dependent, you do not have to include the subscriber object (i.e. subscriber is not required to query for a dependent).
If billing is not a person but an organization with a type 2 NPI, use this instead of first_name and last_name
Claim Request Schema
Parameter
Required
Type
Description
amount
true
String
Total claim charge amount. If you are billing for $1000.00, you would put "1000.00" here. (Note: Total amount must equal the sum of all the amounts in the services section)
notes
false
[String]
Free text notes to send to insurance companies. Max 5 notes with limitations of 80 characters per note.
Detailed information about services rendered for the claim
service_date
false
String
Service Date for the claim. Dates specified in the services section will override this value for those specific services. Format must be in (MM/DD/YYYY) where MM = month, DD = day, YYYY = year.
Tooth information relating to the tooth number and tooth surfaces
service_date
false
String
Date of service, if different from the claim.service_date
prior_placement_date
false
String
Required if prosthetic_placement_status is replacement
ortho_banding_date
false
String
Date orthodontic appliance was place
ortho_replacement_date
false
String
Required if orthodontic appliance was replaced
predetermination_id
false
String
If submitting a claim that had a predetermination, you can add that predetermination ID here
description
false
String
Free text area to add additional information. Limit 80 characters. Note: as this is free text, this section may prompt a person on the insurance side to manually review which may affect overall time required to process the claim.
Tooth Status Schema
Parameter
Required
Type
Description
tooth_number
false
String
The tooth number from ADA's Universal/National Tooth Designation System
Tooth surface when procedure performed by tooth involves one or more surfaces
Address Request Schema
Parameter
Required
Type
Description
street1
true
String
First line of a street address
street2
false
String
Second line of a street address. If no second line, don't include
city
true
String
City of the address
state
true
String
State of the address
zip
false
String
Zipcode of the address
Relevant Enums
To use this section properly, when sending the claim submission request to Onederful, the Accepted Keys are the only values accepted for their corresponding parameters.
Provider Taxonomy Enum
Accepted Keys
Description
dentist
Dentist (122300000X)
orthodontics_and_dentofacial_orthopedics
Orthodontics And Dentofacial Orthopedics(1223X0400X)
general_practice
General Practice (1223G0001X)
dental_public_health
Dental Public Health (1223D0001X)
dentist_anesthesiologist
Dentist Anesthesiologist (1223D0004X)
endodontics
Endodontics (1223E0200X)
oral_and_maxillofacial_pathology
Oral and Maxillofacial Pathology (1223P0106X)
pediatric_dentistry
Pediatric Dentistry (1223P0221X)
periodontics
Periodontics (1223P0300X)
prosthodontics
Prosthodontics (1223P0700X)
oral_and_maxillofacial_surgery
Oral and Maxillofacial Surgery (1223S0112X)
oral_and_maxillofacial_radiology
Oral and Maxillofacial Radiology (1223X0008X)
orofacial_pain
Orofacial Pain (1223X2210X)
Place of Service Enum
Accepted Keys
office
home
assisted_living_facility
group_home
mobile_unit
temporary_lodging
walk_in_retail_health_clinic
worksite
off_campus_outpatient_hospital
urgent_care_facility
inpatient_hospital
outpatient_hospital
emergency_room_hospital
telehealth
Provider Signature Enum
Accepted Keys
yes
no
Plan Participation Enum
Accepted Keys
assigned
not_assigned
Authorized Payment Enum
Accepted Keys
yes
no
patient_refuses_to_assign_benefits
Release of Information Enum
Accepted Keys
has_signed_statement
no_signature
Tooth Status Enum
Accepted Keys
to_be_extracted
missing
Tooth Surfaces Enum
Accepted Keys
Description
B
Buccal
D
Distal
F
Facial
I
Incisal
L
Lingual
M
Mesial
O
Occlusal
Oral Cavity Designation Enum
Accepted Keys
Description
00
Entire oral cavity
01
Maxillary Arch
02
Mandibular Arch
10
Upper Right Quadrant
20
Upper Left Quadrant
30
Lower Left Quadrant
40
Lower Right Quadrant
Prosthetic Placement Enum
Accepted Keys
initial_placement
replacement
Gender Enum
Accepted Keys
Description
M
Male
F
Female
U
Unknown
Response Claim Submission API
Claim submission response will be sent back to you immediately once the claim is submitted into our system.
As the claim submission flow is asynchronous and takes days to weeks for the insurance company to start adjudicating the claim,
rather than hold a connection open for days, we use webhook notifications to push updates directly to you.
If there are no quick server side validation errors, you will get the response similar to the (EXAMPLE RESPONSE)
(EXAMPLE RESPONSE)
{"onederfulId":"1b2cdfr1-341x-25exb-ad15-454d513456af","message":"Payers may take a couple of days before responding to claims submission. Notifications will be sent to your webhook url, for instructions on registering a webhook url please refer to our developer documentation at: https://developers.onederful.co/documentation"}
Response Schema
Parameter
Type
Description
onederfulId
String
Unique UUID passed back by Onederful in every response. You can just pass the onederfulId when emailing support@onederful.co for any questions about a specific transaction.
message
String
Generic message that claims may take days to weeks to start the adjudication process on the insurance company side. Notifications will be sent as an HTTPS POST to your registered webhook URL
The dependent (if any) of the benefits you are requesting. Typically, the dependent member id is the same as the subscriber member id. When requesting for a dependent, you do not have to include the subscriber object (i.e. subscriber is not required to query for a dependent).
The insurance company (payer) you are querying for (i.e. Aetna, Principal, etc.)
service_date
true
String
The service date for the requested claim. Format must be in (MM/DD/YYYY) where MM = month, DD = day, YYYY = year.
service_date_end
false
String
(optional: if end date is different from service_date you can put the end service date here). Format must be in (MM/DD/YYYY) where MM = month, DD = day, YYYY = year.
total_amount_submitted
false
String
Dollar amount of claim submitted
Claim Status Patient Request Schema
Parameter
Required
Type
Description
first_name
true
String
First name of the patient
last_name
true
String
Last name of the patient
dob
true
String
Date of birth of the patient. Format must be in (MM/DD/YYYY) where MM = month, DD = day, YYYY = year.
member_id
true
String
Member ID of the patient (can also be the SSN of the patient, however, many insurances are moving away from SSN towards member IDs).
group_number
false
String
Group number of the insurance plan you are searching for
The returned payer ID from the insurance (will look different from onederful payer ID as the onederful payer IDs are abstracted IDs depending on the data source)
name
String
Payer name
Claim Status Response Provider
Parameter
Type
Description
entity
String
Entity type of the provider (can ignore)
name
String
Provider name
npi
String
Provider npi
Claim Status Response Provider
Parameter
Type
Description
entity
String
Entity type of the patient (can ignore)
member_id
String
Patient member id
first_name
String
Patient first name
last_name
String
Patient last name
Claim Status Response Claim
Parameter
Type
Description
claim_control_number
String
Autogenerated claim control number
date
String
Date of the claim requested for (can be a range of dates)
ERA webhook enables a push notification of electronic EOB (explanation of benefits) to route through Onederful to push to you. Enrollment is required in order to enable ERAs to pass through Onederful. This can tie end to end claim submission to getting ERA info all digitized.
Response ERA
(EXAMPLE RESPONSE) Response from insurance (note: data has been abbreviated for length)
{"financial_info":{"transaction_handling_code":"remittance_information_only","payment_amount":"500","transaction_type":"credit","payment_method":"check","issue_date":"01/01/2020","check_number":"1234561","payer_id":"1234561234","date":{"qualifier":"production","value":"01/01/2020"},"references":[{"qualifier":"receiver_identification_number","value":"123456789"},{"qualifier":"version_code_local","value":"1.2.3.456"}]},"payer":{"name":"PAYER","address":{"street1":"PO Box 12345","city":"SAN FRANCISCO","state":"CA","zip":"94105"},"contact_info":[{"contact_function":"payers_claim_office","name":"JOHN DOE","contacts":[{"method":"fax","value":"8001234567"}]}]},"payee":{"name":"Dental Group","npi":"1234567890","address":{"street1":"123 CALIFORNIA ST","city":"SAN FRANCISCO","zip":"94101","state":"CA"},"references":[{"qualifier":"tax_id","value":"123456789"}]},"claims":[{"assigned_number":"1","provider_id":"12345","facility_type":"office","fiscal_period_date":"01/01/2020","claim_count":"2","total_claim_charge_amount":"2000","claim_payment_info":[{"patient_control_number":"ABCDEFGHI","status":"processed_as_primary","total_charge_amount":"2000","claim_payment_amount":"500","claim_filing_indicator_code":"health_maintenance_organization","payer_claim_control_number":"2020010101203","facility_type":"office","patient":{"member_id":"1234567890","first_name":"JANE","last_name":"DOE"},"rendering_provider":{"npi":"1234567890","first_name":"JOHN","last_name":"DOE"},"date":{"qualifier":"received","value":"01/01/2020"},"claim_supplemental_amount":{"qualifier":"coverage_amount","value":"2000"},"service_payment_info":[{"product_service_detailed":{"procedure_code":"D0210"},"line_charge_amount":"500","line_payment_amount":"250","units_of_service_paid":"1","date":{"qualifier":"service","value":"01/01/2020"},"claim_supplemental_amount":{"qualifier":"allowed_actual","value":"250"},"claim_adjustments":[{"claim_adjustment_group_code":"contractual_obligations","adjustment_amount":"250"}],"references":[{"qualifier":"provider_control_number","value":"P1234567"}]},{"product_service_detailed":{"procedure_code":"D1110"},"line_charge_amount":"500","line_payment_amount":"250","units_of_service_paid":"1","date":{"qualifier":"service","value":"01/01/2020"},"claim_supplemental_amount":{"qualifier":"allowed_actual","value":"250"},"claim_adjustments":[{"claim_adjustment_group_code":"contractual_obligations","adjustment_amount":"250"}],"references":[{"qualifier":"provider_control_number","value":"P1234568"}]}]},...]}]}
Registering your webhook URL with Onederful allows Onederful to push notifications directly to your server.
By moving to an events driven notification system, Onederful is able to push notifications directly to you without you having to ping for updates.
Setting up a webhook URL is helpful during the claim submission process, as insurances may take days to weeks to send a response.
Parameter
Required
Description
url
true
Your webhook URL, example: https://www..com/webhook
Payer List API
Request Payer List
Payer List request
curl -X GET https://production.onederful.co/payer/list
(EXAMPLE RESPONSE) Onederful supported Payer List (note: data has been abbreviated for length)
[{"id":"3M","name":"3M Dental Services","features":["eligibility","claim_submission","claim_status","era"]},{"id":"32_BJ","name":"32 BJ","features":["eligibility","claim_submission","claim_status","era"]},{"id":"AARP","name":"AARP Dental Insurance Plan","features":["eligibility","claim_submission","claim_status","era"]},{"id":"ADMINISTRATIVE_SERVICES_ONLY","name":"Administrative Services Only (ASO)","features":["eligibility","claim_submission"]},{"id":"ADVANTICA","name":"Advantica","features":["eligibility","claim_submission","claim_status","era"]},{"id":"AETNA_DENTAL_PLANS","name":"Aetna Dental Plans","features":["eligibility","claim_submission","claim_status","era"]},{"id":"AETNA_DMO","name":"Aetna DMO","features":["eligibility","claim_submission","claim_status","era"]},{"id":"AFFINITY_HEALTH","name":"Affinity Health Plan","features":["eligibility","claim_submission","era"]},{"id":"ALIERA","name":"Aliera Health Care","features":["eligibility","claim_submission"]},{"id":"ALLEGIANCE","name":"Allegiance Benefit Plan Management, Inc.","features":["eligibility","claim_submission","claim_status","era"]},...]
This endpoint is helpful for saving Onederful's payer list into your own database. This list will be kept up to date with any new payers.
HTTP Request
GET https://production.onederful.co/payer/list
Response Schema
Parameter
Type
Description
id
String
Onederful payer ID, required when sending requests to Onederful APIs
{"message":"Payer Specific Error","code":"payer_specific_error","onederfulId":"1b2cdfr1-341x-25exb-ad15-454d513456af","errors":[{"reason":"invalid_missing_subscriber_insured_id","valid_request_indicator":"yes","follow_up":"please_correct_and_resubmit","payer_specific_message":"Please call (800)123-4567 for benefit information"}]}
Unique UUID passed back by Onederful in every response. You can just pass the onederfulId when emailing support@onederful.co for any questions about a specific transaction.
The eligibility sandbox was created to showcase specific test case responses. The sandbox can be used effectively to get
a sense of what data will be returned and basic validation. The quicker you can move to production data the better as the
more real-life scenarios will be uncovered (i.e. the sandbox is just a snapshot of very specific test cases).
The sandbox is not meant for production data and should not be a replacement for full implementation. The sandbox data returns
static mock data and does not represent all the variations of responses that you can recieve from insurance companies.
The currently supported test cases for sandbox are:
PRINCIPAL (full dental eligiblity and benefits response)
AETNA_DENTAL_PLANS (orthodontics flag set)
DD_CALIFORNIA (general dental eligibility and benefits response)
METLIFE (general dental eligibility and benefits response)
