API FAQs

Last updated
Save as PDF

Kareo SOAP API FAQs

Answers to the most common Kareo SOAP APIs questions and system integration patterns.

Question	Answer
Where can I review the API Terms of Use?	Review the API Terms of Use here.
Where do I download the Technical Guide?
Do I need to change any settings in the Kareo client in order to use the API?	Yes, a System Administrator needs to generate the Kareo Customer Key and set the appropriate security permissions in order to start using the Kareo SOAP API. As an added security measure, Kareo SOAP API requires the use of a customer key (in addition to login credentials) to access your data.
Can you look at my code to see what I’m doing wrong?	Due to the many different programming languages available and unfamiliarity with each engineer’s personal code, we do not provide technical support to debugging an integrator’s code. We can only provide support with the API web service on the Kareo side.
Do you have examples of how to interface with the Kareo API using PHP, C++, etc.?	There are too many different programming languages available for us to provide an example of every single language. We expect that an integrator will choose the language that best fits their design and need. However, here’s a PHP example: <?php try{ $user = ' YOUR KAREO USERNAME HERE '; $password = ' YOUR KAREO PASSWORD HERE '; $customerKey = ' YOUR KAREO CUSTOMERKEY HERE '; $wsdl = 'https://webservice.kareo.com/service...vices.svc?wsdl'; $client = new SoapClient($wsdl); $request = array ( 'RequestHeader' => array('User' => $user, 'Password' => $password, 'CustomerKey' => $customerKey), 'Filter' => array('FromLastModifiedDate' => '3/4/2012'), 'Fields' => array('PatientFullName' => 'true') ); $params = array('request' => $request); $response = $client->GetPatients($params)->GetPatientsResult; foreach($response->Patients->PatientData as &$value) { print($value->PatientFullName. '<br />'); } } catch (Exception $err) { print "Error: ". $err->getMessage(); } ?>
Does Kareo have a mechanism for pushing new/updated data to external systems?	No, Kareo does not automatically push information out to external systems.
Does Kareo support a HL7 messaging interface?	No, we do not currently support HL7 messaging.
How do I get the request and response XMLs for my transaction to receive API support?	There are many tools available on the internet to monitor and capture your computer’s web traffic. One of the most popular web debugging tools is Fiddler.
If I need to query Kareo for new/updated information, what is an acceptable polling frequency?	If you are polling the Kareo API, we suggest that 5 to 15 minute intervals are good settings to pull for refreshed data. We also recommend using the last modified parameter to narrow the return data.
In what format is DOB stored?	YYYY-MM-DD
What do I need to do in order to request Kareo engineering support for API related questions?	Please pull the request and response XMLs for the transaction you are having an error with. Submit your inquiry through a support ticket and include the request and response XMLs in the Description field of the form. Note: Kareo can only provide support with the API on the Kareo side.
What type of functions can I perform over the API interface?	The Kareo API offers a number of different functions to interact with the Kareo system data. These include: Retrieving data from different types of records in Kareo: Appointment (single) Appointments (bulk) Charges Encounter Details Patient (single) Patients (bulk) Payments Practices Procedure Codes Providers Service Locations Transactions Creating different types of records into Kareo: Create Appointment Create Patient Create Encounter Create Payment Updating patient records in Kareo Delete appointments
What type of integration does the Kareo API support?	Kareo’s API is a SOAP-based web service.

System Integration Patterns with Kareo SOAP APIs

I. External ID Usage

For many of the entities we expose via our public APIs, we provide a fields name with the 'ExternalId' postfix which are optional fields that can be used by an integrator to populate with identifiers generated by their own system. For example, a Patient will have a field named 'PatientExternalId', or an InsurancePolicy will have an InsuracePolicyExternalId.

For disambiguation, the same examples like Patients also have a PatientId, and, an InsurancePolicy has an InsurancePolicyId that will hold Kareo generated IDs for these entities.

The ExternalId fields can be used by integrators as a convenience to be able to query or GET data Kareo's APIs using IDs native to the system they want to integrate with Kareo. This alleviates the need for integrators to extend their records to also maintain a Kareo ID for each entity.

All of the GET endpoints available through our APIs will allow you to get or filter by the external ID instead of using a Kareo identifier for these entities.

II. Migrating Patient Data into Kareo

If you are integrating with Kareo for purposes of utilizing the Kareo Billing Module only, you do NOT need to do an initial load of all of your patients into Kareo. What you can do instead is design your integration with Kareo to have Patient information sent when billing is needed for a particular patient.

How?

Patient Creation Workflows:
- Whenever a new patient is created in the external system, you can immediately call the CreatePatient method on Kareo APIs to ensure the patient is also created in Kareo.
  - CASE 1: You are utilizing the External ID Field:
    - When you create the patient, make sure to populate the ExternalID field.
  - CASE 2: You are NOT utilizing the External ID Field:
    - When you create the patient, make sure to update your own patient records with Kareo's Patient Id.
Patient Creation when submitting a Superbill
- CASE 1: You are utilizing the External ID field:
  1. Check if the patient has already been created in Kareo. If so, submit the Superbill/Encounter. If not...
  2. Create the patient with the proper ExternalId, then submit the Superbill/Encounter
- CASE 2: You are NOT utilizing the External ID Field:
  1. Check if your patient record is assigned a Kareo Patient ID. If so, submit the Superbill/Encounter with the Kareo Patient Id. If not...
  2. Create the patient, update your own records with the Kareo Patient ID, then submit the Superbill/Encounter with the Kareo Patient Id.

III. Synchronizing/Retrieving Patient Changes Made within Kareo

Kareo does not connect to Web Hooks to send out patient demographics changes made by users within Kareo. If you anticipate users making changes to patient records from within Kareo, you more than likely want to ensure those changes are also made in the system you are integrating.

In order to retrieve changes made from within the Kareo Client, you can utilize the GetPatients (plural) API method. This method will allow you to specify either a FromLastModfiiedDate and/or a ToLastModifiedDate; the response from this call contains ALL patient records that have been updated within the scope of those dates.

In general, we recommend your system retrieves patient changes every 5 to 10 minutes to ensure records are kept up-to-date.