eFiling Eviction Using API for Landloards

Prerequisite

Before you start, make sure to have an account in the staging system. If you don't have one yet, create an eFiling user account by going to Tyler staging site or contact us and we will create one for you. Then email info@uslgalpro.com and request a clienttoken

General Idea

Following are the high level steps to automating eFIling and they are

  1. Authenticate
  2. Search for your case (Only if you are filing into an existing case)
  3. Create Payload
  4. eFile
  5. Check Status
#1 Authenticate

The auth_token returned from this call will be used in all subsequent calls.

Endpoint https://api-stage.uslegalpro.com/v2/{{STATE}}/user/authenticate
Method POST
Header {clienttoken: XXXXX}
Payload
{
  "data": {
    "username": "{{USERNAME}}",
    "password": "{{PASSWORD}}"
  }
}									        
Response
{
  "message_code": 0,
  "item": {
    "auth_token": "fe2c40a7-68dc-476c-acf8-b850fb72e7c0/XXXXX/992af94b-fff2-4e06-a087-34dfc0e3e1542"
  }
}									        
#2 Search for case (Only if you are filing into an existing case)
The case_tracking_id returned from this call will be used to file into the case
Endpoint https://api-stage.uslegalpro.com/v2/{{STATE}}/search_case?jurisdiction={{JURISDICTION}}&case_number={{CASE_NUMBER}}
Method GET
Header {authtoken: fe2c40a7-68dc-476c-acf8-b850fb72e7c0/XXXXX/992af94b-fff2-4e06-a087-34dfc0e3e1542}
Response
{
  "message_code": 0,
  "items": [
    {
      "case_tracking_id": "6eefc566-217e-4778-9d63-38650903dbe5",
      "jurisdiction": "refugio:276dc",
      "case_category": "131370",
      "case_number": "2017-02-12417",
      "case_title": "IN THE MATTER OF THE EVICTION OF JAMES DEAN AND ERICA SMITH",
      "case_type": "16101",
      "case_category_display": "Civil - Eviction",
      "jurisdiction_display": "Baltimore County - District Clerk",
      "case_type_display": "Eviction",
      "link": {
        "case_detail": {
          "method": "GET",
          "link": "https://api-stage.uslegalpro.com/v2/tx/case/6eefc566-217e-4778-9d63-38650903dbe5",
          "header": {
            "clienttoken": "XXXXX"
          }
        }
      }
    }
  ],
  "count": 1
}
									        
#3 Create Payload
A JSON payload serves as a blueprint containing all the necessary information for eFiling in the court system. Creating this blueprint may require time, especially when filing in different jurisdictions or handling various types of cases. When you eFile, the system relies on internal codes specified in the JSON payload to determine details such as case category, type, party, and document. Accuracy in identifying these codes is essential. As these codes may undergo frequent changes, it is crucial to establish a process that simplifies the updating of codes when necessary.

File into existing case example JSON payload

{
  "data": {
    "reference_id": "DRAFT128611111",
    "case_tracking_id": "6eefc566-217e-4778-9d63-38650903dbe5",
    "payment_account_id": "b471e862-9c87-4959-8081-5da1841c6698",
    "filer_type": "40467",
    "filing_type": "EFileAndServe",
    "filings": [
      {
        "code": "131832",
        "doc_type": "197901",
        "file": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "file_name": "ANSWER.pdf",
        "description": "Answer/Response"
      }
    ]
  }
}
        

#3.1 File a new case JSON payload (Maryland Landlord Tenant Cases)

Here is an example JSON payload that you need to submit when starting a new landlord-tenant case in Maryland using a batch. If you have 50 in a batch, then you will call this API 50 times with different batch_sequence and reference_id. Here's the cleaned HTML for the table:
{
  "data": {
    "batch_id": "MYBATCH9",
    "batch_size": "50",
    "batch_sequence": "1",
    "reference_id": "REF121212",
    "jurisdiction": "dc:8thbalto",
    "payment_account_id": "04bcb030-77e0-46b1-b071-fee294a3bf91",
    "filing_attorney_id": "ed65bf56-9f73-41f9-a1cd-05dfa7bd6beb",
    "case_parties": [
      {
        "is_business": "true",
        "business_name": "Logix DS",
        "city": "Flower Mound",
        "address_line_1": "625 Heritage Ln",
        "phone_number": "18472208005",
        "state": "TX",
        "id": "Party_900975933",
        "type": "5413",
        "zip_code": "75022",
        "group_id": "GRP1"
      },
      {
        "is_business": "false",
        "city": "Flower Mound",
        "address_line_1": "625 Heritage Ln",
        "last_name": "Bhattarai",
        "phone_number": "18472208005",
        "state": "TX",
        "id": "Party_419922473",
        "type": "5420",
        "first_name": "Sudeep",
        "zip_code": "75022"
      }
    ],
    "filings": [
      {
        "code": "26638",
        "file": "base64://JVBERi0xLjQNCiXDosOjw4/Dkw0KNSAwIG...",
        "optional_services": [
          {
            "quantity": "1",
            "code": "26838"
          }
        ],
        "file_name": "sample.pdf",
        "description": "Complaint/Petition - Landlord Tenant - Personal Service",
        "doc_type": "7712"
      }
    ],
    "case_category": "7",
    "case_type": "5442",
    "filing_type": "EFileAndServe",
    "filing_party_id": "Party_900975933"
  }
}
      
Definitions

batch_id

Provide a unique batch id

batch_sequence

