Deal lifecycle

Where a deal comes from

You never create a deal. A business applies on the marketplace, the request is matched against your lane, and the deal is handed to you. There is no create endpoint on this API, and the absence is deliberate rather than an omission.

Three ways it can reach you, and the right one depends on the lane rather than on a house standard:

We push it to you. Register an endpoint and the complete deal object arrives by POST the moment it is routed, and again on every change. Nothing to poll.
You pull it. GET /deals lists what is routed to you and GET /deals/{ref} returns one in full. Some teams prefer a schedule to an inbound endpoint.
We post into your own intake API. If you already run an application API that accepts a business and returns indicative figures, we build and maintain the adapter and send deals straight into it. Nothing is built on your side beyond giving us the schema and a sandbox key.

Before documents, and after

A deal reaches you twice over, and the two moments carry different things. Reading the first as if it were the second is the usual cause of a stalled integration.

	At routing, before documents	After the client uploads
Business and contact	Present	Unchanged
Company identity	Registered name, company number, legal form, status, incorporation date and address, from the register where that market answers. `market.registry.status` says which case you are in, and the per-market pages say what each market can answer	Unchanged
Figures	What the applicant told us, as a band with a midpoint, plus whatever the register could add	The parsed figures from the statements take over, and the basis on each number says so
Statements	`statements.has_statements` is false	Provider, months covered, average inflow and outflow, and the files themselves
Documents	Empty, and `GET /deals/{ref}/documents` answers with an empty list	Every file with its type, size, upload time and a signed link
What you can post	An indicative offer	A firm offer

You do not have to wait for the second moment to engage. An indicative figure on the first one is what puts you in the comparison at all; the firm offer follows once the statements are in. If you would rather ask for a document yourself, request it by type and the client sees it on their checklist.

Every deal carries channel: the brand the client applied through, with its name and domain. Address the client by it, in every message and document.

A deal has two status fields. status is the marketplace state of the deal itself. lender_status is your own position on it, and only you change it.

The path

A deal, end to endEvery state a deal passes through. The colour of a node says who moves it, and the code beside one is the event that fires when it does.

RoutedCapvantdeal.created
Matched to your lane and pushed to your endpoint in full. It also shows in GET /deals if you prefer to pull.
In reviewYouin_review
POST /deals/{ref}/status
You report it as soon as the deal is with a person or a model on your side. The applicant sees that someone is looking.
Indicative offerYouoffer_made
POST /deals/{ref}/indicative-offer
Non-binding figures. They render in the comparison immediately, marked indicative. This is what puts you in the comparison at all.
Statements arriveThe clientrequest.fulfilled
The client uploads bank statements once. They reach you with signed download links, and the parsed figures take over from the applicant bands.
Firm offerYouoffer_made
POST /deals/{ref}/firm-offer
Binding terms. It supersedes your indicative offer in place, and firm figures outrank indicative ones.
AcceptedThe clientoffer.accepted
The applicant accepts in the marketplace. Completion starts on one of the two lanes.
Fundedfunded
POST /deals/{ref}/status
Carries the completed amount. That is the figure reconciliation uses.
Declineddeclined
POST /deals/{ref}/status
A reason is required. Decline reasons feed routing, so a lane stops seeing the shape it declines.

Capvant moves itYou move itThe client moves it

Completion, two lanes

Acceptance is where integrations differ, so pick the lane that matches how you want the client to experience the close out. Both end in the same place: you report the outcome.

Completion, two lanesAcceptance is where integrations differ. Both lanes end in the same place: you report the outcome.

White label

The client never leaves the brand they applied through.

Attach your agreementYou
PUT /deals/{ref}/agreement
The PDF, base64, up to 15 MB. It renders in the client’s completion view like any other document.
Read the payout accountThe clientdeal.account_submitted
Before the client confirms it, GET /deals/{ref}/bank-account answers 404, which is the honest state.
SignatureThe clientdeal.agreement_signed
The client signs on the marketplace and the verification reference appears on the completion state.
State at a glanceYou
GET /deals/{ref}/completion
Account confirmed, agreement attached, signed, with timestamps, for anyone who prefers polling to events.

Your own journey

Completion belongs in your product.

Attach your continuation linkYou
POST /deals/{ref}/handover
The client sees Continue and finishes with you.
Nothing else changesCapvant
Statements, offers and the outcome call stay exactly as they are on the other lane.

You move itThe client moves itCapvant moves it

Where a deal comes from

Before documents, and after

The path

Completion, two lanes

White label, the client never leaves

Your own journey

Reporting the outcome

Timing

On this page