Skip to main content
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: 
const BASE_URL = "https://api.herondata.io";
const BROKER_API_KEY = 'bft_xxxxxxxxx';

const response = await fetch(`${BASE_URL}/broker_submissions/`, {
  method: 'POST',
  headers: {
    'x-api-key': `${BROKER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'ABC Company - Working Capital Request',
  }),
});

const data = await response.json();
// ^ { heron_id: 'sub_xxxxxxxxx' }

const submissionHeronId = data.heron_id;
:::note 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: 
const BASE_URL = "https://api.herondata.io";
const BROKER_API_KEY = 'bft_xxxxxxxxx';

const response = await fetch(
  `${BASE_URL}/broker_submissions/${submissionHeronId}/update_information`,
  {
    method: 'POST',
    headers: {
      'x-api-key': `${BROKER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      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',
      },
    }),
  }
);

const updatedInfo = await response.json();
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: 
const BASE_URL = "https://api.herondata.io";
const BROKER_API_KEY = 'bft_xxxxxxxxx';

const formData = new FormData();
formData.append('files', pdfFile1);
formData.append('files', pdfFile2);

const response = await fetch(
  `${BASE_URL}/broker_submissions/${submissionHeronId}/files`,
  {
    method: 'POST',
    headers: {
      'x-api-key': `${BROKER_API_KEY}`,
    },
    body: formData,
  }
);

const uploadResults = await response.json();
// ^ [{ file: "statement_q4.pdf", status: "uploaded" }]

​
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