# Lawneu Advocate App REST API

Base URL:

```text
https://page.law.indias.cloud/api/v1
```

These endpoints match `lawneu-advocate-app/app/src/main/java/com/example/data/ApiService.kt`.

## Auth

Use the project master key for these app API calls:

```text
X-Master-Key: YOUR_MASTER_KEY
```

or:

```text
Authorization: Bearer YOUR_MASTER_KEY
```

Most advocate-owned endpoints should also send `advocate_id` in the query/body.

The app login itself can stay on Firebase. PHP `/auth/login` and `/auth/verify` are optional development helpers and are not required for production login.

### Optional Dev OTP Helper

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"mobileNumber":"919876543210","countryCode":"IN","dialCode":"+91"}'
```

### Optional Dev OTP Verify

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"mobileNumber":"919876543210","otpCode":"123456","deviceToken":"android-device-token"}'
```

The optional helper response returns a Bearer token for local/dev testing:

```json
{
  "success": true,
  "token": "access-token",
  "userRole": "ADVOCATE",
  "registrationDate": "2026-06-19T08:00:00Z"
}
```

## Advocates

### Check Subdomain

```bash
curl "https://page.law.indias.cloud/api/v1/subdomains/check?subdomain=adv-sharma"
```

### Create Website

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/create" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subdomain":"adv-sharma","advocateName":"Adv. Sharma","tagline":"Dedicated to Justice","bio":"Civil and property matters","experience":"5+ Years","court":"District Court","education":"LL.B","approach":"Clear advice","countryCode":"IN","countryName":"India","state":"Delhi","city":"New Delhi","county":"Central Delhi","defaultCurrency":"INR","contactPhone":"+91 98765 43210","contactEmail":"adv@example.com","contactAddress":"Delhi","createMailAccount":true}'
```

Create response includes the advocate-scoped linked mail account when created:

```json
{
  "success": true,
  "message": "Advocate website created",
  "advocate_id": 3,
  "subdomain": "adv-sharma",
  "url": "https://adv-sharma.lawneu.in",
  "countryCode": "IN",
  "countryName": "India",
  "currencyCode": "INR",
  "mail_account_linked": true,
  "mail_account_email": "adv-sharma@zeetx.com",
  "mail_scope": "advocate_website_only"
}
```

The linked mail account is metadata for Lawneu-wrapped mail access. There is no public mail endpoint and no domain-wide mailbox access. Future mail reads/replies must match the `advocate_id` and the linked email account for that advocate website.

```bash
curl "https://page.law.indias.cloud/api/v1/advocates?countryCode=IN&currencyCode=INR&specialty=civil"
```

```bash
curl "https://page.law.indias.cloud/api/v1/advocates/1"
```

```bash
curl "https://page.law.indias.cloud/api/v1/advocates/profile" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -G --data-urlencode "advocate_id=3"
```

### Update Profile

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/update" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"name":"Advocate Arjun Mehta","tagline":"Clear legal guidance","bio":"Updated bio","experience":"8+ Years","countryCode":"IN","countryName":"India","state":"Delhi","city":"New Delhi","county":"Central Delhi","defaultCurrency":"INR","contactPhone":"+91 98765 43210","contactEmail":"adv@example.com","bankAccount":"1234567890","ifsc":"HDFC0000001","upi":"advocate@upi","isAcceptingBookings":true}'
```

### Country And Currency Fields

Supported country/currency fields are accepted on advocate, case, payment, receipt, payout, and AI draft APIs:

```json
{
  "countryCode": "IN",
  "countryName": "India",
  "state": "Delhi",
  "city": "New Delhi",
  "county": "Central Delhi",
  "currencyCode": "INR"
}
```

Aliases are also accepted: `country`, `country_code`, `currency`, `currency_code`, `stateName`, `cityName`, and `countyName`.

## Bio Links And Financials

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/bio-links" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"bioLinks":[{"title":"Website","url":"https://example.com"}]}'
```

```bash
curl "https://page.law.indias.cloud/api/v1/advocates/financials" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

## Services And Gallery

### List Services

```bash
curl "https://page.law.indias.cloud/api/v1/advocates/services?advocate_id=3" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

### Add Or Edit Service

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/services" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"title":"Civil Law","description":"Civil disputes and property matters","iconUrl":"https://example.com/icon.png"}'
```

Pass `id` in the same payload to edit an existing service.

### Delete Service

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/services" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"id":10,"action":"delete"}'
```

### Get Gallery URLs

```bash
curl "https://page.law.indias.cloud/api/v1/advocates/gallery?advocate_id=3" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

### Update Gallery URLs

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/advocates/gallery" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"gallery_urls":["https://example.com/photo1.jpg","https://example.com/photo2.jpg"]}'
```

## Cases

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/initiate" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientName":"Ravi Kumar","advocateId":"1","title":"Property consultation","category":"Civil","initialDescription":"Need advice","countryCode":"IN","countryName":"India","state":"Delhi","city":"New Delhi","county":"Central Delhi","currencyCode":"INR","agreedRetainerAmount":2500}'
```

