Bank Integration API v1

1. Authentication

North Eye Advisors issues you an API key (test and live). Send it as a bearer token on every request. Keys are shown once at issue time — store them in your secrets vault.

Authorization: Bearer lrs_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

2. Create a case

POST /cases — documents are base64 encoded, 15 MB total per request. Test keys and live keys are fully isolated: a case created with a test key never appears in the live queue. Re-posting the same external_ref with the same key mode returns the existing case instead of creating a duplicate, so retries are safe.

POST https://ne.legalreportstudio.com/api/public/bank/v1/cases

{
  "external_ref": "LOS-2026-114233",
  "applicant_name": "Ramesh Kumar",
  "co_applicant_name": "Sunita Kumar",
  "loan_account_number": "HL00456778",
  "loan_amount": 4500000,
  "case_type": "TSR",
  "branch": "Karol Bagh",
  "state": "Delhi",
  "district": "New Delhi",
  "ulpin": "12345678901234",
  "property_description": "Flat 402, Tower B, Sector 12",
  "contact_name": "A. Sharma",
  "contact_email": "banker@bank.example.com",
  "contact_phone": "9876543210",
  "documents": [
    { "filename": "sale-deed.pdf", "content_type": "application/pdf", "content": "<base64>" }
  ]
}

202 Accepted
{ "external_ref": "LOS-2026-114233", "status": "received" }

3. Track status

GET /cases/{external_ref} — also accepts the case id. Returns the current stage plus a timeline.

GET https://ne.legalreportstudio.com/api/public/bank/v1/cases/LOS-2026-114233

200 OK
{
  "case_id": "0f2c…",
  "external_ref": "LOS-2026-114233",
  "status": "in_review",
  "is_sandbox": false,
  "documents_awaited": false,
  "latest_revision_reason": null,
  "applicant_name": "Ramesh Kumar",
  "loan_account_number": "HL00456778",
  "case_type": "TSR",
  "ulpin": "12345678901234",
  "finalised_at": null,
  "risk_score": {
    "grade": "A",
    "grade_label": "Low risk",
    "score": 82,
    "recommendation": "Proceed",
    "components": [{ "key": "litigation", "label": "Litigation", "score": 74, "weight": 0.2 }],
    "drivers": ["No critical litigation against the owner"]
  },
  "timeline": [{ "status": "allocated", "at": "2026-08-02T09:12:00Z" }]
}

Statuses: received, allocated, in_review, query_raised, finalised. When documents_awaited is true, the analyst is waiting for more papers. Send them to POST /cases/{external_ref}/documents; if the case was already finalised it will be reopened as a revision.

ulpin is the 14-character Bhu-Aadhaar land parcel id, optional on intake and echoed back on every case. risk_score is populated once the report is finalised — grades run AAA to C and are safe to store against the loan file in your LOS.

4. Add documents later

If the case is still open, the documents are attached for review. If it was already finalised, the case is reopened as a revision, a new version of the report is produced, and a report.revised webhook is fired.

POST https://ne.legalreportstudio.com/api/public/bank/v1/cases/LOS-2026-114233/documents

{
  "documents": [
    { "filename": "ec-2015-2026.pdf", "content_type": "application/pdf", "content": "<base64>" }
  ],
  "note": "EC received from SRO"
}

200 OK
{
  "case_id": "0f2c…",
  "external_ref": "LOS-2026-114233",
  "status": "under_review",
  "reopened": true,
  "stored": ["ec-2015-2026.pdf"]
}

5. Download the finalised report

Returns signed links valid for 60 minutes. Responds 409 not_ready until the report is finalised.

GET https://ne.legalreportstudio.com/api/public/bank/v1/cases/LOS-2026-114233/report

200 OK
{ "files": [{ "filename": "TSR-Ramesh-Kumar.pdf", "url": "https://…", "expires_in": 3600 }] }

6. Status callbacks (optional)

Register an https callback and we POST every status change, signed with HMAC-SHA256 over the raw body using your webhook secret.

POST https://bank.example.com/lrs/callback
X-LRS-Event: case.finalised
X-LRS-Signature: sha256=<hex>

{ "event": "case.finalised", "case": { "external_ref": "LOS-2026-114233", "status": "finalised" } }

Events: case.received, case.allocated, case.query_raised, case.finalised, documents.received, report.revised.

7. Verify collateral property (state-routed)

