Broker Submissions API

The Broker Submissions API allows brokers to programmatically submit applications with company details and supporting documents directly to a funder.

Prerequisites

Before following this guide, you will need:

A broker email address associated with your organization
Access to generate API keys (requires funder authentication)

Steps

1. Create a Broker Submission

Create a new submission with a name (API reference):

app.py

BROKER_API_KEY = "bft_xxxxxxxxx"
BASE_URL = "https://app.herondata.io"

response = requests.post(
  f"{BASE_URL}/api/broker_submissions/",
  headers={
    "x-api-key": BROKER_API_KEY,
    "Content-Type": "application/json",
  },
  json={
    "name": "ABC Company - Working Capital Request"
  }
)

response.raise_for_status()

data = response.json()
# ^ { "heron_id": "sub_xxxxxxxxx" }

submission_heron_id = data["heron_id"]

The submission name must be at least 10 characters long and is used for reference purposes to help identify the submission.

The returned submission Heron ID will be used to upload files and company details, linking them to a unique ID.

2. Add Company and Owner Details

Update the submission with detailed business and owner information (API reference):

app.py

BASE_URL = "https://app.herondata.io"
BROKER_API_KEY = 'bft_xxxxxxxxx'

response = requests.post(
  f"{BASE_URL}/api/broker_submissions/{submission_heron_id}/update_information",
  headers={
    "x-api-key": BROKER_API_KEY,
    "Content-Type": "application/json",
  },
  json={
    "source_email_address": "[email protected]",
    "company_legal_business_name": "ABC Company LLC",
    "company_email": "[email protected]",
    "company_phone_number": "555-123-4567",
    "federal_tax_id": "12-3456789",
    "amount_requested": 100000,
    "annual_revenue": 500000,
    "industry_type": "Restaurant",
    "business_start_date": "2018-05-15",
    "company_physical_address": {
      "line_1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001"
    },
    "owner_1": {
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "[email protected]",
      "mobile_phone": "555-987-6543",
      "ownership_percentage": 75,
      "date_of_birth": "1985-03-20"
    }
  }
)

response.raise_for_status()

updated_info = response.json()
# ^ The full submission record with the merged company + owner details
#   (see EndUserInformationSchema in the API reference)

Set source_email_address to the email of the broker who submitted the deal so they receive credit for the submission.

All fields in the update request are optional, allowing you to provide only the information you have available.

3. Upload PDF Files

Upload supporting documents to the submission (API reference). Optionally include a file_class form field to apply that classification to all files in the request — if omitted, Heron will automatically classify each file based on its contents:

app.py

BASE_URL = "https://app.herondata.io"
BROKER_API_KEY = 'bft_xxxxxxxxx'

files = [
  ('files', ('statement_q4.pdf', open('statement_q4.pdf', 'rb'), 'application/pdf')),
  ('files', ('statement_q3.pdf', open('statement_q3.pdf', 'rb'), 'application/pdf'))
]

response = requests.post(
  f"{BASE_URL}/api/broker_submissions/{submission_heron_id}/files",
  headers={
    "x-api-key": BROKER_API_KEY,
  },
  data={"file_class": "bank_statement"},  # optional — applies to all files in this request
  files=files
)

response.raise_for_status()

upload_results = response.json()
# ^ [
#     { "file": "statement_q4.pdf", "status": "uploaded" },
#     { "file": "statement_q3.pdf", "status": "uploaded" }
#   ]

Because file_class applies to every file in the request, uploads with files of different classes must be split into separate requests (one per class). Alternatively, omit file_class and let Heron classify each file automatically.

Response Status Codes

The file upload endpoint returns different status codes based on the outcome:

201: All files uploaded successfully
207: Partial success - some files uploaded, others failed
400: All files failed validation or upload

For partial failures (207), the response will include details about which files succeeded and which failed:

[
  {
    "file": "statement.pdf",
    "status": "uploaded"
  },
  {
    "file": "invalid.pdf",
    "status": "error",
    "reason": "File type application/msword not allowed. Allowed: application/pdf"
  }
]

File Restrictions

When uploading files:

Only PDF files are accepted
Duplicate files for the same submission will be rejected

Get Started

Use Cases

Integrations

FAQs

Miscellaneous

Legacy Use Cases

Broker Submissions API

Prerequisites

Steps

1. Create a Broker Submission

2. Add Company and Owner Details

3. Upload PDF Files

Response Status Codes

File Restrictions

​Prerequisites

​Steps

​1. Create a Broker Submission

​2. Add Company and Owner Details

​3. Upload PDF Files

​Response Status Codes

​File Restrictions

Prerequisites

Steps

1. Create a Broker Submission

2. Add Company and Owner Details

3. Upload PDF Files

Response Status Codes

File Restrictions