PulsePoint Integration Primer

This short document is meant to accompany our API documentation and outlines important features and behavior of the PulsePoint system.  If you have implemented Internet based web services before, much of this information will be familiar.  Reading through this document before starting may help you avoid common mistakes and make better choices during your integration work.  The API documentation fully describes all system resources and functions and should be referenced once the concepts presented here are understood.

System Overview

REST Resources - Background

Error Handling

  1. The service uses HTTP Status Codes for communicating success/failure that is used by program clients.
  2. Failed service requests involving user entered data (POSTs) additionally include a list of user error messages in the response body that describes the action needed to correct the error condition.
  3. It is very important that your client integration acknowledges these status codes and messages and respond to them appropriately.  Ignoring status code errors can have detrimental effects on your integration.

Data Format

Our resources are delivered in JSON (Java Script Object Notation) format. We chose JSON for its simplicity. JSON not only fits in well with the Web’s JavaScript programming model, it’s more compact than XML and the complexity of XML namespaces and schemas are not needed in our use case.

URL endpoints

Sandbox

https://api.pulsepoint.org/v1-sandbox/

Production

https://api.pulsepoint.org/v1/

API Authentication

On your development account page, you will see a section titled "PulsePoint Information" that contains all of your system credentials.

Passwords

There are two passwords used in the PulsePoint system, one for account administration access and another that’s used by your integration for API authentication.  You chose an Administration password when you signed up and can change it at any time.  The Administration password is used to gain access to your account information on the PulsePoint developer site.  The API Password is assigned by PulsePoint and cannot be changed by you.  If you ever have reason to believe that your API password has been compromised, contact PulsePoint and a new password and API key(s) will be generated for you.  The PulsePoint app server uses Basic Auth which requires your account username and the supplied API Password.  Do not confuse this password with the Administration Password you use to access account administration.

API Keys

There are two different API keys. One for our sandbox server and one for production.  Once your agency is approved to start development (Status: Reviewed), you will see the Sandbox API Key in the “PulsePoint Information” section of your developer account page.  You will use this key along with your Username and API Password to authenticate your integration to the sandbox endpoint during your development.  Once PulsePoint approves your integration for production, the Production API Key will appear.  You will then use this production key along with the production endpoint to 'go-live' with your integration.

CAD Systems and Internet Based Web Services

The persistent socket nature of the typical Computer Aided Dispatch system can clash with the requirements of Internet based web services.  CAD systems are typically event driven engines, passing incident and unit updates via persistent sockets in real time to internal systems. While PulsePoint itself is an asynchronous multithreaded system, its interface is via the REST web service model.  Incident submissions must be verified as successful before subsequent updates of the same incident are made.  If not, update ordering problems can result due to to latency, connection failures and other internet related issues. Out-of-order posting of incidents can have many detrimental side-effects.

Incident and Unit Data - What's required, what's not, and what's nice-to-have.

We encourage agencies to submit as many incident attributes as they can match to the PulsePoint system.  The PulsePoint dataset was compiled with an eye toward future enhancements.  Submitting as many attributes as you can will help ‘future-proof’ your integration.  Doing so will also increase the likelihood that you will not have to make attribute additions to your integration if we add a new feature to the PulsePoint application that uses an attribute that you opted not to include.

Incident attribute subset used by the PulsePoint App (See API doc for full Incident data

set)

Incident block

AgencyID                                

Required

TransactionID                            

Required

IncidentNumber                           

Required

StreetNumber                             

Required (post address fields as needed to complete an address or convey a location. If exact address is not known, system will use cross streets.)

Predirectional                           

As needed

StreetName                               

Required

StreetSuffix                             

Required

Postdirectional                          

As needed

Suite                                    

As needed

Building                                 

As needed

Floor                                    

As needed

CityOrLocality                           

Required

County (Parish)

Strongly encouraged

StateOrProvince                          

Required

PostalCode                   

Strongly encouraged

CommonPlaceName*                          

As needed*

*posting CommonPlaceName encouraged any time it’s available… used in CPR alert to help responder identify incident location (e.g., McDonalds, City Library, Union High School, etc.)

CrossStreet1                             

As needed

CrossStreet2

As needed

                           

Latitude, Longitude

Required.  If not submitted, system will geolocate based on address data.  Address data MUST follow USPS standards for geolocation to be accurate (but accuracy not guaranteed).

PublicLocation                           

If known, please submit.  If not available, system will derive from commercial delivery database using your posted address.

                              

PulsePointIncidentCallType               

Required

PulsePointDeterminantCode                

Required

                   

                         

CallReceivedDateTime                     

Required

ClosedDateTime                        

Required (on incident closure)

DispatchDateTime                       

Required (on first unit dispatched)

