A guide to AngelTrack's billing API, how to consume it, and some suggestions on its use
AngelTrack offers an API by which billing data may be manipulated and retrieved.
If you are looking for the CAD API, that allows you to push new trips into the system and then retrieve their status, refer to the CAD API Accepting NEMSIS article.
PostprocessWorkflow.asmx
Every AngelTrack cloud server has a webservice named PostprocessWorkflow.asmx. Therefore, a cloud server named 'acme' offers its webservice over HTTPS like this:
https://acme.angeltrack.com/PostprocessWorkflow.asmx
Application developers may request its WSDL document like this:
https://acme.angeltrack.com/PostprocessWorkflow.asmx?wsdl
The WSDL describes the methods offered and their expected parameters. The methods will download NEMSIS XMLs of billable trips, as well as perform postprocess workflow moves.
Application developers can also browse to its URL to view its interfaces and their expected inputs and outputs.
Authentication
To use this webservice, you must have an API key, issued to you by an administrator of the AngelTrack server.
An API key is a GUID with dashes but no curly braces, like this:
F0BBC854-9222-486F-A76B-658FCF9E06AA
The API key includes the designation of a proxy employee, which is an employee account in AngelTrack in whose name all webservice activity is attributed. You can create a special employee account just for this purpose, naming it something like "Postprocess API Activity".
To learn how to issue and manage API keys, visit the API Key Guide.
When accessing the webservice, you must pass an authentication header (as described by the WSDL) within the SOAP request body that specifies the following datafields:
InstallationID - This is your API key, with dashes but without any curly braces.
Username - This legacy field is ignored, send any freetext you like.
Password - This legacy field is ignored, send any freetext you like.
Here is a sample SOAP request body with authentication header:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<Authentication xmlns="http://angeltrack.com/webservices/">
<InstallationID>448F4A7C-813A-4906-BC52-9007235B35A1</InstallationID>
<Username>not applicable</Username>
<Password>not applicable</Password>
</Authentication>
</soap:Header>
<soap:Body>
<DispatchDownloadPCRAsPDF xmlns="http://angeltrack.com/webservices/">
<DispatchID>your_desired_dispatch_ID</DispatchID>
</DispatchDownloadPCRAsPDF>
</soap:Body>
</soap:Envelope>
SOAP webservices return HTTP error 500 on any error -- even those which are not server-side problems, such as invalid passwords. If you receive any HTTP status other than 200, then examine the reply body to see the error message.
Legacy Authentication
Until July 2024, you can also access this webservice using its legacy authentication method. To do so, send a SOAP request containing an authentication header (as described by the WSDL) that specifies the following datafields:
| Datafield | Contents |
|---|---|
| InstallationID | The unique installation ID of the AngelTrack cloud server. It is a UUID. This data can be found at the top-right corner of the Diagnostics page under Settings, but is only visible to Administrators and to the Principal employee(s). When you place the installation ID in your SOAP header, include the dash characters but do not include curly braces, quotation marks, or whitespace. |
| Username | Any AngelTrack login name that has Administrator, Principal, or Biller access. If the account is a Biller and none of the others, then it must NOT be marked as 'provisional'. The login name is not case-sensitive. |
| Password | The account's password in plain text. It is case-sensitive. |
Your SOAP request must be sent in an HTTP POST which contains an http header-field named "Content-Type" set to "application/soap+xml; charset=utf-8".
Here is a sample SOAP request body using the legacy authentication header:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<Authentication xmlns="http://angeltrack.com/webservices/">
<InstallationID>your_installation_ID</InstallationID>
<Username>your_user_name</Username>
<Password>your_plaintext_password</Password>
</Authentication>
</soap:Header>
<soap:Body>
<DispatchDownloadPCRAsPDF xmlns="http://angeltrack.com/webservices/">
<DispatchID>your_desired_dispatch_ID</DispatchID>
</DispatchDownloadPCRAsPDF>
</soap:Body>
</soap:Envelope>
SOAP webservices return HTTP error 500 on any error -- even those which are not server-side problems, such as invalid passwords. If you receive any HTTP status other than 200, then examine the reply body to see the error message.
If your legacy authentication attempt is successful, then AngelTrack will auto-migrate your InstallationID and Username values to a new API key, so that in the future you can stop sending real values in the authentication header's Username and Password fields.
Flood Protection
Each customer (i.e. each EMS provider) is limited to ten API requests in any sixty-second period; any request after the tenth will fail, returning error 500 plus a message requesting the web service slow down.
Because you will probably be making two requests per dispatch (download XML + workflow advance), you must limit your requests to five dispatches per minute.
Backlogs
The service-method BillingQueueDownloadNextDispatchAsNEMSISXML() retrieves the oldest dispatch that is currently at Billing office . Therefore you may have to work through a long backlog -- advancing each one to Finished -- before reaching the recent trips.
Some Billing Data is Emitted in Custom Fields
The NEMSIS spec does not have room for very much billing data, as it is focused on the medical aspects of EMS. Therefore, AngelTrack stashes some of its billing data in <eCustomResults>.
To see which fields are available there, and their formats, refer to the AngelTrack Custom Fields in NEMSIS Data Guide.
Specify the NEMSIS Version
By default, AngelTrack will download NEMSIS XMLs to you in v3.4.0 format. If you would prefer to receive them in v3.5.0 format, then use the alternate versions of the service-methods: BillingQueueDownloadNextDispatchAsNEMSISXMLInVersion() and DispatchDownloadAsNEMSISXMLInVersion().
Download Attached Documents
The webservice methods that offer to download NEMSIS XMLs all have a IncludeDocumentsSetting parameter, which takes one of these five values:
- Use the systemwide preference setting (defaults to '1')
- Exclude all documents
- Include only documents attached directly to the dispatch
- Include documents attached directly to the dispatch or to any paired (return-trip) dispatch
- Include all documents for the dispatch, and for any paired dispatch, and for the patient according to the document persistence window (defaults to 60 days)
Note that attached documents can require significant data, sometimes resulting in large XML downloads -- 10MB or even 20MB.
Download a PDF of the Full PCR
You can use the web-method DispatchDownloadPCRAsPDF() to retrieve the full PCR in compact PDF format.
Detached Biller Example
This webservice is intended for detached billers, who pull data out of AngelTrack in order to perform all billing and bookkeeping in a third-party application.
Please refer to this diagram, which visualizes AngelTrack's postprocess workflow:
The webservice will retrieve all dispatches that have completed, or have skipped over, the QA review process, and are marked 'billable', thus arriving at Billing office (step 3). It does not take account of parking, i.e. it will return both parked and unparked dispatches.
Note that billable trips delegated to an affiliate that performs their own billing will be automatically marked by AngelTrack as 'non-billable'. Therefore, you cannot download these trips through the web service.
The detached biller's software will therefore use the webservice like this:
- Call BillingQueueDownloadNextDispatchAsNEMSISXMLInVersion() to fetch the next dispatch at Billing office (step 3).
- Verify that the downloaded XML was correctly imported into the detached biller's system.
- Retrieve the dispatch ID from the downloaded XML; it is in the <eRecord.01> node.
- Call DispatchChangePostprocessStatus() to tell AngelTrack to advance the downloaded dispatch to Finished (step 5).
All four steps can be combined in a single step, by means of the AdvanceDispatchToPostprocessStatus parameter to the BillingQueueDownloadNextDispatchAsNEMSISXMLInVersion() method, if you have verified your XMl download process. Simply pass 4 (Awaiting payment) or 5 (Finished) in the AdvanceDispatchToPostprocessStatus parameter.
Redownload of Data / Changes in Underlying Records
At any time, you can re-download any dispatch by calling DispatchDownloadAsNEMSISXMLInVersion().
Once a dispatch reaches Billing office (step 3), AngelTrack does not allow the crew to modify anything in the PCR; however, the underlying patient record may undergo changes, such as the addition of insurance policy data. AngelTrack does not use a push API to notify you that this has occurred.
You may track patient records using the ID number emitted in the <ePatient.01> node. Later trips for a specific patient might result in a backfill of data that was missing during their earlier trips.
Fail a Dispatch Back to QA / Kick-Backs
You can fail a dispatch back to QA review by calling DispatchChangePostprocessStatus() and specifying the value of 1 in the DesiredPostprocessStatus parameter. AngelTrack will automatically add the appropriate comment to the journal.
When you do this, you'll want to append some guidance to the Billing Notes field, so the QA reviewer knows why you kicked it back. For this, call DispatchAppendBillingNote(), and specify your new text for the Billing Notes. AngelTrack will automatically append your new text to the end of the Billing Notes field, along with your username and the current date and time.
The Billing Notes field is limited to 20,000 characters. You can append up to 1,000 characters using this API call.
Retrieve a List of All Dispatches at Billing Office
You can use the Billing API to retrieve a list of all dispatches currently at Billing Office, sorted according to their workflow locations. For example, the list will include the IDs of all dispatches currently in the Insurance Review Queue, and in the Insurance Filing Queue, and so forth.
To retrieve the list, call ListAllDispatchesAtBillingOffice(). The reply data is formatted as a single XML document, with a child node for each billing queue specifying its contents.
Once you have the list, you will know all the dispatch IDs, which can then be passed to the other API functions.