Retrieve a referral

curl --request GET \
  --url https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "ref_01K5X3K7Q2",
  "external_id": "<string>",
  "status": "received",
  "status_label": "In review",
  "progress": {
    "step": "received",
    "steps": [
      {
        "key": "received",
        "label": "In review",
        "state": "done"
      }
    ],
    "ended": true
  },
  "intent": "work_this_deal",
  "business": {
    "legal_name": "<string>",
    "dba": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "referral",
  "status_reason": "Two lenders are reviewing your file. Most answer within two business days.",
  "todos": [
    {
      "id": "act_01K5X3T5E9",
      "who": "borrower",
      "kind": "upload_documents",
      "label": "Upload Feb and Mar 2026 bank statements",
      "url": "<string>",
      "purpose": "statements",
      "document_request_id": "<string>",
      "detail": "<string>",
      "due_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "reminders": {
        "cadence_days": [
          2,
          5,
          9
        ],
        "sent_count": 123,
        "next_at": "2023-11-07T05:31:56Z",
        "via": "oj_channels"
      }
    }
  ],
  "next_action": {
    "id": "act_01K5X3T5E9",
    "who": "borrower",
    "kind": "upload_documents",
    "label": "Upload Feb and Mar 2026 bank statements",
    "url": "<string>",
    "purpose": "statements",
    "document_request_id": "<string>",
    "detail": "<string>",
    "due_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "reminders": {
      "cadence_days": [
        2,
        5,
        9
      ],
      "sent_count": 123,
      "next_at": "2023-11-07T05:31:56Z",
      "via": "oj_channels"
    }
  },
  "requested_amount": 123,
  "matches": [
    {
      "id": "mat_01K5X3M1A4",
      "lender": "Example Capital",
      "product": "revenue_based_financing",
      "state": "matched",
      "program": "Revenue-based financing",
      "amount_max": 123,
      "term_months": [
        6,
        12
      ],
      "speed": "1–2 business days"
    }
  ],
  "offers_available": 123,
  "credit": {
    "status": "authorization_needed",
    "type": "soft",
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "outcome": {
    "status": "declined",
    "reason": "lender_declined",
    "message": "Example Capital didn't approve this request. They'll send you a notice explaining their decision.",
    "lender": "<string>",
    "decided_at": "2023-11-07T05:31:56Z"
  },
  "funded": {
    "lender": "<string>",
    "amount": 123,
    "funded_at": "2023-11-07T05:31:56Z",
    "account": {
      "institution": "Example Bank",
      "mask": "4471"
    },
    "lender_contact": {
      "name": "<string>",
      "phone": "<string>",
      "email": "jsmith@example.com",
      "url": "<string>"
    }
  },
  "payout": {
    "status": "estimated",
    "status_label": "Held until Nov 4",
    "commission": 123,
    "oj_fee": 123,
    "partner_share": 123,
    "scheduled_for": "2023-12-25",
    "paid_at": "2023-11-07T05:31:56Z"
  },
  "conversation": {
    "id": "conv_01K5X3K7Q2",
    "last_message_at": "2023-11-07T05:31:56Z",
    "last_message_preview": "O.J.: Thanks, Feb is in. Still need Mar.",
    "last_channel": "embed",
    "unread_for_partner": 123
  },
  "hosted_url": "<string>",
  "metadata": {}
}

{
  "type": "https://api.meet-oj.com/problems/duplicate-external-id",
  "title": "Referral already exists",
  "status": 409,
  "code": "invalid_request",
  "request_id": "req_01K5X4A9M2",
  "detail": "A referral with external_id cust_8842 was created on 2026-09-20 as ref_01K5X3K7Q2.",
  "instance": "/partner/v0/referrals",
  "param": "<string>"
}

GET

referrals

{referral_id}

Retrieve a referral