EnrouteDateTime                         

Strongly encouraged

OnSceneDateTime                           

Required (first unit on-scene)

EntryDateTime                            

Required

                 

Unit block              

AgencyID                         

Required

IncidentNumber                    

Required

UnitDispatchNumber                   

Required

UnitID               

Required

PulsePointDispatchStatus                           

Required

VehicleNumber                    

Strongly encouraged

TransactionID         

Strongly encouraged

AgencyDispatchStatus            

Strongly encouraged

UnitClearedDateTime             

Required

UnitDispatchDateTime         

Strongly encouraged

UnitAcknowledgeDateTime             

Strongly encouraged

UnitEnrouteDateTime             

Strongly encouraged

UnitOnSceneDateTime  

Strongly encouraged

UnitTransportStartDateTime

Strongly encouraged

UnitTransportArriveDateTime

Strongly encouraged

UnitAvailableOnEventDateTime             

Strongly encouraged

UnitInQuartersDateTime  

Strongly encouraged

Coordinates, Addressing and Geolocation

The PulsePoint mobile application displays a map view of an incident’s location when a user clicks on an incident entry. The map location is displayed based on coordinates either submitted by your integration or geolocated by the PulsePoint system from the submitted incident address.

PulsePoint requires that agencies submit incident location coordinates (WGS84 decimal lat/long) from their CAD system.  This is the most reliable way of ensuring mapping accuracy of the incident location in the PulsePoint application. If for some reason your integration fails to submit coordinates for an incident, then the PulsePoint server will derive coordinates from the submitted incident address. This coordinate lookup service is provided only as a backup and your integration should not rely on it as a default.  For our geolocation and public location determination to work properly, it is extremely important that all address components conform to USPS addressing rules.

Example:

Unacceptable

StreetNumber: 121

Predirectional: E

StreetName: GULF TO LAKE

StreetSuffix: HW

CityOrLocality: WLDWD

StateOrProvince: FLORIDA

PostalCode: 34785

CrossStreet1: VETRANS EX

CrossStreet2: SUNCOAST PY

Acceptable

StreetNumber: 121

Predirectional: E

StreetName: GULF TO LAKE

StreetSuffix: HWY

CityOrLocality: WILDWOOD

StateOrProvince: FL

PostalCode: 34785

CrossStreet1: VETRANS EXPY

CrossStreet2: SUNCOAST PKWY

DateTime Entry

Datetime stamps must conform to the ISO 8601 data interchange format with an offset from UTC.  This is the typical timestamp format used in web services.  For instance, if your agency is located on the US east coast, you would submit a datetime as 2012-15-01T09:31:34-05:00 (EST: -5 hour offset from UTC).  This will be stored in the PulsePoint system as 2012-15-01T14:31:34-00:00. (UTC or ‘ZULU’ time)  The PulsePoint mobile app will automatically convert stored UTC datetimes to the local time zone of the user's device for display.

Call Types, Determinant Codes and Unit Dispatch Status Codes

PulsePoint Incident/Unit types and codes are listed in the API documentation.

Your CAD system might not use the same incident call type codes as PulsePoint.  If not, you must map your call type codes to PulsePoint equivalents and submit them in the PulsePointIncidentCallType field.  Every incident must have a PulsePoint Incident Call Type.  You may also submit your system’s call types in the AgencyIncidentCallType field for reference.

The same is true for Medical Determinant Codes. You must map your determinant codes to PulsePoint equivalents and submit them in the PulsePointDeterminantCode field.  The only determinant codes absolutely required are those associated with the Pulsepoint ‘ME’ call type that trigger a CPR alert in the mobile application (noted in red in the API documentation).  Submission of determinant codes for non-CPR 'ME' incidents is completely at your discretion.

Unit Dispatch Status Codes are used to display unit status in the app.  Again, these unit codes must use the PulsePoint unit dispatch status codes (mapped from your unit status codes) and entered in the PulsePointDispatchStatus field.

Some Incident/Unit Lifecycle Tips

The Incident OnSceneDateTime should be updated when the first unit is on scene.  This is very important for ‘ME’ CPR alert incidents. The application’s CPR alert state closes for notified responder(s) when an EMS/Fire unit is on scene.

The Incident ClosedDateTime must be updated when an incident is closed.  This value triggers the transition of the incident from the Active to the Recent screen in the mobile app.  If this value is not updated when an incident is closed, the incident will remain in the active list for 24 hours after the last time the incident was updated and then dropped.

The Unit UnitDispatchNumber is a unique id that identifies a unit for its entire lifecycle serving an incident.  If your system does not have a unique dispatch id for a unit assigned to an incident, the actual UnitID (e.g., E34, T32, etc.) can be used in this field.