Indicate the sequence of envelopes that you are submitting. For example, 1, 2 till 50 if batch size is 50

batch_size

Specify the size of this batch. e.g 50

reference_id

Ensure a unique number is always provided per API call

jurisdiction

Specify the jurisdiction where the filing will occur

payment_account_id

This is the internal ID of the payment account created in your Tyler account for paying court fees. You can retrieve the list of payment accounts by calling the following endpoint with your auth token: {{host}}/v2/{{state}}/payment_accounts.

filing_attorney_id

This is the internal ID of the attorney associated with your Tyler account who is filing the documents. You can retrieve the list of attorneys by calling the following endpoint with your auth token: {{host}}/v2/{{state}}/firm/attorneys.

is_business

Set this to true if the case party is a business. If true, only enter the business_name and leave out first_name, middle_name, and last_name.

case_parties > id

For initial filings, always create an id that starts with "Party_" followed by a random number (e.g., Party_23232323)

case_parties > group_id

This applies only to the filing party. It represents the grouping of petitioners. You can assign any value for group_id. For instance, if an eviction company manages two apartment complexes for different clients, with the first apartment owned by John and Jane and the second by Harry and Jessy, John and Jane would be group1, and Harry and Jessy would be group2. If filing multiple evictions in one batch, use group_id to help the court identify and allocate hearing dates for the groups.

filings (code, doc_type, case_category, case_type)

These values vary by county. You should retrieve and store these values for each county you are filing into. Note that the staging environment will have different values than the production environment. You can use the following process to get this value and store it in your system. There is another way to get these values using our eFiling UI and If you want to learn how, we can meet.

1. Install the ModHeader Chrome extension - Go to https://chrome.google.com/webstore/detail/modheader-modify-http-hea/idgpnmonknjnojddfkpgkljpfnnfcklj?hl=en - Install the extension. - Set the header clienttoken to <your_client_token>.

2. Install the JSONVue Chrome extension - Visit https://chrome.google.com/webstore/detail/jsonvue/chklaanhfefbnpoihckbnefhakgolnmc - Install the extension.

3. Browse the specified link and navigate as needed and get the code and store it - https://api.uslegalpro.com/v2/md/code/jurisdiction_codes?is_initial=true

filing_party_id

It is the case part id (from step 4), who is filing, typically petitioner

#4 eFile
Take the payload generated from above and execute the following
Endpoint https://api-stage.uslegalpro.com/v2/{{STATE}}/efile
Method POST
Header {authtoken: fe2c40a7-68dc-476c-acf8-b850fb72e7c0/XXXXX/992af94b-fff2-4e06-a087-34dfc0e3e1542}
Payload Payload from step #5
Response
{
  "message_code": 0,
  "item": {
    "filings": [
      {
        "code": "131832",
        "id": "cca449c8-a08b-42f6-bb37-e3fe17f44519",
        "status": "submitting"
      }
    ],
    "id": "260281",
    "case_tracking_id": "6eefc566-217e-4778-9d63-38650903dbe5"
  }
}
        
#5 Check status

#5.1 Batch Filing Status Check (Only applicable to Maryland)

Endpoint https://api-stage.uslegalpro.com/v2/md/batch/{{BATCH_ID}}
Method GET
Header {authtoken: fe2c40a7-68dc-476c-acf8-b850fb72e7c0/XXXXX/992af94b-fff2-4e06-a087-34dfc0e3e1542}
Response
{
  "message_code": 0,
  "item": {
    "id": "4072",
    "status": "Submitted",
    "size": "2",
    "envelope_count": "2",
    "envelopes": [
      {
        "id": "229643",
        "sequence": "1",
        "jurisdiction": "dc:8thbalto",
        "envelope_fee": "86.93",
        "filings": [
          {
            "id": "b983cf38-b111-4eae-bcae-6e01d747b421",
            "code": "26638"
          },
          {
            "id": "b983cf38-b111-4eae-bcae-6e01d747b421",
            "code": "26638"
          }
        ],
        "submitter_name": "EFILE ADMIN"
      },
      {
        "id": "229643",
        "sequence": "1",
        "jurisdiction": "dc:8thbalto",
        "envelope_fee": "86.93",
        "filings": [
          {
            "id": "5e13c387-67b4-40d2-9962-2a35232b18c4",
            "code": "26638"
          },
          {
            "id": "5e13c387-67b4-40d2-9962-2a35232b18c4",
            "code": "26638"
          }
        ],
        "submitter_name": "EFILE ADMIN"
      }
    ]
  }
}
        

#5.2 Individual Envelope Status Check

Endpoint https://api-stage.uslegalpro.com/v2/{{STATE}}/envelope/{{ENVELOPE_ID}}?fields=status,filings(original_document,stamped_document,reviewer_comment,status_reason)
Method GET
Header {authtoken: fe2c40a7-68dc-476c-acf8-b850fb72e7c0/XXXXX/992af94b-fff2-4e06-a087-34dfc0e3e1542}
Response
{
  "message_code": 0,
  "item": {
    "status": "accepted",
    "filings": [
      {
        "stamped_document": "https://ezstage.s3.us-east-2.amazonaws.com/20fafab4-7583-40eb-a7ba-c8688871f61e?response-content-disposition=attachment%3B%20filename%3DANSWER.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20231121T085706Z&X-Amz-SignedHeaders=host&X-.....",
        "reviewer_comment": "",
        "status_reason": "",
        "original_document": ""
      }
    ]
  }
}