> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextlevelmca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running an AI workflow on top

> What an AI agent can do with the platform: answer the phone, chase stuck deals, pick lenders from analysed statements, and tell the merchant when an offer lands.

The platform was built so an agent can run a deal desk: notice what changed, decide what to do, act, and hand off to a person where judgement is needed. Notifications are the triggers, the API is how it reads and acts, and lender matching is the recommender, so the agent never has to know your lenders' criteria; the workspace already does. For the conversational version, where a team member asks Claude or ChatGPT to do the same things, see [AI assistants](/developers/mcp/overview).

## What it looks like

**An unknown number calls.** The agent looks the number up, finds Dana Rivera, owner of ACME Plumbing, with a deal in *Submitted*, and puts that on the rep's screen before they pick up: which two lenders it went to, when, and that nothing has come back yet.

**Deals get stuck.** Every morning the agent lists deals that have sat in *Missing docs* for more than five days, drafts a follow-up for each in the rep's voice naming the exact items still outstanding, and leaves them as tasks. The rep sends the ones they like.

**Statements come in.** When a merchant uploads bank statements and the analysis finishes, the agent re-runs lender matching on the bank-verified numbers, keeps the lenders that clear every gate with nothing unknown, and submits to the top three, leaving a note on the deal explaining why those three. Lenders where something is still unknown go to the rep with the missing item named.

**An offer lands.** The agent compares payback and daily payment against the positions found in the statements and writes the comparison up as a task for the rep. Once the rep picks the primary offer, the agent sends the merchant their portal link so they can see it and upload whatever the lender still needs.

**An advance is ready to renew.** When an advance crosses the renewal threshold, the agent opens the renewal deal on the same business and the loop starts again.

## Guardrails

* **Roles and scopes.** Give the agent's key only what its job needs. A reader that summarises deals needs no write scope at all, and a missing scope comes back as a clear "not allowed here" rather than a silent failure. Prefer the `manager` role; it cannot change settings or the team.
* **Nothing sends twice.** Every action that sends something, whether a submission, a document request or a portal link, carries an idempotency key taken from the notification that triggered it, so an agent that crashes and restarts cannot email a lender twice.
* **Pipeline rules apply.** A stage move the board would refuse is refused for the agent too, with the same message a rep would see.
* **People approve sends.** Submit automatically only where matching says nothing is unknown; route the rest, and every offer decision, to a rep. Assistants working through chat are told which tools send real messages and confirm before using them.
* **Everything is traceable.** Every action is attributed in the activity log, and every request carries an id that support can trace.

## For developers

The story above as a sequence of calls. Verification and retry rules for the triggers are in [Notifications](/developers/guides/webhooks).

| Trigger | Read | Act |
| - | - | - |
| Inbound call | `GET /v1/people?phone=%2B12125550123`, then `GET /v1/people/{id}` for their businesses and deals, then `GET /v1/deals/{id}?include=offers,submissions,documents` | Show it to the rep; `POST /v1/people` when nothing matches |
| Morning sweep | `GET /v1/deals?phase=preoffer&stale_days=5` (stage ids from `GET /v1/pipeline`) | `POST /v1/deals/{id}/tasks` with the drafted follow-up |
| `deal.created` | `GET /v1/deals/{id}/lender-matches?view=recommended`; check `meta.deal.missing_fields` and coverage in `GET /v1/deals/{id}/statement-analysis` | `POST /v1/deals/{id}/document-requests` with `channel: "sms"` and `Idempotency-Key: <event id>` |
| `statement.analyzed` | Re-run lender matches; keep `auto_eligible: true`, sort by `score` and `approval_rate` | `POST /v1/deals/{id}/submissions` with the top three `lender_ids` and `Idempotency-Key: <event id>`; `POST /v1/deals/{id}/notes` with the reasoning |
| `offer.received` | `GET /v1/deals/{id}/offers` and the positions from statement analysis | `POST /v1/deals/{id}/tasks` with the comparison; `POST /v1/offers/{id}/primary` only when the rule is explicit |
| `offer.primary_changed` | | `POST /v1/deals/{id}/portal-link` with `send_via: "sms"` |
| `advance.renewal_ready` | `GET /v1/advances/{id}` | `POST /v1/deals/{id}/renewal` |

`GET /v1/deals/{id}?include=business,people,offers,submissions,documents,activity` returns the full picture in one call. The limit is 300 requests a minute per credential, so fan out across deals with a queue and honour `Retry-After` on a `429`. A refused stage move is `400` with `code: "stage_rule"`. Log `X-Request-Id` with every action so a wrong send can be traced.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.