```bash
curl "https://page.law.indias.cloud/api/v1/cases/my-cases" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/CASE-1234/link-statute" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actCode":"BNS","sectionNumber":"420","titleText":"Cheating"}'
```

## Bare Acts Sync

```bash
curl "https://page.law.indias.cloud/api/v1/bare-acts/sync?last_updated=0"
```

## Payments

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/payments/initiate" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advocate_id":3,"caseId":"CASE-1234","amount":500,"currencyCode":"INR","countryCode":"IN","countryName":"India","transactionPurpose":"Consultation","paymentGatewayMode":"UPI"}'
```

### Payment Detail And Status

```bash
curl "https://page.law.indias.cloud/api/v1/payments/detail?txnReferenceId=TXN-123" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

```bash
curl "https://page.law.indias.cloud/api/v1/payments/status?txnReferenceId=TXN-123" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

### Update Payment Status

Use this after payment gateway callback/manual confirmation.

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/payments/update-status" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"txnReferenceId":"TXN-123","status":"SUCCESS"}'
```

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/payments/payout" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payoutAmount":500,"currencyCode":"INR","countryCode":"IN","countryName":"India","targetPayoutType":"UPI","upiId":"advocate@upi"}'
```

## Case Payment Ledger And Receipts

### Get Case Payment Status

```bash
curl "https://page.law.indias.cloud/api/v1/cases/payment?caseId=CASE-1234" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

### Update Case Quoted/Paid Amount

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/payment" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE-1234","paymentTotal":50000,"paymentPaid":20000,"state":"Delhi","city":"New Delhi","county":"Central Delhi","currencyCode":"INR","countryCode":"IN","countryName":"India"}'
```

Response includes:

```json
{
  "success": true,
  "caseId": "CASE-1234",
  "paymentTotal": 50000,
  "paymentPaid": 20000,
  "paymentPending": 30000,
  "paymentStatus": "PART_PAID",
  "currency": "INR",
  "currencyCode": "INR",
  "countryCode": "IN",
  "countryName": "India"
}
```

### List Receipts

```bash
curl "https://page.law.indias.cloud/api/v1/cases/receipts?caseId=CASE-1234" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

### Add Receipt

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/receipts" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE-1234","label":"Retainer Deposit Received","amount":20000,"currencyCode":"INR","countryCode":"IN","countryName":"India","date":"2026-06-19","method":"UPI","note":"Client advance"}'
```

## Case Pairing And Files

### Create Client Pairing Code

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/pairing" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"create","caseId":"CASE-1234","clientName":"Ravi Kumar","clientMobile":"919876543210","clientEmail":"client@example.com"}'
```

### Read Or Unlink Pairing

```bash
curl "https://page.law.indias.cloud/api/v1/cases/pairing?pairingCode=CASE-1-RAVI" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/pairing" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"unlink","pairingCode":"CASE-1-RAVI"}'
```

### Case File Metadata

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/cases/files" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE-1234","fileName":"petition.pdf","storagePath":"https://example.com/petition.pdf","uploadedBy":"ADVOCATE"}'
```

```bash
curl "https://page.law.indias.cloud/api/v1/cases/files?caseId=CASE-1234" \
  -H "X-Master-Key: YOUR_MASTER_KEY"
```

## Internal P2P Video Calls

P2P call/session handling is wrapped by the Lawneu app/backend flow. Direct call-room endpoints and raw P2P room URLs are not published in the public app API docs or Postman collection.

## AI Draft

```bash
curl -X POST "https://page.law.indias.cloud/api/v1/ai/generate-draft" \
  -H "X-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"draftType":"LEGAL_NOTICE","statePartiesDetail":"Client vs opposite party facts","specificClausesOverride":"Add payment demand clause","countryCode":"IN","countryName":"India"}'
```

## Current Provider Notes

- Production login can remain Firebase-based; API access uses the project master key.
- PHP `/auth/login` and `/auth/verify` are optional development helpers and are not required.
- OTP uses `LAWNEU_APP_TEST_OTP` when configured, otherwise `123456`.
- Payments and payouts save records. Payment status supports `PROCESSING`, `SUCCESS`, `FAILED`, `CANCELLED`, and `REFUNDED`.
- Updating a payment to `SUCCESS` also updates the linked case payment ledger and adds a receipt when `caseId` is supplied.
- Country/currency values are stored on advocates, cases, payments, payouts, receipts, calls, and AI drafts. If omitted, case/payment APIs inherit from the advocate or case and default to `IN`/`India`/`INR`.
- P2P calls are app-wrapped and not exposed as direct public API samples.
- AI draft generation uses the Lawneu-wrapped Open WebUI provider when configured; otherwise it returns a built-in template fallback.
- Linked mail accounts are advocate-website scoped only. The app should not request raw mail-provider/domain access.