Background Checks

The Background Check API screens a deal’s owners and business against public-records data and returns Heron’s structured work product: a per-subject breakdown of criminal records, bankruptcies, liens and judgments, lawsuits, UCC filings, sanctions / OFAC matches, corporate filings, and more, plus the outcome of each policy check you’ve configured. The flow is:

Make sure the deal’s owner and business details have reached Heron - usually automatically from the ISO applications you already send us.
Trigger the background check.
Poll for completion and fetch the results.

The background check runs asynchronously. Triggering it returns immediately; you poll the results endpoint until the run completes.

This page is the narrative walkthrough. The full request and response schema for each endpoint is generated from our OpenAPI spec and lives in the API reference, so it always matches the live API:

Prerequisites

Before following this guide, you will need:

An API key (see Authentication). All requests send it in the x-api-key header.
The background check product enabled for your account. Speak to your Heron rep to switch it on - it is not enabled by default.
An end user representing the deal you want to screen. Most integrations already have these - an end user is created whenever you send Heron an ISO application, or you can create one directly (Create EndUser). The calls below address it by its heron_id (an eus_ string) or your own end_user_id.

Steps

1. Make sure the deal’s details have reached Heron

The background check searches on the owner and business identity Heron holds for the deal. There are two ways that data gets there.

From your ISO applications (most common)

If you already send Heron the deal’s ISO application - by API or email forwarding - Heron extracts the owner and business details from it automatically. There’s nothing extra to do here; skip to step 2.

Send the details over the API

If you don’t send ISO applications, supply the identity directly with PATCH /end_users/{id}/end_user_information (reference):

app.py

import requests

BASE_URL = "https://app.herondata.io"
API_KEY = "key_xxxxxxxx"
end_user_heron_id = "eus_xxxxxxxx"  # the deal you're screening

requests.patch(
  f"{BASE_URL}/api/end_users/{end_user_heron_id}/end_user_information",
  headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
  json={
    "company_legal_business_name": "ACME Logistics LLC",
    "federal_tax_id": "12-3456789",
    "company_physical_address": {"line_1": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701"},
    "owner_1": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1985-03-20",
      "social_security_number": "123-45-6789",
      "home_address": {"line_1": "456 Oak Ave", "city": "Austin", "state": "TX", "zip": "78704"},
    },
  },
).raise_for_status()

The Set application data reference lists every accepted field. The fields that drive the background check search are:

Subject	Fields used
Owners	`first_name`, `last_name`, `social_security_number`, `date_of_birth`, `home_address`
Business	`company_legal_business_name`, `dba`, `federal_tax_id`, `company_physical_address`, `company_phone_number`

The more identity available, the more precise the match. A name is the minimum for an owner (first + last) and a legal name or DBA is the minimum for the business, but an owner’s SSN and date of birth is what reliably resolves them to the right person and avoids false matches. Up to two owners (owner_1, owner_2) are supported.

2. Trigger the background check

Start the check with the background_check enricher (reference). It returns 202 Accepted as soon as the run is dispatched:

app.py

import requests

BASE_URL = "https://app.herondata.io"
API_KEY = "key_xxxxxxxx"
end_user_heron_id = "eus_xxxxxxxx"  # the deal you're screening

requests.post(
  f"{BASE_URL}/api/end_user_enrichers/definitions/background_check/start_enrich",
  headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
  json={"end_user_heron_id": end_user_heron_id},
).raise_for_status()

3. Poll and fetch the results

Fetch the background check (reference) and read the top-level status until it is no longer processing:

app.py

import requests, time

BASE_URL = "https://app.herondata.io"
API_KEY = "key_xxxxxxxx"
end_user_heron_id = "eus_xxxxxxxx"  # the deal you're screening

def get_background_check():
  response = requests.get(
    f"{BASE_URL}/api/end_users/{end_user_heron_id}/background_check",
    headers={"x-api-key": API_KEY},
  )
  response.raise_for_status()
  return response.json()

result = get_background_check()
while result["status"] == "processing":
  time.sleep(10)
  result = get_background_check()

# status is now "succeeded", "failed", or "missing_input_data"

Status lifecycle

`status`	Meaning
`never_run`	No background check has been triggered for this end user yet.
`processing`	A run is in flight. `processing_stage` reports the phase: `searching`, `pulling_reports`, `analysing`.
`succeeded`	The run completed; `overall`, `subjects`, and `policy` are populated.
`failed`	The run errored. No results are available.
`missing_input_data`	No owner or business identity was available to search on (see step 1).

Understanding the result

A succeeded response has three parts:

overall - the headline: a result (pass / review_required / failed / missing_data), a severity, and pass / review / fail counts.
subjects[] - one entry per owner_1, owner_2, and business, each with how it was matched (resolution), the search trail (searches), and the findings grouped by record type (sections).
policy - the outcome of your configured checks, each with its status and the evidence (subject, section, and records) behind it.

The full field-level schema - every section type, record shape, and enum - is on the Get background check results reference page, generated from the live API. An abridged example to show the shape:

{
  "end_user_id": "eus_xxxxxxxx",
  "status": "succeeded",
  "overall": { "result": "review_required", "severity": "medium", "check_counts": { "pass": 12, "review": 2, "fail": 0 } },
  "subjects": [
    {
      "key": "owner_1",
      "kind": "person",
      "name": "Jane A Doe",
      "resolution": { "status": "found", "method": "ssn_dob", "confidence_score": 0.97 },
      "sections": [
        {
          "key": "criminal",
          "label": "Criminal Records",
          "count": 1,
          "severity": "medium",
          "flag": "fail",
          "records": [{ "offense": "Theft - petit", "disposition": "Convicted", "is_felony": false }]
        }
      ]
    },
    {
      "key": "business",
      "kind": "business",
      "name": "ACME Logistics LLC",
      "resolution": { "status": "found", "method": "name_state" },
      "duns_numbers": ["123456789"],
      "unreported_officers": ["John Smith"]
    }
  ],
  "policy": {
    "result": "review_required",
    "checks": [
      { "id": "owner_felony_recent", "auto_status": "pass", "evidence": { "subject_key": "owner_1", "section": "criminal" } }
    ]
  }
}

Affiliate reports

An owner’s report names other businesses and people: companies the owner is an officer of, filings under their name, and known associates. You can order a separate report on any of them. This is optional and off by default. Each report is billed once on top of the submission; ask your Heron rep to enable it and for the per-report rate.

Reports are pulled only when you ask for one. Running a background check, on any number of deals, never buys an affiliate report by itself.

The endpoint details are in the API reference:

1. List the affiliations

Once the deal’s background check has completed, list what it connected the deal to:

app.py

import requests

BASE_URL = "https://app.herondata.io"
API_KEY = "key_xxxxxxxx"
end_user_heron_id = "eus_xxxxxxxx"

affiliations = requests.get(
  f"{BASE_URL}/api/end_users/{end_user_heron_id}/background_check/affiliations",
  headers={"x-api-key": API_KEY},
).json()

for row in affiliations["businesses"]:
  print(row["subject_key"], row["index"], row["business_name"], row["source"], row["report"])

businesses and persons each list rows keyed by subject_key (the owner whose report named them) and index (its position in that list). Business rows carry a source: work_affiliation, corporate_officer or corporate_filing. Every row has report, which is null until a report has been requested for it.

2. Request the reports you want

Echo the subject_key, index and name of each row you want a report on, up to 25 per call:

app.py

response = requests.post(
  f"{BASE_URL}/api/end_users/{end_user_heron_id}/background_check/affiliations/reports",
  headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
  json={"affiliates": [
    {"subject_key": "owner_1", "kind": "business", "index": 2, "name": "ACME Freight Partners LLC",
     "search_inputs": {"street": "123 Main St", "city": "Austin", "state": "TX", "zip_code": "78701"}},
    {"subject_key": "owner_1", "kind": "person", "index": 0, "name": "John Smith",
     "search_inputs": {"date_of_birth": "1979-06-02", "state": "TX"}},
  ]},
)
response.raise_for_status()  # 202
refs = [r["ref"] for r in response.json()["requests"]]

