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)
Full Name
Date Open
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)

The data returned is limited to 20 matters.

Administrative Setup

If your site does not already have an API user and user role:

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 yoursite.legalserver.org/matter/api page for any role with the API Access permission — typically only Administrators and the special API user.

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


Permissons Required 
API Search Cases By Phone


number – Required – Phone number to search for. Anything non-numeric is ignored.
daysopenlimit – Optional – The number of days in the past to search.


    "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 -u username:password https://sitename-demo.legalserver.org/matter/api/caller_id_search/?number=1234567890&output_format=json


$ wget --http-user=username --http-password=password "https://sitename-demo.legalserver.org/matter/api/caller_id_search/?number=1234567890&output_format=json&FORCE_HTTP_AUTH=1" -q -O -

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

API Testing with a Browser

If your user role does not have the above permissions, 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: