Create a session

curl --request POST \
  --url https://sandbox.api.meet-oj.com/partner/v0/partner_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "return_url": "<string>",
  "referral_id": "<string>",
  "options": {},
  "expires_in_seconds": 86400,
  "theme": {
    "primary_color": "<string>",
    "logo_url": "<string>",
    "partner_display_name": "<string>",
    "locale": "en"
  }
}
'

import requests

url = "https://sandbox.api.meet-oj.com/partner/v0/partner_sessions"

payload = {
    "return_url": "<string>",
    "referral_id": "<string>",
    "options": {},
    "expires_in_seconds": 86400,
    "theme": {
        "primary_color": "<string>",
        "logo_url": "<string>",
        "partner_display_name": "<string>",
        "locale": "en"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    return_url: '<string>',
    referral_id: '<string>',
    options: {},
    expires_in_seconds: 86400,
    theme: {
      primary_color: '<string>',
      logo_url: '<string>',
      partner_display_name: '<string>',
      locale: 'en'
    }
  })
};

fetch('https://sandbox.api.meet-oj.com/partner/v0/partner_sessions', 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/partner_sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'return_url' => '<string>',
    'referral_id' => '<string>',
    'options' => [
        
    ],
    'expires_in_seconds' => 86400,
    'theme' => [
        'primary_color' => '<string>',
        'logo_url' => '<string>',
        'partner_display_name' => '<string>',
        'locale' => 'en'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://sandbox.api.meet-oj.com/partner/v0/partner_sessions"

	payload := strings.NewReader("{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.api.meet-oj.com/partner/v0/partner_sessions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.api.meet-oj.com/partner/v0/partner_sessions")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}"

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

{
  "id": "ps_01K5X3T5E9",
  "url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "object": "partner_session",
  "client_token": "<string>",
  "referral_id": "<string>"
}

{
  "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>"
}

Sessions

Create a session

Creates a session that unlocks one O.J. screen. Call it from your server, never from a browser. The response contains a client_token for the O.J. Embed library, which works once and expires after fifteen minutes, and a hosted url for partners that would rather redirect, which lasts expires_in_seconds (24 hours by default).

purpose picks the screen:

status shows the borrower’s progress, to-dos, matches and offers.
intake is the full application for a new business, prefilled from prefill, including the credit authorization. It creates the referral when the borrower submits.
documents lets the borrower connect a bank or upload what O.J. still needs.
bank_connect opens Plaid, for statements or the funding account. You never see balances or credentials.
offer_acceptance lets the borrower compare offers, accept and sign, and choose the funding account.
conversation shows the borrower’s messages with O.J.

theme sets your logo and colours. The wording and legal disclosures on the screen are O.J.’s and cannot be changed. When the borrower finishes on the hosted page, they are sent to your return_url with ?referral_id= added.

POST

partner_sessions

Create a session

curl --request POST \
  --url https://sandbox.api.meet-oj.com/partner/v0/partner_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "return_url": "<string>",
  "referral_id": "<string>",
  "options": {},
  "expires_in_seconds": 86400,
  "theme": {
    "primary_color": "<string>",
    "logo_url": "<string>",
    "partner_display_name": "<string>",
    "locale": "en"
  }
}
'

import requests

url = "https://sandbox.api.meet-oj.com/partner/v0/partner_sessions"

payload = {
    "return_url": "<string>",
    "referral_id": "<string>",
    "options": {},
    "expires_in_seconds": 86400,
    "theme": {
        "primary_color": "<string>",
        "logo_url": "<string>",
        "partner_display_name": "<string>",
        "locale": "en"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    return_url: '<string>',
    referral_id: '<string>',
    options: {},
    expires_in_seconds: 86400,
    theme: {
      primary_color: '<string>',
      logo_url: '<string>',
      partner_display_name: '<string>',
      locale: 'en'
    }
  })
};

fetch('https://sandbox.api.meet-oj.com/partner/v0/partner_sessions', 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/partner_sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'return_url' => '<string>',
    'referral_id' => '<string>',
    'options' => [
        
    ],
    'expires_in_seconds' => 86400,
    'theme' => [
        'primary_color' => '<string>',
        'logo_url' => '<string>',
        'partner_display_name' => '<string>',
        'locale' => 'en'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://sandbox.api.meet-oj.com/partner/v0/partner_sessions"

	payload := strings.NewReader("{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.api.meet-oj.com/partner/v0/partner_sessions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.api.meet-oj.com/partner/v0/partner_sessions")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"return_url\": \"<string>\",\n  \"referral_id\": \"<string>\",\n  \"options\": {},\n  \"expires_in_seconds\": 86400,\n  \"theme\": {\n    \"primary_color\": \"<string>\",\n    \"logo_url\": \"<string>\",\n    \"partner_display_name\": \"<string>\",\n    \"locale\": \"en\"\n  }\n}"

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

{
  "id": "ps_01K5X3T5E9",
  "url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "object": "partner_session",
  "client_token": "<string>",
  "referral_id": "<string>"
}

{
  "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.

Headers

Idempotency-Key

string

required

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.

Maximum string length: 255

Body

application/json

What you send to create a partner session. A session unlocks one O.J. screen, either as an Embed component inside your page or as a hosted page. purpose picks the screen.

For a new business, use intake and put whatever you already know in prefill, so the borrower confirms it instead of typing it again. For an existing referral, pass its referral_id. theme sets your logo and colour. The wording and legal disclosures on the screen are O.J.'s and cannot be changed.

purpose

enum<string>

required

Which component (or hosted page) this session unlocks. See x-embed for what each one shows.

Available options:

status,

conversation,

intake,

documents,

bank_connect,

offer_acceptance

return_url

string<uri>

required

referral_id

string

Required for every purpose except intake.

options

object

Per-component options listed in x-embed (for example compact for the status card, skip_known_fields for intake, document_request_ids for documents).

prefill

object

For intake — anything already known; the borrower confirms rather than retypes.

Show child attributes

expires_in_seconds

integer

default:86400

Required range: 300 <= x <= 604800

theme

object

Partner colors and logo. O.J.'s copy and disclosures are not editable.

Show child attributes

Response

Session created

A minted hosted-page link. Send the borrower to url by redirect, new tab, text message, or QR code. When they finish, they are returned to your return_url with ?referral_id= appended.

string

required

Example:

"ps_01K5X3T5E9"

url

string<uri>

required

Redirect, open in a new tab, or render as a QR code.

expires_at

string<date-time>

required

object

string

Allowed value: "partner_session"

client_token

string

Hand this to the browser for O.J. Embed (OJ.create({ token })). Single use, 15 minutes, bound to this session's purpose and referral. Never expose your client credentials to a browser; this token is what goes there instead.

referral_id

string