For lenders who prepare the legal report in-house. Every property carries a state and is searched on that state's registry only — Maharashtra on IGR e-Search Index II, Karnataka on Kaveri/Bhoomi. There is no cross-state searching. Several properties in one request are processed together purely for turnaround. States live today: MH (Maharashtra) and KA (Karnataka); full names and ISO codes such as IN-MH are accepted. Any other state returns 400 unsupported_state. New states are added to the same endpoint — the request and response shape never change. Scope cases:create to submit, cases:read to poll.

POST https://ne.legalreportstudio.com/api/public/bank/v1/collateral

{
  "external_ref": "a0X5g000004ABCDEA5",
  "loan_account_number": "HL00456778",
  "borrower_name": "Ramesh Kumar",
  "callback_url": "https://bank.example.com/lrs/collateral",
  "properties": [
    { "reference": "COLL-1", "state": "Maharashtra", "district": "Pune", "taluk": "Haveli",
      "village": "Wagholi", "survey_no": "Gat No. 212/3", "parcel_type": "rural",
      "from_year": "2015", "to_year": "2026" }
  ]
}

202 Accepted
{
  "data": {
    "id": "3d9c…",
    "status": "running",
    "properties": [
      { "reference": "COLL-1", "state": "MH", "stateLabel": "Maharashtra",
        "portal": "IGR e-Search Index II (Government of Maharashtra)", "status": "running" }
    ]
  }
}

A Karnataka property is the same call with "state": "Karnataka", plus hobli, and survey_no holding the survey no. or PID. parcel_type, from_year and to_year are Maharashtra-only. You may send up to 10 properties in one request; each is routed and reported independently.

400 Bad Request — state outside our coverage

{
  "error": {
    "code": "unsupported_state",
    "message": "Supported states today: Karnataka (KA) and Maharashtra (MH).",
    "details": ["properties.0.state: \"Kerala\" is not searched yet."]
  }
}

Poll GET /collateral/{id}. Each property carries its own status, so a finished property is readable while another is still running. Overall status is running, completed, partial or failed.

GET https://ne.legalreportstudio.com/api/public/bank/v1/collateral/3d9c…

200 OK
{
  "data": {
    "status": "completed",
    "properties": [{
      "reference": "COLL-1",
      "state": "MH",
      "status": "completed",
      "findings": {
        "portal": "IGR e-Search Index II (Government of Maharashtra)",
        "holders": ["Ramesh Kumar"],
        "area": { "raw": "0.20.50", "sqm": 2050, "sqyd": 2451.79, "sqft": 22065.98 },
        "encumbrances": [{ "documentNo": "PNE-4412/2019", "date": "2019-06-11", "nature": "Sale Deed" }],
        "mortgages": [],
        "nameMatchScore": 100,
        "nameMatch": "match",
        "riskBand": "low",
        "riskFlags": []
      }
    }]
  }
}

If callback_url is set we POST the completed payload to it, signed the same way as status callbacks (X-LRS-Signature). Properties in states we do not cover are returned as unsupported_state without blocking the rest.

8. Salesforce setup

If your LOS runs on Salesforce, create a Named Credential and call the API from Apex or a Flow.

1. Create a Named Credential with URL https://ne.legalreportstudio.com/api/public/bank/v1, identity type Named Principal or Per User, and the API key stored as an authentication parameter.
2. Build a Flow triggered on Opportunity/Loan_Application__c creation. Use an HTTP Callout action to POST /cases.
3. Store the returned external_ref on the Salesforce record for status polling.
4. Alternatively, register a webhook and update the record from the callback payload.

HttpRequest req = new HttpRequest();
req.setEndpoint('https://ne.legalreportstudio.com/api/public/bank/v1/cases');
req.setMethod('POST');
req.setHeader('Authorization', 'Bearer ' + apiKey);
req.setHeader('Content-Type', 'application/json');
req.setBody(JSON.serialize(payload));
HttpResponse res = new Http().send(req);

A sample case and full payload reference are available on the self-serve integration page that North Eye Advisors will send you.

9. Errors

401 unauthorized      — missing, revoked or invalid API key
403 forbidden         — key lacks the required scope
400 invalid_request   — validation failed (field list included)
404 not_found         — unknown case
409 not_ready         — report not finalised yet
413 payload_too_large — documents exceed 15 MB
429 rate_limited      — slow down and retry

10. Getting started

1. North Eye Advisors sends you a private /integrate/… link. Open it to issue your own test and live API keys.
2. Post a sample case against the test key and confirm the status endpoint.
3. Register your callback URL and store the signing secret.
4. Switch to the live key once your UAT sign-off is complete.