A guide to AngelTrack's billing API, how to consume it, and some suggestions on its use
AngelTrack offers APIs by which billing data may be manipulated and retrieved.
Every AngelTrack cloud server has a webservice named PostprocessWorkflow.asmx. Therefore, a cloud server named 'acme' offers its webservice over HTTPS like this:
Application developers may request its WSDL document like this:
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.
To access this webservice, your application's SOAP request must contain an authentication header (as described by the WSDL) that contains the following data:
|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".
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.
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 State Uploads Guide.
Specifying 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().
Downloading 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.
Downloading 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 BillingQueueDownloadNextDispatchAsNEMSISXML() 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 BillingQueueDownloadNextDispatchAsNEMSISXML() method, if you have verified your XMl download process. Simply pass 4 (Awaiting payment) or 5 (Finished) in the AdvanceDispatchToPostprocessStatus parameter.
Redownload of dispatch data / Changes in underlying records
At any time, you can re-download any dispatch by calling DispatchDownloadAsNEMSISXML().
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.