Home‎ > ‎Other Modules‎ > ‎

Phone API: Search Matters by Phone Number from an External Application

Purpose: LegalServer allows an external application to perform a phone number search and return matter information via an API (Application Programming Interface). An agency's phone system could, for example, use the API phone search to return matters that match Caller ID or a manually entered number.

Cost: There is no cost for this feature.


What is Searched

LegalServer returns information on matters that have had activity in the last twelve months.

Activity in the last 12 months is cases with Date Opened within a year of the current date.

All client phone numbers are searched. Phone numbers of other people linked to a matter, like family members, are not searched.

Data Returned

The API search returns the following fields:

ID (matter index number)
First
Last
Full Name
Date Open
DOB
Matter ID (full Matter/Case ID)
Legal Problem Code
Current Disposition
Disposition Status
Disposition Date
Primary Advocate
URL (a partial URL for the matter; external application can prepend the hostname and display this as a clickable link)

Administrative Setup

Create a new user role, suggested name "API":
* Give this role only the "API Access", "API Search Cases by Phone", and "Login" permissions.

Create a new user:
* Suggested username "api_user" and name "API User"
* Set Login Active to Yes, Current to No, and Contact Active to No.
* Select the user role created above.
* Select an Office and a Program (any value)
* Enter an email address (a single @ character is fine)
* All other fields can be any choice or left blank if not required.
* Set a strong password, and do not require it be changed on next login.
* If your site expires passwords, this user's password will need to be periodically reset as well.

API Documentation

Documentation is on the /matter/api page for any role with the API Access permission — typically only Administrators and the special API user. Add that path your agency's base URL to view the page.

The API Help information listed below is subject to change. Information at the above URL is definitive.

API Help

Parameters For All Methods 
output_format – Optional – json|xml – defaults to json

Caller ID Search

URL 
/matter/api/caller_id_search/

Permissons Required 
API Search Cases By Phone

Parameters 
number – Required – Phone number to search for. Anything non-numeric is ignored.

Example 
/matter/api/caller_id_search/?number=1-212-555-1212&output_format=json

{
    "results": [
        {
            "id": {
                "raw_value": "556287",
                "text_value": "556287"
            },
            "first": {
                "raw_value": "Fidel",
                "text_value": "Fidel"
            },
            "last": {
                "raw_value": "Castro",
                "text_value": "Castro"
            },
            "full_name": {
                "raw_value": "Fidel Castro",
                "text_value": "Fidel Castro"
            },
            "date_open": {
                "raw_value": "",
                "text_value": "N\/A"
            },
            "unique_id": {
                "raw_value": "cdd82e78-6311-11dd-8e03-001ec947c021",
                "text_value": "cdd82e78-6311-11dd-8e03-001ec947c021"
            },
            "dob": {
                "raw_value": "1999-01-01",
                "text_value": "01\/01\/1999"
            },
            "identification_number": {
                "raw_value": "08-0556287",
                "text_value": "08-0556287"
            },
            "legal_problem_code": {
                "raw_value": "",
                "text_value": "N\/A"
            },
            "current_disposition": {
                "raw_value": "Matter: Rejected",
                "text_value": "Matter: Rejected"
            },
            "disposition_status": {
                "raw_value": "Out of State Legal Issue",
                "text_value": "Out of State Legal Issue"
            },
            "disposition_date": {
                "raw_value": "2008-08-05",
                "text_value": "08\/05\/2008"
            },
            "primary_advocate": {
                "raw_value": "",
                "text_value": "N\/A"
            },
            "url": "\/matter\/dynamic-profile\/view\/556287"
        },

Command Line Testing

$ curl "https://apiusername:password@sitename.legalserver.org/matter/api/caller_id_search/?number=1234567890"

With appropriate substitutions for apiusername, password, sitename, and the actual number to search.

API Testing with a Browser

Log out, and log in with the api username and password

login screen welcome - username - password

Put the API query in the address bar. You are already logged in as the API user, so repeating the login and password isn't necessary: