Create a referral
Creates a referral for one business. Behind it, O.J. opens a deal and starts working.
If the request includes structured data in context (monthly ledger figures, card-processing months, a
listing’s financials, or a Plaid connection), the response already lists the lenders the business matches.
Matches update as documents and the credit check arrive, and each change sends referral.matches_updated.
intent decides who talks to the borrower. With work_this_deal, O.J. never contacts the borrower and
anything the borrower must do arrives in the referral’s todos for you to show. With just_refer,
O.J. contacts the borrower directly, in its own name, mentioning that you referred them.
Authorizations
One client per partner per environment. Access tokens expire after 15 minutes. Scopes are granted per client. Sandbox clients use https://sandbox.api.meet-oj.com/oauth/token.
Headers
IETF Idempotency-Key semantics (draft-ietf-httpapi-idempotency-key-header). Send a fresh unique value
(a UUID) with every new request. A retry with the same key and the same payload returns the original
response with the header Idempotent-Replayed: true. The same key with a different payload is rejected with
422 and code idempotency_key_reused. Keys are kept for 24 hours.
255Body
The body you send to create a referral. Five things are required: your own id for the business
(external_id), who will talk to the borrower (intent), the business, at least one contact, and a consent
record. Everything else is optional and makes the first matches more complete.
Your customer, merchant, or listing id. Unique per partner.
Who the borrower hears from. O.J. does the work either way. With just_refer, O.J. contacts the borrower
directly, introducing itself as working with you, and sends the borrower the link for each to-do. With
work_this_deal, O.J. never contacts the borrower; each to-do arrives in the referral's todos with a link
you place in your own product, so the borrower acts inside your flow.
work_this_deal, just_refer The company that needs financing. Only the legal name and address are required to create a referral;
everything else improves matching. The EIN (federal tax ID) is used to detect the same business arriving from two
partners, in which case the first partner keeps the referral. The NAICS code (a six-digit industry
classification) or a free-text industry lets programs with industry restrictions evaluate correctly.
1A record of what the business agreed to before you sent it to O.J. At minimum, the business must have agreed
that you may share its information with O.J. and O.J.'s lenders. If you use intent: just_refer, the business
must also have agreed that O.J. may contact it. Anything you did not capture, O.J. captures on its own hosted
pages before proceeding.
A kind of financing. When you pass one as product_hint, O.J. still checks every product it can place, but
lists the hinted one first. revenue_based_financing is repaid as a share of sales; term_loan is a fixed
amount repaid over a fixed period; business_line_of_credit can be drawn and repaid repeatedly; sba_7a is a
government-guaranteed bank loan; invoice_factoring advances money against unpaid invoices;
asset_based_lending is secured by inventory or equipment; hard_money_lending is secured by real estate.
revenue_based_financing, term_loan, business_line_of_credit, sba_7a, invoice_factoring, asset_based_lending, hard_money_lending A dollar amount expressed in whole US cents, so $85,000.00 is 8500000. Cents avoid rounding errors that decimals cause in some languages.
working_capital, inventory, equipment, expansion, acquisition, refinance, payroll, real_estate, other Everything you already know about the business, in whatever combination you have. The more you send, the more of the matching O.J. can do immediately, before any documents arrive. Figures you report are later checked against the borrower's bank data; if they disagree by more than a small tolerance, an O.J. reviewer looks at the file before it goes to lenders.
Attribution below the partner — a sub-partner, agent, or campaign. Drives overrides.
Response
Referral created
One business you have sent to O.J., and everything the borrower and your team need to see about it.
O.J. Embed renders only what this object returns, in the same words. If you build your own UI, render the
same fields: progress as a five-step track, todos as a checklist with one button each, matches as the
lenders the business matches, and status_reason as the sentence under it all. payout is for your team
and never appears on a borrower screen.
hosted_url is a link to O.J.'s own page for this referral, for a person at your company.
"ref_01K5X3K7Q2"
Where the referral is, for logic. Use progress and status_label for anything a person reads.
The normal path is received, then prequalified once the business has matches, then submitted when
the file has gone to lenders, then offer when a lender has made one, then funded. A referral pauses in
needs_borrower when the borrower has a to-do, or needs_partner when someone at your company does.
Two statuses are final. declined means a lender reviewed the file and did not approve it; the lender, not
O.J., sends the borrower its notice. closed means the referral ended without a lender decision, for
example because no lender matched, the borrower withdrew, or the business funded elsewhere.
received, prequalified, needs_partner, needs_borrower, submitted, offer, funded, declined, closed The current step's label ("Received", "Documents", "In review", "Offer", "Funded"), or "Declined" or "Closed" when the referral ended. Render as-is.
"In review"
The five steps the borrower sees, in the same words everywhere: Received, Documents, In review, Offer,
Funded. Render the steps as a track. When the referral ends without funding, ended is true and the track
is replaced by status_reason, one plain sentence.
Who the borrower hears from. O.J. does the work either way. With just_refer, O.J. contacts the borrower
directly, introducing itself as working with you, and sends the borrower the link for each to-do. With
work_this_deal, O.J. never contacts the borrower; each to-do arrives in the referral's todos with a link
you place in your own product, so the borrower acts inside your flow.
work_this_deal, just_refer "referral"One plain sentence for the borrower about where things stand. When the referral ends, this is the only thing to show.
"Two lenders are reviewing your file. Most answer within two business days."
Everything needed from outside O.J. right now, one row per item. Empty when nothing is needed.
The first item in todos, for integrations that show one button. Absent when nothing is needed.
A dollar amount expressed in whole US cents, so $85,000.00 is 8500000. Cents avoid rounding errors that decimals cause in some languages.
The lender programs the business matches, named.
O.J. runs a soft credit pull on the primary owner to match on credit score. It does not affect the owner's
score. The owner authorizes it and enters their SSN on O.J.'s screen (Embed or a hosted page); neither
passes through your servers. Until it is authorized, the referral carries an authorize_credit action.
O.J. never shares the score, or anything derived from it, with partners. Lenders run their own credit check if
the borrower accepts an offer.
Present when status is declined or closed.
What the borrower needs after funding. The lender, not O.J., sends and collects the money.
The partner's share on this referral. Money states never imply O.J. holds funds.
A summary of the referral's conversation. GET /referrals/{id}/conversation returns the messages.
The partner's own view of this referral on O.J. (magic-link). Not for the borrower.