curl --request GET \
  --url https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "ref_01K5X3K7Q2",
  "external_id": "<string>",
  "status": "received",
  "status_label": "In review",
  "progress": {
    "step": "received",
    "steps": [
      {
        "key": "received",
        "label": "In review",
        "state": "done"
      }
    ],
    "ended": true
  },
  "intent": "work_this_deal",
  "business": {
    "legal_name": "<string>",
    "dba": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "referral",
  "status_reason": "Two lenders are reviewing your file. Most answer within two business days.",
  "todos": [
    {
      "id": "act_01K5X3T5E9",
      "who": "borrower",
      "kind": "upload_documents",
      "label": "Upload Feb and Mar 2026 bank statements",
      "url": "<string>",
      "purpose": "statements",
      "document_request_id": "<string>",
      "detail": "<string>",
      "due_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "reminders": {
        "cadence_days": [
          2,
          5,
          9
        ],
        "sent_count": 123,
        "next_at": "2023-11-07T05:31:56Z",
        "via": "oj_channels"
      }
    }
  ],
  "next_action": {
    "id": "act_01K5X3T5E9",
    "who": "borrower",
    "kind": "upload_documents",
    "label": "Upload Feb and Mar 2026 bank statements",
    "url": "<string>",
    "purpose": "statements",
    "document_request_id": "<string>",
    "detail": "<string>",
    "due_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "reminders": {
      "cadence_days": [
        2,
        5,
        9
      ],
      "sent_count": 123,
      "next_at": "2023-11-07T05:31:56Z",
      "via": "oj_channels"
    }
  },
  "requested_amount": 123,
  "matches": [
    {
      "id": "mat_01K5X3M1A4",
      "lender": "Example Capital",
      "product": "revenue_based_financing",
      "state": "matched",
      "program": "Revenue-based financing",
      "amount_max": 123,
      "term_months": [
        6,
        12
      ],
      "speed": "1–2 business days"
    }
  ],
  "offers_available": 123,
  "credit": {
    "status": "authorization_needed",
    "type": "soft",
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "outcome": {
    "status": "declined",
    "reason": "lender_declined",
    "message": "Example Capital didn't approve this request. They'll send you a notice explaining their decision.",
    "lender": "<string>",
    "decided_at": "2023-11-07T05:31:56Z"
  },
  "funded": {
    "lender": "<string>",
    "amount": 123,
    "funded_at": "2023-11-07T05:31:56Z",
    "account": {
      "institution": "Example Bank",
      "mask": "4471"
    },
    "lender_contact": {
      "name": "<string>",
      "phone": "<string>",
      "email": "jsmith@example.com",
      "url": "<string>"
    }
  },
  "payout": {
    "status": "estimated",
    "status_label": "Held until Nov 4",
    "commission": 123,
    "oj_fee": 123,
    "partner_share": 123,
    "scheduled_for": "2023-12-25",
    "paid_at": "2023-11-07T05:31:56Z"
  },
  "conversation": {
    "id": "conv_01K5X3K7Q2",
    "last_message_at": "2023-11-07T05:31:56Z",
    "last_message_preview": "O.J.: Thanks, Feb is in. Still need Mar.",
    "last_channel": "embed",
    "unread_for_partner": 123
  },
  "hosted_url": "<string>",
  "metadata": {}
}

{
  "type": "https://api.meet-oj.com/problems/duplicate-external-id",
  "title": "Referral already exists",
  "status": 409,
  "code": "invalid_request",
  "request_id": "req_01K5X4A9M2",
  "detail": "A referral with external_id cust_8842 was created on 2026-09-20 as ref_01K5X3K7Q2.",
  "instance": "/partner/v0/referrals",
  "param": "<string>"
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

referral_id

string

required

Example:

"ref_01K5X3K7Q2"

Response

The referral

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.

string

required

Example:

"ref_01K5X3K7Q2"

external_id

string

required

status

enum<string>

required

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.

Available options:

received,

prequalified,

needs_partner,

needs_borrower,

submitted,

offer,

funded,

declined,

closed

status_label

string

required

The current step's label ("Received", "Documents", "In review", "Offer", "Funded"), or "Declined" or "Closed" when the referral ended. Render as-is.

Example:

"In review"

progress

object

required

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.

Show child attributes

intent

enum<string>

required

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.

Available options:

work_this_deal,

just_refer

business

object

required

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

object

string

Allowed value: "referral"

status_reason

string

One plain sentence for the borrower about where things stand. When the referral ends, this is the only thing to show.

Example:

"Two lenders are reviewing your file. Most answer within two business days."

todos

object[]

Everything needed from outside O.J. right now, one row per item. Empty when nothing is needed.

Show child attributes

next_action

object

The first item in todos, for integrations that show one button. Absent when nothing is needed.

Show child attributes

requested_amount

integer

A dollar amount expressed in whole US cents, so $85,000.00 is 8500000. Cents avoid rounding errors that decimals cause in some languages.

matches

object[]

The lender programs the business matches, named.

Show child attributes

offers_available

integer

credit

object

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.

Show child attributes

outcome

object

Present when status is declined or closed.

Show child attributes

funded

object

What the borrower needs after funding. The lender, not O.J., sends and collects the money.

Show child attributes

payout

object

The partner's share on this referral. Money states never imply O.J. holds funds.

Show child attributes

conversation

object

A summary of the referral's conversation. GET /referrals/{id}/conversation returns the messages.

Show child attributes

hosted_url

string<uri>

The partner's own view of this referral on O.J. (magic-link). Not for the borrower.

metadata

object

Show child attributes