SOAP API Overview
The Northern 911 SOAP API provides live programmatic access to 9-1-1 client records. Using the SOAP API clients can build custom tools to add, update, delete or query client records.
The API is based on open standards known collectively as "Web Services," which include the Simple Object Access Protocol (SOAP) and Web Services Definition Language (WSDL).
These standards are supported by a wide range of development tools on a variety of platforms.
WSDL Schema Definitions
The Northern 911 Web Services schema is required for developing custom tools.
QA Schema: https://soapqa.northern911.com/soap/Service.svc?wsdl (Only to be used for initial integration testing. Ongoing address updates and validations are to be performed in Live environment)
Security
The Northern 911 SOAP API service is protected to ensure that only authorized users access it. The levels of security are as follows:
1. A required vendor code and a secret API passcode.
2. A daily changing MD5 hash string.
3. Secure Sockets Layer (SSL) data transport.
4. A maximum of 5 (five) login attempts; upon failure, SOAP access is disabled.
SOAP API Functions
Add new or update existing client record.
Request - AddorUpdateCustomer
Parameters:
Element
Included Element
Description
Data Type
Max Length
Customer
Customer data object
Customer Type
VENDOR_CODE
Vendor Code
String
3
PHONE_NUMBER
Customer phone number. Must be 10 digits
String
10
LAST_NAME
Last name or company name
String
100
FIRST_NAME
First name
String
38
STREET_NUMBER
Street number
String
10
SUITE_APT
Suite or apartment number
String
30
STREET_NAME
Street name
String
84
CITY
City
String
38
PROVINCE_STATE
Two letter province or state code
String
2
POSTAL_CODE_ZIP
Canadian postal code or USA zip code
String
10
OTHER_ADDRESS_INFO
Other information
String
250
ENHANCED_CAPABLE
Yes or No. Must be 'Y' or 'N'.
String
1
Response - AddorUpdateCustomerResult
Parameters:
Element
Included Element
Description
Data Type
Accepted
True if transaction is successful, otherwise false
Boolean
Errors
Error object
Error Type
ErrorMessage
Error message presented
String
SuggestedCity
Used when the database has a city suggestion.
String
SuggestedProvince
Used when the database has a province suggestion.
String
Returns current data for the requested record.
Request - QueryCustomer
Parameters:
Element
Included Element
Description
Data Type
Max Length
vendorCode
String containing your 2-3 digit vendor code
String
phoneNumber
Customer phone number. Must be 10 digits.
String
10
Response - QueryCustomerResult
Parameters:
Element
Included Element
Description
Data Type
Accepted
True if transaction is successful, otherwise false
Boolean
Customer
Customer data object
Customer Type
phoneNumber
Vendor Code
String
PHONE_NUMBER
Customer phone number. Must be 10 digits
String
LAST_NAME
Last name or company name
String
FIRST_NAME
First name
String
STREET_NUMBER
Street number
String
SUITE_APT
Suite or apartment number
String
STREET_NAME
Street name
String
CITY
City
String
PROVINCE_STATE
Two letter province or state code
String
POSTAL_CODE_ZIP
Canadian postal code or USA zip code
String
OTHER_ADDRESS_INFO
Other information
String
ENHANCED_CAPABLE
Yes or No. Must be 'Y' or 'N'.
String
LAST_DATETIME_MODIFIED
Timestamp indicating last update time. (UTC Date Time.)
String
LAST_DATETIME_MODIFIED_UNIXTIME
Unix timestamp indicating last update time. (Number of seconds elapsed since January 1st, 1970 Midnight UTC.)
String
Errors
Error object
Error Type
ErrorMessage
Error message presented
String
SuggestedCity
Used when the database has a city suggestion.
String
SuggestedProvince
Used when the database has a province suggestion.
String
Delete an existing client record
Request - DeleteCustomer
Parameters:
Element
Included Element
Description
Data Type
Max Length
vendorCode
String contraining your 2-3 digit vendor code
String
phoneNumber
Customer phone number. Must be 10 digits.
String
10
Response - DeleteCustomerResult
Parameters:
Element
Included Element
Description
Data Type
Accepted
True if transaction is successful, otherwise false
Boolean
Errors
Error object
Error Type
ErrorMessage
Error message presented
String
Get a URL to download the entire vendor database as CSV
Request - GetVendorDumpURL
Parameters:
Element
Included Element
Description
Data Type
Max Length
vendorCode
String contraining your 2-3 digit vendor code
String
Response - GetVendorDumpURL
Parameters:
Element
Included Element
Description
Data Type
Accepted
True if transaction is successful, otherwise false
Boolean
Errors
Error object
Error Type
ErrorMessage
Error message presented
String
VendorDumpURL
HTTPS URL for a one time secure download of the entire vendor database as a comma seperated file.
String
This does not modify customer details and only verifies whether or not the data passed to AddorUpdateCustomer would succeed.
Request - VerifyCustomer
Parameters:
Element
Included Element
Description
Data Type
Max Length
Customer
Customer data object
Customer Type
VENDOR_CODE
Vendor Code
String
3
PHONE_NUMBER
Customer phone number. Must be 10 digits
String
10
LAST_NAME
Last name or company name
String
100
FIRST_NAME
First name
String
38
STREET_NUMBER
Street number
String
10
SUITE_APT
Suite or apartment number
String
30
STREET_NAME
Street name
String
84
CITY
City
String
38
PROVINCE_STATE
Two letter province or state code
String
2
POSTAL_CODE_ZIP
Canadian postal code or USA zip code
String
10
OTHER_ADDRESS_INFO
Other information
String
250
ENHANCED_CAPABLE
Yes or No. Must be 'Y' or 'N'.
String
1
Response - VerifyCustomer
Parameters:
Element
Included Element
Description
Data Type
Accepted
True if all data is valid, otherwise false
Boolean
Errors
Error object
Error Type
ErrorMessage
Error message presented
String
SuggestedCity
Used when the database has a city suggestion.
String
SuggestedProvince
Used when the database has a province suggestion.
String
Hash is comprised of the following concatenated string:
1. Your vendor code.
2. Your secret SOAP API passcode.
3. The current date in GMT. (YYYYMMDD)
Please Note: You must create the hash to use GMT. GMT is Greenwich Mean Time with 0 offset.
See Example Code for more details.
| Code | Error Message | Description |
| 100 | That vendor code does not exist. | Vendor code does not exist in the Northern 911 Database. |
| 101 | That customer does not exist. | The customer you queried does not exist. |
| 102 | Invalid credentials supplied. | Authenticated with invalid credentials or has not been granted access. |
| 200 | Phone number is not valid. | Phone number is not valid. The number must be 10 digits, the first digit cannot be 0 or 1, and the number cannot start with 999. |
| 300 | Invalid Province/State code. | Province/State code must be a valid 2 letter Canadian province or US State abbreviation. (English) |
| 400 | Enhanced capable contains characters other than 'Y' or 'N'. | Enhanced capable field must either be Y or N. (Case insensitive.) |
| 500 | Not a valid Canadian postal code. | Not a valid Canadian postal code. (Assuming a valid Canadian province code was supplied. Also, case insensitive and white space insensitive. Must only contain letters and numbers.) |
| 501 | Not a valid American zip code. | Not a valid American zip code. (Assuming a valid American state code was supplied. Also, case insensitive and white space insensitive. Must only contain letters and numbers.) |
| 600 | Cannot have a US State with a valid Canadian postal code. | A valid Canadian postal code was validated with a valid US State code. This is invalid. |
| 666 | Fatal system error. Your request was not processed. Northern 911 has been notified. | There was a system error that occurred during the transaction and the request was therefore not performed. Northern 911 administrators are automatically notified when this error occurs. Please contact us if you would like to follow up. |
| 700 | That postal code does not match the given city (CITY,Province). Did you mean (SuggestedCITY, Province)? | The given postal code does not match the given city, province on file with Northern 911. (Canada only) |
| 701 | That zip code does not match the given city (CITY,State). Did you mean (SuggestedCITY, State)? | The given zip code does not match the given city, state on file with Northern 911. (United States only) |
| 800 | Vendor code must be 2 or 3 characters. | Vendor code is not a valid length. |
| 801 | Phone number must be 10 digits. | Phone number is not a valid length. |
| 802 | Last name must be <= 100 characters. | Last name is not a valid length. |
| 803 | First name must be <= 38 characters. | First name is not a valid length. |
| 804 | Street number must be <= 10 characters. | Street number is not a valid length. |
| 805 | Suite/Apt must be <= 30 characters. | Suite/Apt is not a valid length. |
| 806 | Street name must be <= 84 characters. | Street name is not a valid length. |
| 807 | City must be <= 38 characters. | City is not a valid length. |
| 808 | Province/State must be 2 characters. | Province/State code is not a valid length. |
| 809 | Postal/Zip code cannot be blank and <= 10 characters. | Postal/Zip code is not a valid length |
| 810 | Other address info must be <= 250 characters. | Other address info is not a valid length. |
| 811 | Enhanced capable must be 1 character. | Enhanced capable is not a valid length. |
| 812 | Postal/Zip code must be <= 10 characters (can be blank) | The Postal/Zip code supplied is not a valid length. (This is for non-Municipal Addresses only) |
| 900 | Cannot delete a phone number that does not exist. | Cannot delete a phone number that does not exist in the Northern 911 Database. |
| 950 | Vendor dump URL method call has been exceeded for your specified time interval. | Vendor can only make a call to this method either Weekly, Daily, or Hourly. (Based on your vendor setting.) |
AddorUpdateCustomer - C#
QueryCustomer - C#
DeleteCustomer - C#
GetVendorDumpURL - C#
PHP Example Code
AddorUpdateCustomer - PHP
QueryCustomer - PHP
DeleteCustomer - PHP
GetVendorDumpURL - PHP