> ## Documentation Index > Fetch the complete documentation index at: https://developers.meet-oj.com/llms.txt > Use this file to discover all available pages before exploring further. # List referrals > Returns your referrals, newest first, one page at a time. Filter by `status` to build a work queue (for example, everything in `needs_partner`), or by `external_id` to find the referral for one of your own customer records. To page, pass the last id you received as `starting_after`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /referrals openapi: 3.1.0 info: title: O.J. Agent Development Kit (ADK) version: 0.5.1 summary: >- Send O.J. a business. Get back named lender matches, what's needed, offers and funding status. description: > The O.J. ADK lets platforms with small-business customers offer financing without becoming a lender or a broker. You send a business as a **referral**. O.J. matches it to lender programs, collects documents, submits to lenders and tracks the deal to funding. You earn a share of the commission on every funded loan. Integrate with **O.J. Embed** (drop-in screens), the **REST API** with webhooks, or **MCP** for agents. All three read and write the same referral. Conventions: OAuth 2.0 client credentials, amounts in cents, prefixed ids, cursor pagination, an `Idempotency-Key` on every POST, RFC 9457 errors, and Standard Webhooks signatures. license: name: Proprietary — O.J. partner terms identifier: LicenseRef-OJ-Partner contact: name: O.J. Developer Support email: developers@meet-oj.com servers: - url: https://sandbox.api.meet-oj.com/partner/v0 description: Sandbox - url: https://api.meet-oj.com/partner/v0 description: Production security: - oauth2: [] tags: - name: Referrals description: >- A referral is one business you sent to O.J. Every other resource belongs to a referral. - name: Matches description: >- The lenders a business matches, named, with estimated limits. `POST /match_checks` screens raw numbers without creating a referral. A match is not a credit decision; the lender decides. - name: Documents description: >- Documents O.J. still needs, and uploads by API. Most integrations show the `next_action` button instead. - name: Offers description: >- Offers returned by lenders. Indicative terms computed before a lender replies are marked `binding: false`. - name: Sessions description: >- Create a session to open an O.J. screen: a `client_token` for Embed, or a hosted `url` to redirect to. - name: Events description: >- Every change to a referral is an event, delivered by webhook, streamed over SSE, and kept for 30 days at `GET /events`. - name: Payouts description: >- Your share of the commission on each funded referral. Match rows to your bank statement with `statement_descriptor`. Payout destinations are set during onboarding and cannot be changed by API. - name: Conversation description: >- The message thread between O.J., the borrower and your team on a referral, across every channel. - name: Channels description: >- Channel connectors let O.J. reach your borrowers through channels you own (in-app inbox, SMS, Apple Business Messages, email), in your brand. - name: Policy description: >- Account-level rules: send approval, allowed Embed origins, contact channels, default intent and reminder cadence. - name: Programs description: >- For lenders running a program on O.J.: receive submissions, record decisions and report funding. - name: Webhooks description: >- Register endpoints that receive signed events. Deliveries follow Standard Webhooks. paths: /referrals: get: tags: - Referrals summary: List referrals description: > Returns your referrals, newest first, one page at a time. Filter by `status` to build a work queue (for example, everything in `needs_partner`), or by `external_id` to find the referral for one of your own customer records. To page, pass the last id you received as `starting_after`. operationId: listReferrals parameters: - name: status in: query description: Only return referrals in this status. schema: $ref: '#/components/schemas/ReferralStatus' - name: external_id in: query description: >- Only return the referral you created with this `external_id` (your own identifier for the business). schema: type: string - name: created_after in: query description: Only return referrals created after this time. schema: type: string format: date-time - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' responses: '200': description: A page of referrals content: application/json: schema: type: object required: - data - has_more properties: data: type: array items: $ref: '#/components/schemas/Referral' has_more: type: boolean components: schemas: ReferralStatus: type: string description: > 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. enum: - received - prequalified - needs_partner - needs_borrower - submitted - offer - funded - declined - closed Referral: type: object description: > 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. required: - id - external_id - status - status_label - progress - intent - business - created_at - updated_at properties: id: type: string examples: - ref_01K5X3K7Q2 object: type: string const: referral external_id: type: string status: $ref: '#/components/schemas/ReferralStatus' status_label: type: string description: >- The current step's label ("Received", "Documents", "In review", "Offer", "Funded"), or "Declined" or "Closed" when the referral ended. Render as-is. examples: - In review status_reason: type: string description: >- One plain sentence for the borrower about where things stand. When the referral ends, this is the only thing to show. examples: - >- Two lenders are reviewing your file. Most answer within two business days. progress: $ref: '#/components/schemas/Progress' todos: type: array description: >- Everything needed from outside O.J. right now, one row per item. Empty when nothing is needed. items: $ref: '#/components/schemas/NextAction' next_action: $ref: '#/components/schemas/NextAction' description: >- The first item in `todos`, for integrations that show one button. Absent when nothing is needed. intent: $ref: '#/components/schemas/Intent' business: type: object required: - legal_name properties: legal_name: type: string dba: type: string city: type: string state: type: string requested_amount: $ref: '#/components/schemas/Money' matches: type: array description: The lender programs the business matches, named. items: $ref: '#/components/schemas/Match' offers_available: type: integer credit: $ref: '#/components/schemas/CreditCheck' outcome: $ref: '#/components/schemas/Outcome' description: Present when `status` is `declined` or `closed`. funded: type: object description: >- What the borrower needs after funding. The lender, not O.J., sends and collects the money. properties: lender: type: string amount: $ref: '#/components/schemas/Money' funded_at: type: string format: date-time account: type: object properties: institution: type: string examples: - Example Bank mask: type: string examples: - '4471' lender_contact: type: object description: Where the borrower goes with payment questions. properties: name: type: string phone: type: string email: type: string format: email url: type: string format: uri payout: type: object description: >- The partner's share on this referral. Money states never imply O.J. holds funds. properties: status: $ref: '#/components/schemas/PayoutStatus' status_label: type: string description: >- The words O.J. shows for the payout state, with the relevant date when there is one. Render as-is. examples: - Held until Nov 4 - Paid Oct 12 - Estimated commission: $ref: '#/components/schemas/Money' description: What the lender pays O.J. oj_fee: $ref: '#/components/schemas/Money' partner_share: $ref: '#/components/schemas/Money' scheduled_for: type: string format: date paid_at: type: string format: date-time conversation: type: object description: >- A summary of the referral's conversation. `GET /referrals/{id}/conversation` returns the messages. properties: id: type: string examples: - conv_01K5X3K7Q2 last_message_at: type: string format: date-time last_message_preview: type: string description: The first line of the latest message, for a list view. examples: - 'O.J.: Thanks, Feb is in. Still need Mar.' last_channel: $ref: '#/components/schemas/Channel' unread_for_partner: type: integer hosted_url: type: string format: uri description: >- The partner's own view of this referral on O.J. (magic-link). Not for the borrower. metadata: type: object additionalProperties: type: string created_at: type: string format: date-time updated_at: type: string format: date-time Progress: type: object description: > 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. required: - step - steps - ended properties: step: type: string enum: - received - documents - in_review - offer - funded description: The current step, or the last one reached if the referral ended. steps: type: array items: type: object required: - key - label - state properties: key: type: string enum: - received - documents - in_review - offer - funded label: type: string examples: - In review state: type: string enum: - done - current - upcoming ended: type: boolean NextAction: type: object description: > Something that has to happen outside O.J. before the referral can move forward: a document, a bank connection, the credit authorization, an offer to accept. `who` says whether the borrower or someone at your company does it. `label` is the text for a button. `url` is an O.J.-hosted page where it is completed; Embed opens the same step in place. A referral lists every open action in `todos`, one row per thing needed. `next_action` is the first of them. required: - id - who - kind - label - url properties: id: type: string examples: - act_01K5X3T5E9 description: >- Stable for the life of the action. Messages and reminders about this action reference it. who: type: string enum: - borrower - partner kind: type: string enum: - upload_documents - connect_bank - authorize_credit - answer_question - approve_send - accept_offer - sign purpose: type: string enum: - statements - funding_account description: >- For `connect_bank`. `statements` replaces uploading bank statements. `funding_account` verifies the account the lender pays and debits. If the borrower already connected a bank, they choose an account from that connection instead of logging in again. document_request_id: type: string description: For `upload_documents`, the document request this row satisfies. label: type: string examples: - Upload Feb and Mar 2026 bank statements - Review and accept your offer detail: type: string description: One sentence of context for the person taking the action. url: type: string format: uri description: >- Hosted page for this action. Valid until the action is completed or `expires_at` passes (seven days by default, renewed each time you read the referral), so the same link works on Tuesday and on Thursday. Progress on the page is kept for the life of the referral. due_at: type: string format: date-time description: When O.J. would like this done. Reminders are scheduled from it. expires_at: type: string format: date-time reminders: type: object description: >- How O.J. is nudging the person. Under `just_refer`, O.J. sends reminders on its own channels. Under `work_this_deal`, O.J. sends them through your channel connector if you have one, and otherwise emits `referral.reminder_due` so your product can nudge. properties: cadence_days: type: array items: type: integer examples: - - 2 - 5 - 9 description: >- Days after the action was opened on which a reminder goes out. Set by your policy. sent_count: type: integer next_at: type: string format: date-time via: type: string enum: - oj_channels - partner_channel - partner_event description: Who delivers the reminder. Intent: type: string description: > 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. enum: - work_this_deal - just_refer Money: type: integer description: >- A dollar amount expressed in whole US cents, so $85,000.00 is `8500000`. Cents avoid rounding errors that decimals cause in some languages. Match: type: object description: > A lender program the business matches, named from the moment it matches. `amount_max` and `term_months` come from the program's own limits; they are estimates, not offers. `state` follows the program through submission to an offer or a decision. required: - id - lender - product - state properties: id: type: string examples: - mat_01K5X3M1A4 lender: type: string examples: - Example Capital program: type: string examples: - Revenue-based financing product: $ref: '#/components/schemas/Product' amount_max: $ref: '#/components/schemas/Money' term_months: type: array items: type: integer minItems: 2 maxItems: 2 examples: - - 6 - 12 speed: type: string description: How long the lender usually takes to decide, in words. examples: - 1–2 business days state: type: string enum: - matched - submitted - offer - declined - withdrawn CreditCheck: type: object description: > 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. required: - status properties: status: type: string enum: - authorization_needed - authorized - completed - unavailable type: type: string enum: - soft completed_at: type: string format: date-time Outcome: type: object description: > Why a referral ended without funding. When a lender declines, `lender` names it and the lender sends the borrower its own notice explaining the decision; O.J. does not give reasons. When no lender matched, nothing was submitted and no credit decision was made, so the referral is `closed`, not `declined`. required: - status - reason - message properties: status: type: string enum: - declined - closed reason: type: string enum: - lender_declined - no_match - withdrawn - funded_elsewhere - expired - other lender: type: string description: >- The lender that declined. Present when `reason` is `lender_declined`. message: type: string description: The sentence to show the borrower. Same as `status_reason`. examples: - >- Example Capital didn't approve this request. They'll send you a notice explaining their decision. decided_at: type: string format: date-time PayoutStatus: type: string description: > Where your share of the commission is. `estimated` is what you would earn if the current offer funds. `pending` means the deal has funded and O.J. has invoiced the lender. `received` means the lender has paid O.J. `held` means O.J. is holding your share until the lender's clawback window has passed. (A clawback is when a lender takes a commission back because the borrower defaulted very early.) `scheduled` means a payout date has been set. `paid` means the money has been sent to you. `reversed` means the lender clawed the commission back. These states describe where the commission is in the process. They do not mean O.J. holds money for you the way a bank would. The account the money goes to is set once, by a person at your company, during onboarding on an O.J.-hosted page. That page also collects your tax form (W-9 or W-8) and runs sanctions screening. The destination cannot be changed through the API, and an AI agent using your account can read payouts but cannot change where they go. O.J. issues 1099-NEC forms at year end. enum: - estimated - pending - received - held - scheduled - paid - reversed Channel: type: string description: > Where a message went through. `embed` is the O.J. Embed component inside your product. `hosted_page` is an O.J.-hosted page. `sms`, `imessage`, `email` and `voice` are O.J.'s own channels, used only when your policy allows them. `partner_channel` means O.J. delivered through one of your channel connectors, in your brand. `api` means the message was posted by your system, your agent, or an A2A client. enum: - embed - hosted_page - sms - imessage - email - voice - partner_channel - api Product: type: string description: > 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. enum: - revenue_based_financing - term_loan - business_line_of_credit - sba_7a - invoice_factoring - asset_based_lending - hard_money_lending parameters: Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 StartingAfter: name: starting_after in: query description: Cursor — the id of the last object on the previous page. schema: type: string securitySchemes: oauth2: type: oauth2 description: >- 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. flows: clientCredentials: tokenUrl: https://api.meet-oj.com/oauth/token scopes: referrals:write: Create referrals and upload documents referrals:read: Read referrals, matches, document requests, offers, events match_checks:write: Run identity-free match checks sessions:write: Mint hosted-session links webhooks:manage: Register and list webhook endpoints payouts:read: >- Read payouts (your statement). There is no payouts:write; destinations are managed in hosted onboarding by a person. messages:read: Read a referral's conversation messages:write: >- Send messages into a referral's conversation on behalf of the partner or the borrower channels:manage: Register and remove channel connectors policy:manage: Read and change the partner policy submissions:read: >- For banks running a program. List and read submissions awaiting review submissions:write: For banks running a program. Record decisions and report funding ````