Build LodgeWise agents into your own platform

Organization

Your agency tenant. Admins build workflows (each defines an agent) in the admin console.

API keys

A publishable key (pk_…, safe in the browser) and a secret key (sk_…, server-side only, full API).

Nominated domain

The browser origins allowed to embed your chat, e.g. visachief.com. Set in the Integration tab.

Agent

The persona attached to a workflow. Assigning an agent = starting that workflow for a client.

Client

One of your end-customers, identified by your own externalId.

Application = Session

The same object: a client’s case + its live chat. applicationId and sessionId are the same id.

All REST calls use Authorization: Bearer <key>. Server-to-server calls use your secret key. Browser code uses the publishable key or a short-lived wsToken returned when you create an application.

curl https://www.lodgewise.ai/api/v1/overview \
  -H "Authorization: Bearer sk_live_xxx"

1. 1Create a client — Idempotent on your externalId.
2. 2Create an application — Pick a workflow (agent), link the clientId, prefill answers + context. You get a wsToken.
3. 3Connect the chat — WebSocket or the SDK widget — your client talks to the agent on your site.
4. 4Post documents & info — As the client supplies them; the agent validates and analyses each.
5. 5Take payment — The deep review / analysis runs after payment.
6. 6Monitor & control — From your dashboard; cancel / pause / refund as needed.

Register prospects (individual or corporate) from your own site and work them through the pipeline NEW → CONTACTED → QUALIFIED → CONTRACT_SENT → CONTRACT_SIGNED → WON / LOST. Leads with an email are nurtured agentically — the agent composes & sends white-label follow-ups on a gentle cadence (or on demand). Send a contract to e-sign, then convert (close-won) to create the client and start an agent.

curl -X POST https://www.lodgewise.ai/api/v1/leads \
  -H "Authorization: Bearer sk_live_xxx" -H "content-type: application/json" \
  -d '{ "kind": "corporate", "company": "Acme Pty Ltd", "name": "Jane Doe",
        "email": "[email protected]", "interest": "visa-assessment",
        "valueCents": 250000, "source": "website", "externalId": "lead-123" }'
# -> 201 { "id", "stage": "NEW", "status": "OPEN", "created": true }

# Send a contract, then close-won
POST /api/v1/leads/:id/contract  { "title": "Service agreement", "body": "Full terms…" }
  -> { "signUrl": "https://www.lodgewise.ai/sign/<token>" }
POST /api/v1/leads/:id/convert   { "workflow": "visa-assessment", "startApplication": true }
  -> { "ok": true, "clientId", "applicationId", "reference" }

Generate the official departmental lodgement forms for a visa, pre-filled from applicant data your site already collected. One call registers the applicant as a lead (idempotent on your externalId), fills every fillable form, and delivers the PDFs — tokenized download URLs when generation finishes fast, otherwise emailed to the applicant from your own domain (white-label).

curl -X POST https://www.lodgewise.ai/api/v1/forms/generate \
  -H "Authorization: Bearer sk_live_xxx" -H "content-type: application/json" \
  -d '{ "visa": "visitor-600",
        "applicantData": { "familyName": "Doe", "givenNames": "Jane",
                           "email": "[email protected]", "mobile": "+61400000000" },
        "externalId": "vc-user-991", "lead": { "source": "visachief" } }'

# Fast → the filled PDFs, by URL:
# 200 { "delivery": "url", "leadId", "visa": { "slug", "name" },
#       "forms": [ { "formNumber": "1419", "formTitle": "…",
#                    "url": "https://…/download?token=…", "expiresInDays": 7 } ] }

# Slow (or "deliver": "email") → 202; the applicant is emailed the links:
# 202 { "delivery": "email", "leadId", "email", "message": "…will be emailed when ready." }

curl -X POST https://www.lodgewise.ai/api/v1/clients \
  -H "Authorization: Bearer sk_live_xxx" -H "content-type: application/json" \
  -d '{ "externalId": "your-user-123", "name": "Jane Doe",
        "email": "[email protected]", "metadata": { "country": "IN" } }'
# -> 201 { "clientId", "externalId", "name", "email" }

Creating an application assigns the workflow’s agent to a client and opens a live chat.applicationId andsessionId are the same id.

POST /api/v1/applications
  { "agent": "visa-assessment",          // workflow slug (alias: "workflow")
    "clientId": "cl_...",                 // optional — link to a client
    "externalUserId": "your-user-123",    // optional
    "answers": { "primary_goal": "Skilled migration" },  // prefill — agent won't re-ask
    "context": "Software engineer, offshore.",
    "metadata": { "ref": "ACME-9981" } }
  -> { "applicationId", "sessionId", "clientId", "reference",
       "wsToken",                         // connect the chat with this
       "agent": { "name", "role" },
       "workflow": { "slug", "name", "definition" } }

The list returns, per application: status { state, label, progress, paused, cancelled },paid,payment, file + open-issue counts, and the linked client.

Upload as multipart/form-data (fieldfile; optionalfieldKey). The agent opens, validates and analyses it, then replies in the chat. Accepts PDF, PNG, JPEG, DOC, DOCX, TXT (≤25 MB).

