Home‎ > ‎Pro Bono‎ > ‎

Pro Bono Opportunities API

Purpose: LegalServer allows an external application to search for cases and return information about the Pro Bono Opportunities data on those cases.

For example, an agency's website could query its instance of LegalServer and get limited (anonymous) data about each case tagged as being an available opportunity.

Cost: There is no cost to implement this feature. 


What is Searched

Cases with disposition set to either Open or Pending.

The query can further limit results by specifying Pro Bono Opportunity Status (typically "Yes: Available"), a Legal Problem Code, a County, or an Organization. See Parameters below in the documentation section.

Data Returned

Data is returned in JSON format (see example below) and includes:

* Case ID
* Case Number
* Legal Problem Code
* Special Legal Problem Code
* County of PB Opportunity
* Case Opportunity Date
* Expertise Level
* PB Opportunity Description
* Email address of the primary advocate on the case

Administrative Setup

Your site may already have an API user and user role. If not, you must create both.

Create a new user role, suggested name "API".
* Give this role only the following permissions: "API Access", "API Search Pro Bono Opportunities", 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, which is available only for users whose user role has the API Access permission (typically only Administrators and the special API user).

Add that path to your agency's base URL to view the page. For example: https://abclegal.legalserver.org/matter/api

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
Not listed here. See Phone API for more information

Pro Bono Opportunities

URL
/matter/api/pro_bono_opportunities/

Permissons Required
API Search Pro Bono Opportunities

Parameters
county – Optional – text
organization – Optional – the Organization Opportunities field includes this organization.
problem – Optional – Numeric code for legal problem code.
status – Optional – text, Yes or No - Pro Bono Opportunity Status field
offset – Optional – Start after N records. (Useful for pagination.)
limit – Optional – How many results to fetch. (Default: 20)

/matter/api/pro_bono_opportunities/?county=King&problem=01&output_format=json

NB: The query must currently include at least the "?status=Yes" parameter. (Ref: 78293).

Examples 

Limit results by both problem code and status:

/matter/api/pro_bono_opportunities/?problem=02&status=Yes&output_format_json
 
Also limit results to only Cook county:

/matter/api/pro_bono_opportunities/?problem=02&status=Yes&county=Cook&output_format_json

Show results for problem code 02 where the matter's opportunity status doesn't matter:

/matter/api/pro_bono_opportunities/?problem=02&output_format_json


The output looks a bit like this: (redacted) 

{
"results": [
{
"id": {
"raw_value": "38998",
"text_value": "38998"
},
"identification_number": {
"raw_value": "16-0012345”,
"text_value": "16-0012345”
},
"legal_problem_code": {
"raw_value": "103271",
"text_value": "60 Homeownership\/Probate"
},
"impact": {
"raw_value": false,
"text_value": “No”
},
"pb_opportunity_status": {
"raw_value": "101157",
"text_value": "Yes: Available Opportunity"
},
"pb_opportunity_summary": {
"raw_value": “Client Seeks Title to Home”,
"text_value": "Client Seeks Title to Home"
"pb_opportunity_note": {
"raw_value": "Client, who is very responsive, seeks title to her home, which is owned by her deceased husband. Client\u2019s husband died in 2015. The deceased has a valid will, which leaves everything, including the property, to Client. A volunteer is needed to assist the client with administering the estate and obtaining title to the property.",
"text_value": "Client, who is very responsive, seeks title to her home, which is owned by her deceased husband. Client\u2019s husband died in 2015. The deceased has a valid will, which leaves everything, including the property, to Client. A volunteer is needed to assist the client with administering the estate and obtaining title to the property."
},
"pb_opportunity_level_of_expertise": {
"raw_value": “Novice”,
"text_value": "Novice”
},
"pb_opportunity_available_date": {
"raw_value": "2016-09-28”,
"text_value": "09\/28\/2016"
},
"pb_opportunity_county": {
"raw_value": “Cook”,
"text_value": “Cook”
},
"email": {
"raw_value": “casehandler@legalserver.org”,
"text_value": “casehandler@legalserver.org”
},
"error": false,
"error_text": "",
"run_time": "0.4125120639801s"
}
  

Testing

With curl:
curl "https://username:password@sitename.legalserver.org/matter/api/pro_bono_opportunities/?status=Yes&limit=20&start=20&output_format=json"

With wget:

wget --http-user=username --http-password=password -qO- "https://username:password@sitename.legalserver.org/matter/api/pro_bono_opportunities/?status=Yes&limit=20&start=20&output_format=json"

With appropriate substitutions for username, password, sitename, and the parameters to search.

Via browser, login with the API user credentials, then visit sitename.legalserver.org/matter/apit/pro_bono_opportunities, with or without additional parameters.