Send a message

curl --request POST \
  --url https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "parts": [
    {
      "text": "<string>",
      "file": {
        "document_id": "<string>",
        "filename": "<string>",
        "media_type": "application/pdf",
        "url": "<string>"
      },
      "data": {},
      "media_type": "<string>"
    }
  ],
  "author_name": "<string>",
  "in_reply_to": "<string>",
  "next_action_id": "<string>",
  "external_id": "<string>"
}
'

import requests

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

payload = {
    "parts": [
        {
            "text": "<string>",
            "file": {
                "document_id": "<string>",
                "filename": "<string>",
                "media_type": "application/pdf",
                "url": "<string>"
            },
            "data": {},
            "media_type": "<string>"
        }
    ],
    "author_name": "<string>",
    "in_reply_to": "<string>",
    "next_action_id": "<string>",
    "external_id": "<string>"
}
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({
    parts: [
      {
        text: '<string>',
        file: {
          document_id: '<string>',
          filename: '<string>',
          media_type: 'application/pdf',
          url: '<string>'
        },
        data: {},
        media_type: '<string>'
      }
    ],
    author_name: '<string>',
    in_reply_to: '<string>',
    next_action_id: '<string>',
    external_id: '<string>'
  })
};

fetch('https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}/messages', 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}/messages",
  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([
    'parts' => [
        [
                'text' => '<string>',
                'file' => [
                                'document_id' => '<string>',
                                'filename' => '<string>',
                                'media_type' => 'application/pdf',
                                'url' => '<string>'
                ],
                'data' => [
                                
                ],
                'media_type' => '<string>'
        ]
    ],
    'author_name' => '<string>',
    'in_reply_to' => '<string>',
    'next_action_id' => '<string>',
    'external_id' => '<string>'
  ]),
  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/referrals/{referral_id}/messages"

	payload := strings.NewReader("{\n  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\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/referrals/{referral_id}/messages")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}"

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

{
  "id": "msg_01K5X6D2E8",
  "referral_id": "<string>",
  "conversation_id": "conv_01K5X3K7Q2",
  "author": "oj",
  "channel": "embed",
  "parts": [
    {
      "kind": "text",
      "text": "<string>",
      "file": {
        "document_id": "<string>",
        "filename": "<string>",
        "media_type": "application/pdf",
        "url": "<string>",
        "type": "bank_statement"
      },
      "data": {},
      "media_type": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "object": "message",
  "author_name": "O.J.",
  "direction": "inbound",
  "next_action_id": "<string>",
  "in_reply_to": "<string>",
  "external_id": "<string>",
  "delivered_at": "2023-11-07T05:31:56Z",
  "read_at": "2023-11-07T05:31:56Z"
}

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

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

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

Conversation

Send a message

Adds a message to the referral’s conversation. There are two uses.

With author: borrower, you are relaying something the borrower said or uploaded inside your own product, for example an answer typed into your chat, or a statement dropped into your inbox. O.J. treats it exactly as if the borrower had said it on a hosted page. It answers a pending question, satisfies a document request, or is read by O.J.’s agent. The borrower never has to leave your app.

With author: partner, you are telling O.J. something about the deal, such as “the owner is travelling until the 12th” or “we already have the lease on file”. O.J.’s agent reads it, and if it changes what is needed, the referral’s todos change too.

Posting a message does not contact the borrower on O.J.’s channels. O.J. decides on its own when to reply and where, under your contact_channels policy. If you want O.J. to answer inside your product, register a channel connector.

POST

referrals

{referral_id}

messages

Send a message

curl --request POST \
  --url https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "parts": [
    {
      "text": "<string>",
      "file": {
        "document_id": "<string>",
        "filename": "<string>",
        "media_type": "application/pdf",
        "url": "<string>"
      },
      "data": {},
      "media_type": "<string>"
    }
  ],
  "author_name": "<string>",
  "in_reply_to": "<string>",
  "next_action_id": "<string>",
  "external_id": "<string>"
}
'

import requests

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

payload = {
    "parts": [
        {
            "text": "<string>",
            "file": {
                "document_id": "<string>",
                "filename": "<string>",
                "media_type": "application/pdf",
                "url": "<string>"
            },
            "data": {},
            "media_type": "<string>"
        }
    ],
    "author_name": "<string>",
    "in_reply_to": "<string>",
    "next_action_id": "<string>",
    "external_id": "<string>"
}
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({
    parts: [
      {
        text: '<string>',
        file: {
          document_id: '<string>',
          filename: '<string>',
          media_type: 'application/pdf',
          url: '<string>'
        },
        data: {},
        media_type: '<string>'
      }
    ],
    author_name: '<string>',
    in_reply_to: '<string>',
    next_action_id: '<string>',
    external_id: '<string>'
  })
};

fetch('https://sandbox.api.meet-oj.com/partner/v0/referrals/{referral_id}/messages', 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}/messages",
  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([
    'parts' => [
        [
                'text' => '<string>',
                'file' => [
                                'document_id' => '<string>',
                                'filename' => '<string>',
                                'media_type' => 'application/pdf',
                                'url' => '<string>'
                ],
                'data' => [
                                
                ],
                'media_type' => '<string>'
        ]
    ],
    'author_name' => '<string>',
    'in_reply_to' => '<string>',
    'next_action_id' => '<string>',
    'external_id' => '<string>'
  ]),
  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/referrals/{referral_id}/messages"

	payload := strings.NewReader("{\n  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\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/referrals/{referral_id}/messages")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"parts\": [\n    {\n      \"text\": \"<string>\",\n      \"file\": {\n        \"document_id\": \"<string>\",\n        \"filename\": \"<string>\",\n        \"media_type\": \"application/pdf\",\n        \"url\": \"<string>\"\n      },\n      \"data\": {},\n      \"media_type\": \"<string>\"\n    }\n  ],\n  \"author_name\": \"<string>\",\n  \"in_reply_to\": \"<string>\",\n  \"next_action_id\": \"<string>\",\n  \"external_id\": \"<string>\"\n}"

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

{
  "id": "msg_01K5X6D2E8",
  "referral_id": "<string>",
  "conversation_id": "conv_01K5X3K7Q2",
  "author": "oj",
  "channel": "embed",
  "parts": [
    {
      "kind": "text",
      "text": "<string>",
      "file": {
        "document_id": "<string>",
        "filename": "<string>",
        "media_type": "application/pdf",
        "url": "<string>",
        "type": "bank_statement"
      },
      "data": {},
      "media_type": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "object": "message",
  "author_name": "O.J.",
  "direction": "inbound",
  "next_action_id": "<string>",
  "in_reply_to": "<string>",
  "external_id": "<string>",
  "delivered_at": "2023-11-07T05:31:56Z",
  "read_at": "2023-11-07T05:31:56Z"
}

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

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

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

Path Parameters

referral_id

string

required

Example:

"ref_01K5X3K7Q2"

Body

application/json

The body for posting a message into a referral's conversation from your side.

author

enum<string>

required

borrower when you are relaying what the borrower said or uploaded in your product. partner when your team or system is telling O.J. something.

Available options:

borrower,

partner

parts

object[]

required

Minimum array length: 1

Show child attributes

author_name

string

in_reply_to

string

The O.J. message the borrower is answering, if your UI knows it.

next_action_id

string

The action this message is about, if your UI knows it. O.J. works it out otherwise.

external_id

string

Response

Message recorded

One turn in a referral's conversation. author is who said it: oj (O.J.'s agent or a reviewer), borrower, or partner (your staff or your system). channel is where it went through. parts is the content. next_action_id is set when the message is about a specific action, for example O.J. asking for statements, or the borrower's reply that satisfied the request.

Messages from the borrower on O.J.'s own channels appear here too, so your product always has the whole thread. The message carries the medium, not the number or address the borrower used.

string

required

Example:

"msg_01K5X6D2E8"

referral_id

string

required

conversation_id

string

required

Example:

"conv_01K5X3K7Q2"

author

enum<string>

required

Available options:

oj,

borrower,

partner

channel

enum<string>

required

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.

Available options:

embed,

hosted_page,

sms,

imessage,

email,

voice,

partner_channel,

api

parts

object[]

required

Show child attributes

created_at

string<date-time>

required

object

string

Allowed value: "message"

author_name

string

Display name to show: "O.J.", the borrower's first name, or your staff member's name.

Example:

"O.J."

direction

enum<string>

From O.J.'s point of view. Outbound messages were sent by O.J.

Available options:

inbound,

outbound

next_action_id

string

in_reply_to

string

The id of the message this answers, when known.

external_id

string

Your own id for the message, if you posted it.

delivered_at

string<date-time>

When the channel confirmed delivery, if it does.

read_at

string<date-time>

When the recipient opened it, if the channel reports that.