curl -X POST https://www.lodgewise.ai/api/v1/applications/$ID/files \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "[email protected]" -F "fieldKey=doc_passport"
# -> 201 { "id", "filename", "sizeBytes", "fieldKey" }

Run the deep agentic review/analysis for an application. This bills your agency the $100 per-application review fee (charged once per application, to your card on file) and queues the review. It's separate from your subscription & credits.

POST /api/v1/applications/:id/review     Authorization: Bearer sk_live_xxx
  -> { "ok": true, "feeCents": 10000, "charged": true, "lifecycleState": "DEEP_REVIEW" }

Optional — if you want LodgeWise to collect a payment from your end-client, create an intent and complete it with Stripe.js on your site (real mode), or call/payment/confirm in sandbox mode.

POST /api/v1/applications/:id/payment-intent
  -> { "intentId", "clientSecret", "publishableKey", "amountCents", "currency", "mock" }
GET  /api/v1/applications/:id/payment
  -> { "status": "PENDING|SUCCEEDED|FAILED|REFUNDED|NONE", "paid", "amountCents" }
POST /api/v1/applications/:id/refund   { "reason": "client withdrew" }
  -> { "ok": true, "status": "REFUNDED", "refundId" }

Build your own agency dashboard from these, or sign in to the admin console (already scoped to your org).

GET /api/v1/overview
  -> { "applications", "clients",
       "byStatus": { "INTAKE": 4, "DEEP_REVIEW": 2 },
       "payments": { "succeeded", "totalCents" } }

Your client chats with the assigned agent on your own page. Three ways:

Drop-in widget

<div id="chat" style="height:560px;max-width:420px"></div>
<script src="https://www.lodgewise.ai/embed/lodgewise-v1.js"></script>
<script>
  Lodgewise.mountChat('#chat', {
    publishableKey: 'pk_live_xxx',
    workflow: 'visa-assessment',
    title: 'Visa Assessment', accent: '#2563EB',
    answers: { primary_goal: 'Skilled migration' },   // prefill
    context: 'Software engineer, offshore.'
  });
</script>

Headless client (your own UI)

const session = await Lodgewise.createSession({
  publishableKey: 'pk_live_xxx', workflow: 'visa-assessment',
  externalUserId: 'your-user-123',
  answers: { citizenship: 'India' }, context: 'Software engineer, offshore.'
});
session.on('status',  (s) => {/* 'thinking' | 'connected' */});
session.on('event',   (f) => { if (f.event === 'delta')   append(f.content);      // live tokens
                               if (f.event === 'options') showButtons(f.options); }); // tappable
session.on('message', (text, frame) => render(frame.html || text));               // final (HTML-ready)
session.connect();
session.send('I want to apply for a skilled visa');
await session.uploadFile(fileInput.files[0], 'doc_passport');   // upload from the browser

WS Raw WebSocket

wss://www.lodgewise.ai/ws/v1/sessions/:id?token=<wsToken>

// frames you receive
{ "type": "status",  "status": "connected" | "thinking" }
{ "type": "event",   "event": "delta",   "content": "partial text" }   // streaming
{ "type": "event",   "event": "options", "options": ["Yes","No"] }     // tappable quick-replies
{ "type": "message", "role": "ASSISTANT", "content": "final reply", "html": "<p>…</p>" }
// send:  { "text": "..." }

Replies arrive as sanitized HTML (tables, lists, links) with optional Mermaid diagrams and tappable options — so they render cleanly and your client never sees raw Markdown.

• ✓ Add your domain(s) to allowed origins — the chat only connects from there.
• ✓ The agent represents your brand; it never mentions LodgeWise. Set the title/accent in the widget.
• ✓ The agent stays strictly on your workflow — capturing, validating and analysing the documents your process requires.

When you create a customer, LodgeWise sends a welcome email from your own domain(e.g. [email protected]), DKIM-signed so it lands in inboxes. Replies come back to the same address (and into your LodgeWise inbox). Set this up once in the admin Integration → Custom sending domain tab.

One-time setup

1. Enter your From address (e.g. [email protected]) in the Integration tab.
2. Add the two DNS records it shows you — a DKIM TXT record and an SPF entry (a:mail.lodgewise.ai).
3. Click Verify DNS. Once verified, all welcome emails send from your domain.

Until verified, welcome emails fall back to a LodgeWise address so nothing is lost.

Welcome email on customer creation

POST /api/v1/clients sends the welcome email automatically when the customer has an email. Customize the template (subject + HTML, with {{name}} {{email}} {{org}} placeholders) in the Integration tab, or skip per-call with sendWelcome: false.

POST /api/v1/clients      Authorization: Bearer sk_live_xxx
  { "externalId": "user-123", "name": "Jane Doe", "email": "[email protected]",
    "sendWelcome": true }          // default true; set false to suppress
  -> 201 { "clientId", "name", "email",
           "welcome": { "sent": true, "from": "\"VisaChief\" <[email protected]>" } }

The response's welcome object tells you whether it was sent and from which address (or the error if your domain isn't verified yet).

• ! Never put a secret key (sk_…) in a webpage — browser code uses only the publishable key or a wsToken.
• ! Publishable keys + the chat WebSocket only work from your allowed origins.
• ! wsTokens are short-lived and scoped to a single application/session.
• ! Rotate or revoke keys any time in the admin Integration tab.