Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.herondata.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
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:
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={
    "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)
All fields in the update request are optional, allowing you to provide only the information you have available. See the API reference for details of full set of fields available for submission.

​
3. Upload PDF Files

Upload supporting documents to the submission. You can upload 1-5 PDF files per request. 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
  • Minimum 1 file per request
  • Maximum 5 files per request
  • Duplicate files for the same submission will be rejected