The name must still match the listing, otherwise the call returns 409 and nothing is ordered, so a stale client cannot buy the wrong row. search_inputs is optional: where the source record already identifies the party, Heron fetches its report directly; otherwise it searches first, and these inputs narrow that search. The request itself buys nothing. It queues a background-check re-run, and that run pulls the reports.

3. Poll for the reports

Re-fetch the affiliations list and read each row’s report.status:

`report.status`	Meaning
`pending`	Requested, not yet pulled.
`succeeded`	The report is on the deal.
`not_found`	The search did not settle on one party. The candidates it found are on the row, confirm one (step 4).
`failed`	The pull errored. The next run retries it.

The reports themselves appear on the background check payload under affiliations.business[] and affiliations.person[], each with its own search trail and findings, shaped like a subject.

4. Confirm a candidate when the search was not conclusive

If a search found several parties, or you want to correct the one it chose, name the party from that row’s search trail:

app.py

requests.post(
  f"{BASE_URL}/api/end_users/{end_user_heron_id}/background_check/affiliations/reports/confirm",
  headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
  json={"ref": refs[0], "entity_id": "<entity_id from the row's search trail>"},
).raise_for_status()  # 202

Only a party that row’s own search identified is accepted; anything else returns 409. The new report replaces the one held for that row.

5. Withdraw a request

DELETE /api/end_users/{end_user_heron_id}/background_check/affiliations/reports/{ref} stops tracking the request, so later runs no longer pull it. Reports already pulled stay on the runs that produced them.

What you pay for

You pay for each affiliate report once, when it first arrives. Nothing else adds a charge:

Re-running the deal’s background check shows the report you already have. It is not bought again.
Confirming a different candidate, or changing a row’s search details, fetches a new report for that row at no extra charge.
A report that could not be pulled is retried on the next run and charged only when it arrives.
A deal on which nobody requested a report never pulls one, however many times its background check runs.

Downloading a report as a PDF

Heron returns the background check as structured data (above), which is the source of truth and the most flexible format to integrate against - you can render it however suits your product. We can also generate a single combined PDF covering all owners and the business in one document, branded as Heron’s work product.

Heron provides its own background check work product. We can’t redistribute the raw third-party reports our data comes from. If a rendered PDF is something you need, talk to your Heron rep about format and branding.

Get Started

API Reference

Use Cases

Integrations

Broker

FAQs

Miscellaneous

Legacy Use Cases

Background Checks

Prerequisites

Steps

1. Make sure the deal’s details have reached Heron

From your ISO applications (most common)

Send the details over the API

2. Trigger the background check

3. Poll and fetch the results

Status lifecycle

Understanding the result

Affiliate reports

1. List the affiliations

2. Request the reports you want

3. Poll for the reports

4. Confirm a candidate when the search was not conclusive

5. Withdraw a request

What you pay for

Downloading a report as a PDF

​Prerequisites

​Steps

​1. Make sure the deal’s details have reached Heron

​From your ISO applications (most common)

​Send the details over the API

​2. Trigger the background check

​3. Poll and fetch the results

​Status lifecycle

​Understanding the result

​Affiliate reports

​1. List the affiliations

​2. Request the reports you want

​3. Poll for the reports

​4. Confirm a candidate when the search was not conclusive

​5. Withdraw a request

​What you pay for

​Downloading a report as a PDF

Prerequisites

Steps

1. Make sure the deal’s details have reached Heron

From your ISO applications (most common)

Send the details over the API

2. Trigger the background check

3. Poll and fetch the results

Status lifecycle

Understanding the result

Affiliate reports

1. List the affiliations

2. Request the reports you want

3. Poll for the reports

4. Confirm a candidate when the search was not conclusive

5. Withdraw a request

What you pay for

Downloading a report as a PDF