openapi: 3.2.0 info: contact: email: support@herondata.io name: Support title: Heron Data End Users API version: '2021-07-19' servers: - description: Production url: https://app.herondata.io security: - ApiKeyAuth: - key_XXX tags: - name: EndUsers paths: /api/end_user_emails: get: description: Get all emails for all end users associate with this user parameters: - in: query name: page required: true schema: minimum: 0 type: integer - in: query name: limit required: true schema: minimum: 1 type: integer responses: '200': content: application/json: schema: properties: _meta: properties: count: type: number has_more: type: boolean page: type: number total_pages: type: number type: object emails: items: properties: email: $ref: '#/components/schemas/EndUserEmailSchema' end_user_heron_id: type: string type: object type: array type: object description: OK security: - ApiKeyAuth: [] summary: Get EndUser emails tags: - EndUsers /api/end_users: get: description: Get a list of EndUsers parameters: - description: Unique ID generated by Heron in: query name: heron_id required: false schema: example: eus_2stYWxcgbmpHMFCDJLD72a type: - string - 'null' - description: Filter by ID associated with end_user_id field in transactions in: query name: end_user_id required: false schema: example: your_end_user_id type: - string - 'null' - description: Filter by name associated with end user in: query name: name required: false schema: example: your_end_user_name type: - string - 'null' - description: Filter by status of end user in: query name: status required: false schema: enum: - new - ready - processed - reviewed - review_requested - failed - null example: reviewed type: - string - 'null' - description: Pagination page number in: query name: page required: false schema: default: 1 minimum: 1 type: integer - description: Pagination limit per page in: query name: limit required: false schema: default: 1000 maximum: 10000 minimum: 1 type: integer - description: Order to return end users by in: query name: order_by required: false schema: default: last_updated_desc enum: - last_updated_desc - last_updated_asc - created_desc - created_asc type: string - description: Whether the end user is part of a lending portfolio in: query name: is_portfolio required: false schema: example: true type: - boolean - 'null' - description: Whether the to include data sources for each end user in: query name: include_data_sources required: false schema: default: false example: true type: boolean - description: Whether to include scorecard metrics for each end user (under field criteria) in: query name: include_scorecard_metrics required: false schema: default: false example: true type: boolean - description: Whether to include the tags applied to each end user in: query name: include_tags required: false schema: default: false example: true type: boolean responses: '200': content: application/json: schema: properties: _meta: properties: limit: example: 1000 type: integer next_url: type: string page: example: 1 type: integer pages: example: 3 type: integer prev_url: type: string total: example: 3500 type: integer type: object end_users: items: $ref: '#/components/schemas/EndUser' type: array type: object description: OK security: - ApiKeyAuth: [] summary: List EndUsers tags: - EndUsers post: description: 'Create a new end user. If transactions have previously been sent for this `end_user_id`, use `PUT end_users` to update instead. ' requestBody: content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUserPostParams' type: object required: true responses: '201': content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUser' type: object description: OK security: - ApiKeyAuth: [] summary: Create EndUser tags: - EndUsers put: callbacks: onData: $yourWebhookUrl: post: requestBody: content: application/json: schema: $ref: '#/components/schemas/EndUserWebhookPayload' description: Webhook payload with end_user responses: '200': description: 'Your webhook implementation should return this HTTP status code if the data was received successfully.' description: 'Confirm an end user is ready for async processing by sending a status of "ready". The `end_user_id` must have previously been sent with at least one Transaction if attempting to update the status. ' externalDocs: description: Webhook Tutorial url: https://docs.herondata.io/webhooks requestBody: content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUser' type: object description: Dictionary representing an EndUser required: true responses: '200': content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUser' type: object description: OK security: - ApiKeyAuth: [] summary: Update EndUser tags: - EndUsers /api/end_users/summary: get: description: Get a list of EndUsers parameters: - description: Unique ID generated by Heron in: query name: heron_id required: false schema: example: eus_2stYWxcgbmpHMFCDJLD72a type: - string - 'null' - description: Filter by ID associated with end_user_id field in transactions in: query name: end_user_id required: false schema: example: your_end_user_id type: - string - 'null' - description: Filter by name associated with end user in: query name: name required: false schema: example: your_end_user_name type: - string - 'null' - description: Filter by status of end user in: query name: status required: false schema: enum: - new - ready - processed - reviewed - review_requested - failed - null example: reviewed type: - string - 'null' - description: Pagination page number (optional). If provided, 'limit' must also be provided. in: query name: page required: false schema: minimum: 1 type: - integer - 'null' - description: Pagination limit per page (optional). If provided, 'page' must also be provided. in: query name: limit required: false schema: maximum: 10000 minimum: 1 type: - integer - 'null' - description: Order to return end users by in: query name: order_by required: false schema: default: last_updated_desc enum: - last_updated_desc - last_updated_asc - created_desc - created_asc type: string - description: Whether the end user is part of a lending portfolio in: query name: is_portfolio required: false schema: example: true type: - boolean - 'null' - description: Whether the to include data sources for each end user in: query name: include_data_sources required: false schema: default: false example: true type: boolean - description: Whether to include scorecard metrics for each end user (under field criteria) in: query name: include_scorecard_metrics required: false schema: default: false example: true type: boolean - description: Whether to include the tags applied to each end user in: query name: include_tags required: false schema: default: false example: true type: boolean - in: query name: with_policy_result required: false schema: enum: - passed - failed - review_required - missing_data - null - in: query name: with_crm_sync_result required: false schema: enum: - success - failure - no_sync_attempted - null - description: Filter to end users whose broker intake classification matches (e.g. 'submission') in: query name: broker_classification required: false schema: enum: - submission - decision - other - null - description: 'Filter to deals at this pipeline stage: ''ready'' before any send, ''missing_docs'' while an unshopped deal is tagged as missing statements or documents, ''shopped'' once a send to a funder has started. Broker customers only; ignored for others.' in: query name: deal_stage required: false schema: enum: - ready - missing_docs - shopped - null - description: Filter by whether an active document is pending human review in: query name: in_human_review required: false schema: type: - boolean - 'null' - in: query name: interval_start required: false schema: format: date-time type: - string - 'null' - in: query name: interval_end required: false schema: format: date-time type: - string - 'null' - description: When true, interval_start and interval_end match end users created or last updated within the window. Bounds are inclusive only when this flag is true. in: query name: include_updates_in_interval required: false schema: default: false type: boolean responses: '200': content: application/json: schema: properties: _meta: description: Pagination metadata. Present only if pagination parameters ('page' and 'limit') are provided in the request. properties: limit: example: 100 type: integer next_url: format: url type: - string - 'null' page: example: 1 type: integer pages: example: 3 type: integer prev_url: format: url type: - string - 'null' total: example: 350 type: integer type: object end_users: items: $ref: '#/components/schemas/EndUserSummary' type: array type: object description: OK security: - ApiKeyAuth: [] summary: List EndUsers with Summary Information tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check: get: description: 'Get the background check results for an end user, including the screening run status, each subject''s identity matches and records, and the outcome of each policy check. ' parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string - description: If true, each record additionally carries its full vendor detail under `detail` in: query name: include_section_detail required: false schema: default: false type: boolean - description: 'If true, each subject''s search trail is taken from that subject''s most recent run that used an automatic identity search, ignoring runs where the subject was manually pinned. Records and policy outcomes are unaffected. ' in: query name: exclude_manual required: false schema: default: false type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckResponseSchema' description: OK '404': description: End user not found security: - ApiKeyAuth: [] summary: Get EndUser background check dashboard payload tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/affiliations: get: description: 'Lists every business and person the deal''s background check connects it to: the businesses each owner is recorded as affiliated with, the people associated with them, and the people and companies named as officers on the business''s own filings. Each row carries the state of any report requested for it, and is absent until a background check has completed. ' parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckAffiliationsViewSchema' description: OK '404': description: End user not found, or affiliations are not enabled for this account security: - ApiKeyAuth: [] summary: List an end user's background check affiliations tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/affiliations/reports: post: description: 'Requests a background check report for each affiliation selected, business or person. Where the source records already identify the party, its report is retrieved for that party directly; otherwise a search runs first, and a search that settles on no single party returns `not_found` along with the parties it did find, so one can be confirmed. Poll the affiliations endpoint for progress. ' parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckAffiliateReportRequestSchema' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckAffiliateRequestAcceptedSchema' description: Report requests accepted '404': description: End user not found, or affiliations are not enabled for this account '409': description: The affiliation list has changed, this affiliation cannot have a report requested for it, or no completed background check exists security: - ApiKeyAuth: [] summary: Request background check reports for affiliations tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/affiliations/reports/confirm: post: description: 'Chooses which of the parties a search found the affiliation''s report should cover, either when the search settled on none of them or to correct an earlier choice. Only a party that affiliation''s own search identified can be chosen. Its report is retrieved in the background, replacing any report already held for that affiliation; poll the affiliations endpoint for progress. ' parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckAffiliateConfirmSchema' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckAffiliationReportState' description: Report pull accepted '404': description: End user not found, or affiliations are not enabled for this account '409': description: No report has been requested for this affiliation, or no report can be ordered for the chosen party - it is not one this affiliation's search identified security: - ApiKeyAuth: [] summary: Confirm a candidate for an affiliate report tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/affiliations/reports/{ref}: delete: description: 'Removes an affiliate report request, so later screening runs no longer pull a report for that affiliation. Reports already pulled remain on the runs that produced them. ' parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string - description: The affiliate report request reference returned when it was requested in: path name: ref required: true schema: type: string responses: '204': description: Request removed '404': description: End user not found, or affiliations are not enabled for this account '409': description: The affiliate report request does not exist security: - ApiKeyAuth: [] summary: Stop tracking an affiliate report tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/override: delete: description: Clears every subject's CLEAR candidate pin so the enricher runs its full search waterfall for all subjects on the next run. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string responses: '204': description: Overrides cleared '404': description: End user not found security: - ApiKeyAuth: [] summary: Clear all CLEAR candidate overrides for a background check tags: - EndUsers get: description: Returns the per-subject CLEAR entity_id pins the background-check enricher fetches reports for directly, skipping its search. An empty value means that subject still runs the full search waterfall. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckCandidateOverrideSchema' description: OK '404': description: End user not found security: - ApiKeyAuth: [] summary: Get the pinned CLEAR candidate overrides for a background check tags: - EndUsers post: description: Pins a CLEAR entity_id per subject (owner_1, owner_2, business) so the enricher fetches that candidate's report directly and skips its search. A null value clears that subject's pin; unpinned subjects still run the full search waterfall. Returns the current pins. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckCandidateOverrideSchema' responses: '200': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckCandidateOverrideSchema' description: OK '404': description: End user not found security: - ApiKeyAuth: [] summary: Pin CLEAR candidate overrides for a background check tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/subjects/{subject_key}/raw_report: get: description: Returns the requested subject's raw background check report as a base64-encoded JSON payload. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string - description: The background check subject whose raw report should be downloaded in: path name: subject_key required: true schema: enum: - owner_1 - owner_2 - business type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BackgroundCheckRawReportSchema' description: OK '404': description: End user or raw report not found security: - ApiKeyAuth: [] summary: Download a background check raw report tags: - EndUsers /api/end_users/{end_user_heron_id}/background_check/subjects/{subject_key}/records/{record_id}/mugshot: get: description: Returns the mug shot for one criminal or arrest record as authenticated image bytes. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string - description: The background check subject whose record should be viewed in: path name: subject_key required: true schema: enum: - owner_1 - owner_2 - business type: string - description: Stable reference of the criminal or arrest record in: path name: record_id required: true schema: type: string responses: '200': content: image/jpeg: schema: format: binary type: string image/png: schema: format: binary type: string description: Mug shot image '404': description: End user, record, or mug shot not found security: - ApiKeyAuth: [] summary: View a criminal-record mug shot tags: - EndUsers /api/end_users/{end_user_heron_id}/duplicate_end_users: get: description: 'Find duplicate end users for the given end user by matching on EIN (federal_tax_id) or normalized legal business name. Only returns duplicates within the same user (lender). Matching strategy: (1) Priority - Match by EIN when available (fast indexed query), (2) Fallback - Match by normalized company_legal_business_name when EIN is missing. Requires the count_duplicate_end_users feature flag to be enabled for the user. ' parameters: - description: The Heron ID of the end user to check for duplicates in: path name: end_user_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DuplicateEndUsersResponse' description: List of duplicate end users found '403': description: Feature not enabled for this user '404': description: End user not found security: - ApiKeyAuth: [] summary: Get duplicate end users for an end user tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}: delete: deprecated: true description: 'Synchronously delete an end user and its associated transactions. Deprecated — use POST /end_users/{end_user_id_or_heron_id}/delete for async deletion instead. ' parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '204': description: Deleted security: - ApiKeyAuth: [] summary: Delete EndUser by heron_id or end_user_id (sync) tags: - EndUsers get: description: 'Get an end user using its end_user_id or heron_id ' parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '200': content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUser' type: object description: Ok security: - ApiKeyAuth: [] summary: Get EndUser by heron_id or end_user_id tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/delete: post: description: 'Asynchronously delete an end user and its associated transactions. Returns immediately with a 202 status while deletion proceeds in the background. ' parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '202': content: application/json: schema: properties: heron_id: example: eus_Eqio3Y4dhyNiMphrXwG58p type: string status: example: pending type: string type: object description: Accepted — deletion is in progress security: - ApiKeyAuth: [] summary: Delete EndUser by heron_id or end_user_id (async) tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/emails: get: description: Get the emails associated with an end user parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/EndUserEmailSchema' type: array description: OK security: - ApiKeyAuth: [] summary: Get EndUser emails tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/end_user_information: get: description: Get the company details of an end user including loan information parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndUserInformationSchema' description: OK security: - ApiKeyAuth: [] summary: Get EndUser information tags: - EndUsers patch: description: Update the end user information parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EndUserInformationPatchSchema' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndUserInformationSchema' description: OK security: - ApiKeyAuth: [] summary: Patch EndUser information tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/enrich: post: description: 'Enriches transactions of an end user identified by its end_user_id or heron_id. There is an optional `priority` parameter that can be set to `high` to prioritize the enrichment over `normal` (default) priority. High priority enrichment is only enabled for enterprise-level accounts. Please contact support@herondata.io to upgrade your account. ' parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string - description: Priority for async enrichment in: query name: priority required: false schema: default: normal enum: - normal - high type: string responses: '200': content: application/json: schema: properties: end_user: $ref: '#/components/schemas/EndUser' type: object description: Ok security: - ApiKeyAuth: [] summary: Enrich transactions of EndUser tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/location: get: description: Get the company physical address coordinates parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndUserAddressLocationSchema' description: OK security: - ApiKeyAuth: [] summary: Get EndUser physical location tags: - EndUsers /api/end_users/{end_user_id_or_heron_id}/processing_status: get: description: 'Get the current processing status of an end user by heron_id or end_user_id. Returns whether the end user is currently being processed or has completed processing. ' parameters: - in: path name: end_user_id_or_heron_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndUserProcessingStatusSchema' description: Successfully retrieved processing status '404': description: End user not found security: - ApiKeyAuth: [] summary: Get EndUser processing status tags: - EndUsers /api/end_users/{heron_id}/crm_sync: get: parameters: - in: path name: heron_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/CrmSyncEventSchema' type: array description: The list of CRM events that occurred for this end user security: - ApiKeyAuth: [] summary: Retrieve CRM sync events for an end user tags: - EndUsers post: parameters: - in: path name: heron_id required: true schema: type: string responses: '200': content: application/json: schema: properties: crm_sync_triggered: type: boolean heron_id: description: The Heron ID of the End User type: string type: object description: Ok security: - ApiKeyAuth: [] summary: Trigger a CRM Sync for an End User tags: - EndUsers components: schemas: BackgroundCheckSubject: properties: application: allOf: - $ref: '#/components/schemas/BackgroundCheckApplication' description: Identity searched, taken from the application data. candidates: description: Every deduplicated candidate returned across the subject's searches, with its match score. items: $ref: '#/components/schemas/BackgroundCheckCandidate' type: array case_ref: description: Reserved case reference; null in normal use. type: - string - 'null' decision: allOf: - $ref: '#/components/schemas/BackgroundCheckDecision' description: Audit of how the winning candidate was selected; null when no scoring decision was needed. duns_numbers: description: D&B DUNS numbers of the resolved business. Empty for person subjects. items: type: string type: array key: description: 'Subject identifier: owner_1, owner_2, or business.' enum: - owner_1 - owner_2 - business type: string kind: description: 'Subject type: person or business.' enum: - person - business type: string name: description: 'Label for the subject: the matched record''s filed name for a business, the searched name for a person. Null when neither is known.' type: - string - 'null' related_party_officers: description: Business-filing officers who match a related party on the deal. items: type: string type: array resolution: allOf: - $ref: '#/components/schemas/BackgroundCheckResolution' description: How and whether the subject was matched. role: description: Subject's role on the deal; null when unavailable. type: - string - 'null' searches: description: Search waterfall in attempted order, including each step's inputs and outcome. items: $ref: '#/components/schemas/SearchAttempt' type: array sections: description: Report findings grouped by record type. items: $ref: '#/components/schemas/BackgroundCheckSection' type: array unreported_officers: description: Officers on active business filings who are not listed as owners on the application. Empty for person subjects. items: type: string type: array required: - application - candidates - key - kind - resolution - searches - sections - unreported_officers type: object BusinessContact: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: department: description: Department of the business contact. type: - string - 'null' emails: description: Business email addresses associated with the contact. items: type: string type: array job_level: description: Job level of the business contact. type: - string - 'null' linkedin_url: description: LinkedIn profile URL for the contact. type: - string - 'null' name: description: Name of the business contact. type: - string - 'null' organization: description: Organisation associated with the contact. type: - string - 'null' organization_addresses: description: Organisation addresses associated with the contact. items: $ref: '#/components/schemas/BusinessContactAddress' type: array phones: description: Business phone numbers associated with the contact. items: $ref: '#/components/schemas/ProfilePhone' type: array risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true source: description: Source that supplied the contact. type: - string - 'null' title: description: Title of the business contact. type: - string - 'null' type: object BackgroundCheckCheck: properties: area: description: Display group for the policy check. type: string area_sub: description: Display subgroup for the policy check; null when the check has none. type: - string - 'null' auto_reason: description: Explanation for the automated policy outcome; null when unavailable. type: - string - 'null' auto_status: description: 'Automated outcome: pass, review_required, failed, or missing_data.' enum: - pass - failed - review_required - missing_data check_text: description: Human-readable description of what the policy check evaluates. type: string evidence_subjects: description: Per-subject pointers to the findings that produced the policy outcome. items: $ref: '#/components/schemas/BackgroundCheckEvidence' type: array id: description: Stable check ID in : form. type: string override: allOf: - $ref: '#/components/schemas/BackgroundCheckOverride' description: Manual reviewer override; null when the automated outcome stands. rule: description: Configured threshold or rule expression; null when the check has none. type: - string - 'null' signal: description: Underlying attribute evaluated by the policy check. type: string required: - area - auto_status - check_text - evidence_subjects - id - signal type: object BackgroundCheckResolution: properties: aka_names: description: Also-known-as names on the resolved entity. items: type: string type: array entity_not_found: description: True when no matching entity was found. type: boolean match_threshold: description: The deciding evidence-score floor; null on older records. type: - number - 'null' method: description: 'Resolving search step: ssn_only, name_state_dob, name_address, name_state, corp_id, manual_recovery (a reviewer manually selected the match), or linked_entity_id (no search ran - the report naming this affiliation already identified them).' type: - string - 'null' report_retry_attempted: description: True when a failed report retrieval was retried. type: boolean report_unavailable: description: True when a match resolved but the report pull failed (distinct from a search-time error). type: boolean score_version: description: Version of the match-scoring model; null when unavailable. type: - string - 'null' status: description: 'Resolution status: found, not_found, or error.' enum: - found - not_found - error type: string winner_ref: description: Ref into the subject's candidates[] for the resolved match; null when unresolved. type: - string - 'null' required: - entity_not_found - report_retry_attempted - report_unavailable - status type: object BackgroundCheckRecordDetail: description: Supplementary source detail returned with include_section_detail=true. The summarised record is the stable typed interface. properties: additional_fields: description: Every source value not mapped to a named field, as label and value pairs. items: $ref: '#/components/schemas/DetailLabelValue' type: array arrests: description: Arrest entries as source-provided key and value pairs. items: additionalProperties: type: string type: object type: array attorneys: description: Counsel the source does not tie to a specific party. items: $ref: '#/components/schemas/DetailAttorney' type: array bail: description: Bail entries on the case. items: $ref: '#/components/schemas/DetailBail' type: array case: allOf: - $ref: '#/components/schemas/DetailCase' description: Case metadata; null when not a case record. charges: description: Charges on the case. items: $ref: '#/components/schemas/DetailCharge' type: array collateral: description: Collateral descriptions on the filing. items: type: string type: array creditors: description: Creditors named on the filing. items: type: string type: array debtors: description: Debtors named on the filing. items: $ref: '#/components/schemas/DetailLienDebtor' type: array defendant: allOf: - $ref: '#/components/schemas/DetailDefendant' description: Defendant details; null when not applicable. docket_entries: description: Docket entries on the case. items: $ref: '#/components/schemas/DetailDocketEntry' type: array entries: description: 'For merged cases: one entry per raw source record, carrying this same shape.' items: $ref: '#/components/schemas/BackgroundCheckRecordDetail' type: array filing: allOf: - $ref: '#/components/schemas/DetailFiling' description: Filing metadata; null when not a filing record. filing_relationship: description: Source-provided filing relationship; null when unavailable. type: - string - 'null' meeting_341: allOf: - $ref: '#/components/schemas/DetailMeeting341' description: 341 creditors' meeting; null when not applicable. parties: description: Parties named on the case. items: $ref: '#/components/schemas/DetailParty' type: array record_shape: description: Names the source shape this detail carries. type: - string - 'null' related: description: Related records as label and value pairs. items: $ref: '#/components/schemas/DetailLabelValue' type: array secured_parties: description: Secured parties named on the filing. items: $ref: '#/components/schemas/DetailLienDebtor' type: array source: allOf: - $ref: '#/components/schemas/DetailSource' description: Provenance of the source record; null when unavailable. source_entry_id: description: Source-provided source entry reference; null when unavailable. type: - string - 'null' type: object EndUserEndUserFile: properties: file_class: type: - string - 'null' filename: type: string heron_id: type: string renamed_filename: type: string type: object BusinessProfileRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: alternate_business_names: description: Other business names on the record. items: type: string type: array business_description: description: Description of the business's activity. type: - string - 'null' business_name: description: Business name on the record. type: - string - 'null' business_type: description: Source-provided business type. type: - string - 'null' company_contact: description: Company contact named by the source. type: - string - 'null' contact_title: description: Title of the company contact. type: - string - 'null' corporate_status: description: Source-provided corporate status. type: - string - 'null' current_outstanding_shares: description: Current outstanding share count. type: - string - 'null' fiscal_year_end: description: Fiscal year end from the source. type: - string - 'null' incorporation_date: description: Date the business was incorporated. format: date type: - string - 'null' last_annual_financial_date: description: Date of the latest annual financial information. format: date type: - string - 'null' legal_business_name: description: Legal business name on the record. type: - string - 'null' location_type: description: Source-provided business location type. type: - string - 'null' non_profit: description: Whether the business is a nonprofit. type: - boolean - 'null' number_of_employees: description: Source-provided employee count. type: - string - 'null' operating_status: description: Source-provided operating status. type: - string - 'null' parent_company: description: Immediate or ultimate parent company. type: - string - 'null' primary_naics_code: description: Primary NAICS industry code. type: - string - 'null' primary_naics_desc: description: Description of the primary NAICS industry code. type: - string - 'null' primary_sic_code: description: Primary SIC industry code. type: - string - 'null' primary_sic_desc: description: Description of the primary SIC industry code. type: - string - 'null' public_company: description: Whether the business is publicly traded. type: - boolean - 'null' registered_agent: description: Registered agent named by the source. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high secondary_naics_codes: description: Secondary NAICS industry codes. items: type: string type: array secondary_sic_codes: description: Secondary SIC industry codes. items: type: string type: array severity: description: Record severity tier, mirroring risk. readOnly: true shareholders: description: Shareholder information from the source. type: - string - 'null' source: description: Source that supplied the record. type: - string - 'null' state_of_incorporation: description: State where the business was incorporated. type: - string - 'null' stock_exchange: description: Stock exchange for a public company. type: - string - 'null' stock_ticker: description: Stock ticker for a public company. type: - string - 'null' website: description: Business website. type: - string - 'null' year_established: description: Year the business was established. type: - string - 'null' year_started: description: Year the business started operating. type: - string - 'null' type: object BackgroundCheckAffiliateRequestAcceptedSchema: properties: requests: description: 'One entry per selection: the report request accepted for processing, or the in-flight request it was deduplicated against.' items: $ref: '#/components/schemas/BackgroundCheckAffiliationReportState' type: array required: - requests type: object EndUserSummary: properties: broker_classification: description: How broker intake classified this end user's email thread (submission, decision, or other). Absent for end users processed before classification recording was introduced. enum: - submission - decision - other readOnly: true confidence: description: Aggregated confidence for the end user across all transactions; between 0 and 1 example: 0.42 readOnly: true type: number created: description: When the end user was created in Heron system example: '2026-07-03T12:24:30.665078' format: date-time readOnly: true type: string criteria: description: List of scorecard metrics items: $ref: '#/components/schemas/Metric' readOnly: true type: array crm_sync_result: allOf: - $ref: '#/components/schemas/CrmSyncEvent' data_sources: description: List of data source summaries for the end user items: $ref: '#/components/schemas/DataSource' readOnly: true type: array deal_stage: description: 'Where this deal sits in the broker pipeline: ''ready'' before any send, ''shopped'' once a send to a funder has started — a started send may already sit with the funder, so it never falls back to ''ready''. ''missing_docs'' is an unshopped deal tagged as missing statements or documents. Present for broker customers only.' enum: - ready - missing_docs - shopped readOnly: true end_user_id: description: id defined by user; links to the end_user_id for transactions example: 6a1d7831-8953-4f9f-a544-423cd8f48eb6 maxLength: 140 minLength: 1 type: string files: items: $ref: '#/components/schemas/EndUserEndUserFile' type: array heron_id: description: Unique id for end user generated by Heron example: eus_5yWkT2NZzCevkyPwbGhn2Z readOnly: true type: string in_human_review: description: Whether an active document is pending human review readOnly: true type: boolean is_portfolio: description: Whether the end user is part of a lending portfolio example: true type: boolean last_processed_at: description: When the end user was last successfully processed in Heron system example: '2026-08-14T12:24:30.678624' format: date-time readOnly: true type: string last_updated: description: When the end user was last updated in Heron system example: '2026-08-14T12:24:30.665119' format: date-time readOnly: true type: string name: description: Name of end user; may help to improve categorisation accuracy example: Company Name Inc. maxLength: 128 type: - string - 'null' policy_evaluation_results: description: One entry per use_case, carrying the latest evaluation's policy identity and result items: $ref: '#/components/schemas/PolicyEvaluationResult' type: array policy_evaluations: items: enum: - passed - failed - review_required - missing_data type: array profit_and_loss_layout: {} status: description: Status of end user; 'ready' triggers async processing, 'review_requested' triggers manual review request enum: - new - ready - processed - reviewed - review_requested - failed example: ready type: string required: - end_user_id type: object BackgroundCheckAffiliateSelection: properties: index: description: Position of the affiliation in that owner's list, as returned by the affiliations endpoint. minimum: 0 type: integer kind: description: Whether the selection is an affiliated business or person. enum: - person - business type: string name: description: Name shown for the affiliation; the request is rejected if the list has changed. type: string search_inputs: allOf: - $ref: '#/components/schemas/BackgroundCheckAffiliateSearchInputs' description: Details to search a corporate officer on, whose filing carries only a name. Optional, and ignored for selections whose source already holds search details. subject_key: description: 'The report whose list the selection refers to: an owner''s affiliations, or the people and companies named as officers on the business''s own filings.' enum: - owner_1 - owner_2 - business type: string required: - index - kind - name - subject_key type: object AddressLocation: properties: lat: type: number lng: type: number type: object CrmSyncEvent: properties: crm_record_url: type: - string - 'null' error_message: type: - string - 'null' heron_id: type: string name: type: string occurred_at: format: date-time type: string provider: type: - string - 'null' result: enum: - success - failure - no_sync_attempted success_message: type: - string - 'null' type: object BackgroundCheckEvidence: properties: filtered: description: True when record_indices is a matched subset. An empty filtered list means no records matched. type: boolean record_indices: description: Indices into the cited section's records array. items: type: integer type: array section: description: Section key containing the cited evidence; null when no section applies. type: - string - 'null' subject_key: description: 'Evidence subject: owner_1, owner_2, business, any_owner, or submission.' enum: - owner_1 - owner_2 - business - any_owner - submission - null type: - string - 'null' required: - filtered - record_indices type: object ProfileSsnIssuance: properties: expiration_date: description: SSN issuance expiration date; null when unavailable. type: - string - 'null' issuance_text: description: Source-provided SSN issuance summary. type: - string - 'null' issue_date: description: SSN issuance date; null when unavailable. type: - string - 'null' issue_state: description: State where the SSN was issued; null when unavailable. type: - string - 'null' type: object LawsuitRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: amount: description: Amount on the case as a decimal string; null when unavailable. type: - number - 'null' amount_type: description: 'What the lawsuit amount represents: demand or judgment.' enum: - judgment - award - demand - null type: - string - 'null' case_category: description: Source-provided case category. type: - string - 'null' case_number: description: Court case reference; null when unavailable. type: - string - 'null' case_status: description: 'Status classification: active, ended, judgment, or no_status. Judgment means entered and still counts as active.' enum: - active - ended - judgment - no_status - null case_sub_category: description: Source-provided case subcategory. type: - string - 'null' case_title: description: Case title; null when unavailable. type: - string - 'null' case_type: description: Source-provided case type. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' defendant_name: description: Defendant named on the case. type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request entry_count: description: Number of underlying source entries combined into this record. type: integer file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' is_active: description: True when the lawsuit appears to still be live. type: boolean is_felony: description: True when the docket record is felony-graded. type: boolean is_mca: description: True when the litigation was brought by a known merchant cash advance funder. type: boolean plaintiff_name: description: Plaintiff named on the case. type: - string - 'null' record_type: description: 'Record class: Lawsuit or Court docket.' type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true source_entries: description: Underlying source rows combined into this record. items: $ref: '#/components/schemas/LitigationEntrySchema' type: array source_entry_ids: description: References for the underlying source rows combined into this record. items: type: string type: array status_text: description: Source-provided status string. type: - string - 'null' type: object BackgroundCheckAffiliateReportRequestSchema: properties: affiliates: description: The affiliations to request CLEAR reports for, at most 25 per request. items: $ref: '#/components/schemas/BackgroundCheckAffiliateSelection' maxItems: 25 minItems: 1 type: array required: - affiliates type: object TagSchema: properties: color: description: 'Optional display color as a six-digit hex code such as #1a2b3c, normalized to lowercase.' type: - string - 'null' description: description: Optional human-readable description of the tag. type: - string - 'null' heron_id: description: Unique identifier for the tag readOnly: true type: string name: description: 'Identifier normalized to lowercase: alphanumeric plus ''_'', ''-'', '':'', up to 140 chars. Unique to your account (case-insensitive).' type: string required: - name type: object DetailLienDebtor: properties: address: description: Source-provided address; null when unavailable. type: - string - 'null' name: description: Source-provided name; null when unavailable. type: - string - 'null' owed_amount: description: Source-provided owed amount; null when unavailable. type: - string - 'null' role: description: Source-provided role; null when unavailable. type: - string - 'null' type: object BackgroundCheckCandidate: description: One deduplicated candidate across the subject's search attempts, including its match score. properties: address: description: Candidate address returned by the search. type: - string - 'null' aka_names: description: Also-known-as names on the candidate. items: type: string type: array basis: description: Search basis that returned the candidate, such as the matching name variant. type: - string - 'null' duns_numbers: description: D&B DUNS numbers from the business candidate; empty for person candidates. items: type: string type: array entity_id: description: Source entity identifier; null when unavailable. type: - string - 'null' group_id: description: Source record-group identifier; null when unavailable. type: - string - 'null' id: description: 'Stable candidate reference: source entity ID, or group ID as fallback.' type: string is_limited: description: Whether the candidate is a limited-data record; null when unknown. type: - boolean - 'null' matched_address: description: Non-primary address that matched the search; null when the primary address matched. type: - string - 'null' matched_aka_name: description: Also-known-as name that matched the search; null when the primary name matched. type: - string - 'null' name: description: Candidate name returned by the search. type: - string - 'null' rank: description: Candidate's position in the search results. type: - integer - 'null' relevance: description: Source relevance score for the search hit. type: - integer - 'null' score: allOf: - $ref: '#/components/schemas/CandidateScore' description: Match score audit; null when the candidate was not scored. required: - id type: object EndUserWebhookData: properties: end_user_id: description: Customer-supplied id for the end user example: myenduser type: string heron_id: description: Heron ID of the end user example: eus_Eqio3Y4dhyNiMphrXwG58p type: string status: description: Status of the end user (e.g. 'processed', 'reviewed') example: processed type: string type: object CorporateRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: annual_report_file_date: description: Date the filing office received the annual report; null when unavailable. format: date type: - string - 'null' associated_business_count: description: Number of associated businesses in the source business group. type: integer business_duns: description: DUNS number assigned to the filed business; null when unavailable. type: - string - 'null' business_group: description: Source grouping identifier for associated businesses. type: - string - 'null' business_name: description: The registered business name. type: - string - 'null' business_type: description: Source-provided business type on the filing; the first value when the source reports several. type: - string - 'null' corp_status: description: 'Filing status classification: active, inactive, dissolved, failed, or unknown. Failed covers forfeited, revoked, suspended, and administratively dissolved filings.' enum: - active - dissolved - inactive - failed - unknown corporation_number: description: Corporation number the filing office assigned to the entity; null when the source does not report one. type: - string - 'null' corporation_type: description: Source-provided corporation classification, separate from the filing's business type; null when unavailable. type: - string - 'null' duration: description: Source-provided duration date or term; null when unavailable. type: - string - 'null' federal_emp_id: description: Federal employer identification number listed on the filing. type: - string - 'null' filing_date: description: Filing date; null when unavailable. format: date type: - string - 'null' filing_history: description: Ordered filing events recorded for this corporate record. items: $ref: '#/components/schemas/CorporateFilingHistoryEntrySchema' type: array filing_office_duns: description: Source-provided filing DUNS number; null when unavailable. type: - string - 'null' filing_office_name: description: Office where the filing was recorded. type: - string - 'null' filing_state: description: State where the filing was recorded. type: - string - 'null' filing_state_name: description: Full name of the filing state. type: - string - 'null' former_names: description: Former business names listed on the filing. items: type: string type: array has_officers: description: True when the filing lists officers. type: boolean incorporation_date: description: Date the entity was incorporated. format: date type: - string - 'null' is_failed: description: True when the corporate filing status is failed. type: boolean notes: description: Source-provided note about the filing; null when unavailable. type: - string - 'null' officer_count: description: Number of officers listed on the filing. type: integer officer_names: description: Names of officers listed on the filing. items: type: string type: array owner_is_officer: description: True when the application's named owner appears among the filing's officers. type: boolean ownership_changed: description: True when officers changed across the entity's filings. type: boolean registered_agent: description: Registered agent listed on the filing. type: - string - 'null' registered_agent_address: description: Address of the registered agent listed on the filing. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true source: description: Source that supplied the record. type: - string - 'null' state_filing_number: description: Filing number recorded on the filing; null when the source does not report one. type: - string - 'null' state_of_incorporation: description: State where the entity was incorporated. type: - string - 'null' status: description: Source-provided corporate filing status. type: - string - 'null' status_date: description: Date the source recorded the corporate status; null when unavailable. format: date type: - string - 'null' status_effective_date: description: Date the filing became effective; null when unavailable. format: date type: - string - 'null' type: object LienJudgmentRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: amount: description: Amount on the record as a decimal string; null when unavailable. type: - number - 'null' amount_band: description: 'Amount band: none, small under $10,000, medium from $10,000 to $49,999.99, or large at $50,000 or more.' enum: - none - small - medium - large case_number: description: Court case reference; null when unavailable. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_location: description: Location of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' creditor_count: description: Number of creditors on the case. type: integer creditor_name: description: First creditor named on the case; null when unavailable. type: - string - 'null' debtor_name: description: Debtor named on the filing. type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request entry_count: description: Number of underlying source entries combined into this record. type: integer file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' filing_relationship: description: 'Relationship to another filing: released_by or release_of; null when unlinked.' type: - string - 'null' is_federal_tax_lien: description: True when the filing is a federal tax lien. type: boolean is_mca_creditor: description: True when the creditor is a known merchant cash advance funder. type: boolean is_released: description: True when the source no longer shows the lien as outstanding. Vacated and closed records are included, not only released ones. type: boolean record_type: description: Source-provided record class. type: - string - 'null' related_filing_number: description: Reference of the related filing; null when unlinked. type: - string - 'null' release_date: description: Lien release date; null when unreleased. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high satisfaction_date: description: Date the debt was satisfied as recorded on the source; null when unavailable. format: date type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true shared_case_key: description: Stable key for a record that appears on both owner and business reports; null when not shared. type: - string - 'null' shared_relationship: description: 'Where the shared record also appears: also_on_business or also_on_owner; null when not shared.' enum: - also_on_owner - also_on_business - null type: - string - 'null' source_entries: description: Underlying source rows combined into this record. items: $ref: '#/components/schemas/LienJudgmentEntrySchema' type: array source_entry_ids: description: References for the underlying source rows combined into this record. items: type: string type: array status: description: 'Lien status: open, released, vacated, or closed.' enum: - open - released - vacated - closed type_of_filing: description: Source-provided filing type, such as JUDGMENT LIEN, FEDERAL TAX LIEN, or STATE TAX LIEN. type: - string - 'null' type_of_satisfaction: description: How the debt was satisfied as recorded on the source; null when unavailable. type: - string - 'null' vacate_date: description: Judgment vacate date; null when not vacated. format: date type: - string - 'null' type: object DetailMeeting341: properties: date: description: Source-provided meeting date; null when unavailable. type: - string - 'null' location: description: Source-provided meeting location; null when unavailable. type: - string - 'null' time: description: Source-provided meeting time; null when unavailable. type: - string - 'null' type: object EndUserInformationSchema: properties: amount_requested: type: - number - 'null' annual_revenue: type: - number - 'null' business_start_date: format: date type: - string - 'null' company_billing_address: $ref: '#/components/schemas/Address' company_email: type: - string - 'null' company_legal_business_name: type: - string - 'null' company_phone_number: type: - string - 'null' company_physical_address: $ref: '#/components/schemas/Address' company_website: type: - string - 'null' dba: description: Doing business as type: - string - 'null' federal_tax_id: type: - string - 'null' industry_type: type: - string - 'null' loan_purpose: type: - string - 'null' monthly_revenue: type: - number - 'null' naics: type: - string - 'null' owner_1: $ref: '#/components/schemas/Owner' owner_2: $ref: '#/components/schemas/Owner' predicted_industry_probability: type: - number - 'null' source_email_address: type: - string - 'null' source_name: type: - string - 'null' source_notes: type: - string - 'null' source_type: description: Source of the end user information enum: - api - iso_application_form - heron_industry_classifier - rel6_industry_classifier - email - end_user_entities example: iso_application_form type: string state_of_incorporation: type: - string - 'null' type_of_business_entity: type: - string - 'null' type: object EndUserProcessingStatusSchema: properties: status: description: Current processing status of the end user enum: - processing - processed example: processed required: - status type: object BackgroundCheckAffiliateConfirmSchema: properties: entity_id: description: The chosen candidate's entity identifier from the report's search trail. type: string ref: description: The affiliate report request reference, as returned when it was requested. type: string required: - entity_id - ref type: object CandidateScore: properties: anchor_trace: allOf: - $ref: '#/components/schemas/CandidateAnchorTrace' description: Winner-only; null otherwise. anchored_by: description: The anchor identifier that resolved the match (e.g. ein); winner-only. type: - string - 'null' cap_trace: allOf: - $ref: '#/components/schemas/CandidateCapTrace' description: Audit of the score cap; null when no cap was applied. capped_by: description: Names the clamp when the total isn't the contribution sum (e.g. zero_floor); null otherwise. type: - string - 'null' contributions: description: Per-field ledger of contributions to the candidate's match score. items: $ref: '#/components/schemas/CandidateScoreContribution' type: array tier: description: 'Score tier: high, medium, or low.' enum: - high - medium - low type: string total: description: The match score as a fraction in [0, 1]. type: number version: description: Match-scoring model version. type: string required: - contributions - tier - total - version type: object SearchAttemptCandidateRef: properties: id: description: Reference to the matching entry in candidates. type: string matched_address: description: Address matched on this step; present only when it differs from the canonical entry. type: string matched_aka_name: description: AKA name matched on this step; present only when it differs from the canonical entry. type: string rank: description: Rank on this step; present only when it differs from the canonical entry. type: integer relevance: description: Relevance on this step; present only when it differs from the canonical entry. type: integer score_total: description: Match score on this step; present only when it differs from the canonical entry. type: number required: - id type: object LienJudgmentEntrySchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: amount: description: Amount on the record as a decimal string; null when unavailable. type: - number - 'null' amount_band: description: 'Amount band: none, small under $10,000, medium from $10,000 to $49,999.99, or large at $50,000 or more.' enum: - none - small - medium - large case_number: description: Court case reference; null when unavailable. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_location: description: Location of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' creditor_count: description: Number of creditors on the case. type: integer creditor_name: description: First creditor named on the case; null when unavailable. type: - string - 'null' debtor_name: description: Debtor named on the filing. type: - string - 'null' file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' filing_relationship: description: 'Relationship to another filing: released_by or release_of; null when unlinked.' type: - string - 'null' is_federal_tax_lien: description: True when the filing is a federal tax lien. type: boolean is_mca_creditor: description: True when the creditor is a known merchant cash advance funder. type: boolean is_released: description: True when the source no longer shows the lien as outstanding. Vacated and closed records are included, not only released ones. type: boolean original_filing_number: description: Original filing number for this source entry. type: - string - 'null' record_type: description: Source-provided record class. type: - string - 'null' related_filing_number: description: Reference of the related filing; null when unlinked. type: - string - 'null' release_date: description: Lien release date; null when unreleased. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high satisfaction_date: description: Date the debt was satisfied as recorded on the source; null when unavailable. format: date type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' type_of_filing: description: Source-provided filing type, such as JUDGMENT LIEN, FEDERAL TAX LIEN, or STATE TAX LIEN. type: - string - 'null' type_of_satisfaction: description: How the debt was satisfied as recorded on the source; null when unavailable. type: - string - 'null' vacate_date: description: Judgment vacate date; null when not vacated. format: date type: - string - 'null' type: object CriminalSectionRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: actual_release_date: description: Actual release date from custody; null when unavailable. format: date type: - string - 'null' arrest_date: description: Date of the arrest; null when unavailable. format: date type: - string - 'null' arrest_time: description: Time of the arrest; null when unavailable. type: - string - 'null' arresting_agency: description: Arresting agency named on the source record; null when unavailable. type: - string - 'null' bail_amount: description: Bail amount on the record as a decimal string; null when unavailable. type: - number - 'null' booking_date: description: Date of the booking; null when unavailable. format: date type: - string - 'null' booking_location: description: Booking location; null when unavailable. type: - string - 'null' booking_number: description: Booking reference; null when unavailable. type: - string - 'null' booking_time: description: Time of the booking; null when unavailable. type: - string - 'null' case_number: description: Court case reference; null when unavailable. type: - string - 'null' case_status: description: The court's live case status, such as DISCHARGE or PENDING. Can resolve a case even when no disposition is recorded; null when unavailable. type: - string - 'null' case_status_date: description: Date of the case status; null when unavailable. format: date type: - string - 'null' categories: description: 'Offence classifications: fraud, violent, dui, drug, burglary, domestic_violence, child_related, sex_offense, murder_homicide, fiduciary, or other.' items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array category: description: Source-provided offence category string. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' crime_date: description: Date the offence occurred, distinct from the case filing date; null when unavailable. format: date type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request disposition: description: Case or charge outcome; null when unavailable. type: - string - 'null' disposition_date: description: Date of the disposition; null when unavailable. format: date type: - string - 'null' entry_count: description: Number of underlying source entries combined into this record. type: integer filed_date: description: Case filing date; null when unavailable. format: date type: - string - 'null' fine_amount: description: Fine imposed as a decimal string; null when unavailable. type: - number - 'null' grade: description: 'Offence grade: felony, misdemeanor, petty_misdemeanor, infraction, or unknown.' enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown is_dismissed: description: True when the case was dismissed or not prosecuted. type: boolean is_felony: description: True when any charge on the case is a felony. type: boolean is_unclassified: description: True when the offence could not be classified. type: boolean mugshot_record_id: description: Stable identifier used to request this record's mug shot; null when no mug shot is available. type: - string - 'null' number_of_counts: description: Number of counts; null when unavailable. type: - integer - 'null' offense: description: Offence as recorded on the source document. type: - string - 'null' offense_county: description: County where the offence occurred; null when unavailable. type: - string - 'null' offense_location: description: Where the offence took place; null when unavailable. type: - string - 'null' parole_status: description: Parole status; null when unavailable. type: - string - 'null' plea: description: The plea entered - the changed plea when one exists, else the original; null when unavailable. type: - string - 'null' plea_date: description: Date of the plea; null when unavailable. format: date type: - string - 'null' probation_end_date: description: Probation end date - the actual end when recorded, else the scheduled end; null when unavailable. format: date type: - string - 'null' probation_violation: description: Probation violation as recorded on the source; null when unavailable. type: - string - 'null' projected_release_date: description: Projected release date from custody, falling back to the tentative then maximum release date; null when unavailable. format: date type: - string - 'null' record_type: description: 'Record class: Criminal case or Arrest record.' type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high sentence: description: Sentence text; null when unavailable. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true severity_text: description: Source-provided severity string. type: - string - 'null' shared_case_key: description: Stable key for a record that appears on both owner and business reports; null when not shared. type: - string - 'null' shared_relationship: description: 'Where the shared record also appears: also_on_business or also_on_owner; null when not shared.' enum: - also_on_owner - also_on_business - null type: - string - 'null' source_entries: description: 'Underlying source rows combined into this record: one per charge for a court case, one per reported arrest entry for an arrest.' items: $ref: '#/components/schemas/CriminalSectionEntrySchema' type: array source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' source_entry_ids: description: References for the underlying source rows combined into this record. items: type: string type: array state: description: State the arrest record was reported in; null when unavailable. type: - string - 'null' statute_code: description: Statute code; null when unavailable. type: - string - 'null' type: object BackgroundCheckSection: description: A subject's findings for one record type. Record fields differ by section key. properties: addresses: description: Known addresses. Populated only on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/ProfileAddress' type: array akas: description: Also-known-as names. Populated only on the `profile` section; empty elsewhere. items: type: string type: array business_contacts: description: Business contacts shown on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/BusinessContact' type: array business_profile_details: description: Customer-safe business identity and profile details shown on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/BusinessProfileRecordSchema' type: array corporate_records: description: Business corporate filings shown on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/CorporateRecordSchema' type: array count: description: Number of records in the section. type: integer emails: description: Known email addresses. Populated only on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/ProfileEmail' type: array entry_count: description: Number of underlying source entries before roll-up; null for sections without combined records. type: - integer - 'null' flag: description: 'Policy flag for this section: ok or fail; null when no policy check cites it.' enum: - ok - fail - null type: - string - 'null' key: description: 'Section identifier: profile, criminal, bankruptcy, liens, lawsuits, marriage, affiliations, ofac, corporate, ucc, or industry.' enum: - profile - criminal - bankruptcy - liens - ucc - lawsuits - marriage - affiliations - corporate - ofac - industry type: string label: description: Display label for the section. type: string phones: description: Populated only on the `profile` section; empty elsewhere. items: $ref: '#/components/schemas/ProfilePhone' type: array records: description: Section rows. Fields differ by section key; the profile section has no rows. items: oneOf: - $ref: '#/components/schemas/CriminalRecordSchema' - $ref: '#/components/schemas/CriminalSectionRecordSchema' - $ref: '#/components/schemas/BankruptcyRecordSchema' - $ref: '#/components/schemas/LienJudgmentRecordSchema' - $ref: '#/components/schemas/LawsuitRecordSchema' - $ref: '#/components/schemas/MarriageRecordSchema' - $ref: '#/components/schemas/AssociateRecordSchema' - $ref: '#/components/schemas/OfacRecordSchema' - $ref: '#/components/schemas/CorporateRecordSchema' - $ref: '#/components/schemas/UCCRecordSchema' - $ref: '#/components/schemas/BusinessProfileRecordSchema' type: array severity: description: 'Highest record severity in the section: none, low, medium, or high.' enum: - none - low - medium - high type: string ssn_issuance: allOf: - $ref: '#/components/schemas/ProfileSsnIssuance' description: SSN issuance details. Populated only on the `profile` section; null elsewhere. work_affiliations: description: Populated only on the `affiliations` section; empty elsewhere. items: $ref: '#/components/schemas/WorkAffiliation' type: array required: - count - key - label - records - severity type: object DuplicateEndUsersResponse: properties: duplicates: description: List of duplicate end users with their heron IDs, names, and created dates items: $ref: '#/components/schemas/DuplicateEndUser' type: array required: - duplicates type: object DetailDocketEntry: properties: attorney: description: Source-provided attorney; null when unavailable. type: - string - 'null' date: description: Source-provided entry date; null when unavailable. type: - string - 'null' description: description: Source-provided entry description; null when unavailable. type: - string - 'null' disposition: description: Source-provided disposition; null when unavailable. type: - string - 'null' docketed_date: description: Source-provided docketed date; null when unavailable. type: - string - 'null' document: description: Source-provided document; null when unavailable. type: - string - 'null' entry_number: description: Source-provided entry number; null when unavailable. type: - string - 'null' fee: description: Source-provided fee; null when unavailable. type: - string - 'null' file_type: description: Source-provided file type; null when unavailable. type: - string - 'null' judge: description: Source-provided judge; null when unavailable. type: - string - 'null' location: description: Source-provided location; null when unavailable. type: - string - 'null' misc: description: Source-provided miscellaneous notes; null when unavailable. type: - string - 'null' party: description: Source-provided party; null when unavailable. type: - string - 'null' party_type: description: Source-provided party type; null when unavailable. type: - string - 'null' room: description: Source-provided room; null when unavailable. type: - string - 'null' time: description: Source-provided time; null when unavailable. type: - string - 'null' type: object UCCRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: collateral_description: description: Collateral description on the filing. type: - string - 'null' collateral_descriptions: description: Collateral descriptions across the filing chain. items: type: string type: array debtor_address: description: Address of the debtor. type: - string - 'null' debtor_name: description: Debtor named on the filing. type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request entry_count: description: Number of underlying source entries combined into this record. type: integer expire_date: description: Filing lapse date; null when unavailable. format: date type: - string - 'null' file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' filing_number: description: Filing reference number. type: - string - 'null' filing_office_name: description: Office where the filing was recorded. type: - string - 'null' filing_state: description: State where the filing was recorded. type: - string - 'null' filing_type: description: Filing type, such as FINANCING STATEMENT, CONTINUATION, or TERMINATION. type: - string - 'null' in_recent_cluster: description: True when the filing is among at least three new UCC liens in the last six months. type: boolean is_active: description: True when the filing chain is active. type: boolean is_recent: description: True when the filing originated recently. type: boolean is_terminated: description: True when the filing chain is terminated. type: boolean original_file_number_full: description: Full reference for the original filing in the chain. type: - string - 'null' record_type: description: Source-provided record class. type: - string - 'null' reference_file_number: description: Reference linking this row to the original filing in the chain. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high secured_party_address: description: Address of the secured party. type: - string - 'null' secured_party_name: description: Name of the secured party. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true source_entries: description: Underlying source rows combined into this record. items: $ref: '#/components/schemas/UCCFilingEntrySchema' type: array source_entry_ids: description: References for the underlying source rows combined into this record. items: type: string type: array status: description: 'UCC filing-chain status: active, terminated, expired, or unknown.' enum: - active - terminated - expired - unknown type: object EndUserInformationPatchSchema: properties: amount_requested: type: - number - 'null' annual_revenue: type: - number - 'null' business_start_date: format: date type: - string - 'null' company_billing_address: $ref: '#/components/schemas/Address' company_email: type: - string - 'null' company_legal_business_name: type: - string - 'null' company_phone_number: type: - string - 'null' company_physical_address: $ref: '#/components/schemas/Address' company_website: type: - string - 'null' dba: description: Doing business as type: - string - 'null' federal_tax_id: type: - string - 'null' industry_type: type: - string - 'null' loan_purpose: type: - string - 'null' monthly_revenue: type: - number - 'null' naics: type: - string - 'null' owner_1: $ref: '#/components/schemas/Owner' owner_2: $ref: '#/components/schemas/Owner' predicted_industry_probability: type: - number - 'null' source_email_address: type: - string - 'null' source_name: type: - string - 'null' source_notes: type: - string - 'null' state_of_incorporation: type: - string - 'null' type_of_business_entity: type: - string - 'null' type: object SearchAttempt: properties: candidate_count: description: Number of candidates this step returned. type: integer candidate_refs: description: References into candidates for every candidate returned by this search step. items: $ref: '#/components/schemas/SearchAttemptCandidateRef' type: array inputs: allOf: - $ref: '#/components/schemas/SearchInputsUsed' description: Exact identifiers sent on this search step. is_resolving_match: description: True on the search step whose match became the subject resolution. type: boolean matched_group_id: description: Opaque source group identifier for support investigations; null when unmatched. type: - string - 'null' outcome: description: 'Search outcome: matched, no_match, one_candidate, multiple_candidates, verification_failed, or error.' enum: - matched - no_match - one_candidate - multiple_candidates - verification_failed - error type: string outcome_reason: allOf: - $ref: '#/components/schemas/SearchAttemptOutcomeReason' description: Human-readable explanation of the search outcome; null when unavailable. resolved: description: True when this search confidently resolved the subject and ended the search waterfall. type: boolean search_method: description: 'Search method: ssn_only, name_state_dob, name_address, name_state, corp_id, manual_recovery, or linked_entity_id (see the resolution method).' type: string top_relevance: description: Source relevance score of the best hit; null when no candidate was returned. type: - integer - 'null' required: - candidate_count - candidate_refs - inputs - is_resolving_match - outcome - resolved - search_method type: object BackgroundCheckOverall: properties: check_counts: allOf: - $ref: '#/components/schemas/BackgroundCheckCheckCounts' description: Policy check totals. result: description: 'Headline result: passed, review_required, failed, or missing_data.' enum: - passed - failed - review_required - missing_data severity: description: 'Highest severity found: none, low, medium, or high.' enum: - none - low - medium - high type: string required: - check_counts - result - severity type: object DetailBail: properties: bond_number: description: Source-provided bond number; null when unavailable. type: - string - 'null' bondsman: description: Source-provided bondsman; null when unavailable. type: - string - 'null' date: description: Source-provided bail date; null when unavailable. type: - string - 'null' posted: description: Source-provided posted amount; null when unavailable. type: - string - 'null' status: description: Source-provided bail status; null when unavailable. type: - string - 'null' type: object ProfilePhone: properties: carrier: description: Phone carrier; null when unavailable. type: - string - 'null' number: description: Phone number. type: - string - 'null' source: description: Source that supplied the record. type: - string - 'null' type: description: Source-provided phone type. type: - string - 'null' type: object BackgroundCheckAffiliateSearchInputs: properties: city: description: City of the address to search on. type: - string - 'null' date_of_birth: description: The person's date of birth; ignored for a business. format: date type: - string - 'null' phone: description: Phone number on file; ignored for a person. type: - string - 'null' state: description: State of the address to search on. type: - string - 'null' street: description: Street of the address to search on. type: - string - 'null' zip_code: description: ZIP code of the address to search on. type: - string - 'null' type: object BackgroundCheckNearTie: properties: flag_counts: additionalProperties: type: integer description: Adverse-flag counts per probed candidate, keyed by candidate id; null when not probed. type: - object - 'null' gap: description: Difference between the top two candidate scores. type: number probed: description: True when both near-tied candidate reports were retrieved and compared. type: boolean required: - gap - probed type: object LitigationEntrySchema: properties: case_number: description: Court case reference; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' record_type: description: 'Source record class: lawsuit or court docket.' type: - string - 'null' source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' status_text: description: Source-provided status string. type: - string - 'null' type: object BusinessContactAddress: properties: city: description: City of the contact's organisation address. type: - string - 'null' country: description: Country of the contact's organisation address. type: - string - 'null' state: description: State or province of the contact's organisation address. type: - string - 'null' street: description: Street address of the contact's organisation. type: - string - 'null' zip_code: description: Postal code of the contact's organisation address. type: - string - 'null' type: object BackgroundCheckResponseSchema: description: Dates use YYYY-MM-DD. Amounts are decimal strings. Nullable source fields return null. SSNs remain masked; full SSNs never appear. properties: affiliations: allOf: - $ref: '#/components/schemas/BackgroundCheckAffiliationsBlock' description: Reports requested for the subjects' affiliated businesses and people; null when none requested. end_user_id: description: Heron ID of the end user type: string overall: allOf: - $ref: '#/components/schemas/BackgroundCheckOverall' description: Headline outcome across all background checks; null until an outcome is available. policy: allOf: - $ref: '#/components/schemas/BackgroundCheckPolicy' description: Outcome of each configured background-check policy check; null until available. processing_stage: description: 'While processing: searching, pulling_reports, or analysing. Null otherwise.' enum: - searching - pulling_reports - analysing - null type: - string - 'null' status: description: 'Run lifecycle: never_run, processing, succeeded, failed, or missing_input_data.' enum: - never_run - processing - succeeded - failed - missing_input_data type: string subjects: description: 'One entry per searched subject: owner_1, owner_2 when present, and business.' items: $ref: '#/components/schemas/BackgroundCheckSubject' type: array required: - end_user_id - status - subjects type: object OfacRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: action_end_date: description: Date the excluded-party action ended. format: date type: - string - 'null' action_start_date: description: Date the excluded-party action began. format: date type: - string - 'null' action_term: description: Source-provided duration of the excluded-party action. type: - string - 'null' aliases: description: Aliases listed on the sanctions record. items: type: string type: array authority: description: Authority that issued the excluded-party action, such as SAM. type: - string - 'null' charge: description: Charge named on the excluded-party record. type: - string - 'null' city: description: City listed on the sanctions record. type: - string - 'null' country: description: Country listed on the sanctions record. type: - string - 'null' document_title: description: Title of the sanctions document. type: - string - 'null' entity_type: description: Entity type on the source record, such as INDIVIDUAL, COMPANY, or ORGANIZATION. type: - string - 'null' finding: description: Finding stated on the excluded-party record. type: - string - 'null' issuer: description: Issuer named on the sanctions record. type: - string - 'null' issuer_category: description: Category of the sanctions issuer. type: - string - 'null' name: description: Name on the sanctions or excluded-party record. type: - string - 'null' position_role: description: Position or role listed on the sanctions record. type: - string - 'null' publication_date: description: Source publication date; null when unavailable. format: date type: - string - 'null' publication_name: description: Publication named on the excluded-party record. type: - string - 'null' region: description: Region listed on the sanctions record. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high sanction_full_text: description: Full text of the sanctions record. type: - string - 'null' sanction_type: description: Type of sanction. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true source: description: Source that supplied the record. type: - string - 'null' type: object DetailLabelValue: properties: label: description: Display label for the source value. type: string value: description: Value paired with the label; null when unavailable. type: - string - 'null' required: - label type: object EndUserEmailSchema: properties: cc_addresses: items: type: string type: array created: format: date-time type: string date_sent: format: date-time type: string date_sent_string: type: string from_address: type: string from_address_domain: type: string from_name: type: string heron_id: type: string html_body: type: string html_or_text_body: type: string is_reply: type: boolean processing_status: enum: - new - processing - processed - failed type: string reply_to: type: - string - 'null' subject: type: string subject_cleaned: type: string text_body: type: string to_addresses: items: type: string type: array viewer_url: description: a temporary, secure URL for viewing the email contents type: string type: object EndUserWebhookPayload: properties: created: description: When the webhook was fired format: date-time type: string data: allOf: - $ref: '#/components/schemas/EndUserWebhookData' description: End user details meta: additionalProperties: {} description: Customer-provided metadata from the end user, if any type: - object - 'null' topic: description: Webhook topic, e.g. `end_user.processed` type: string type: object EndUserPostParams: properties: confidence: description: Aggregated confidence for the end user across all transactions; between 0 and 1 example: 0.42 readOnly: true type: number created: description: When the end user was created in Heron system example: '2026-07-03T12:24:30.665078' format: date-time readOnly: true type: string criteria: description: List of scorecard metrics items: $ref: '#/components/schemas/Metric' readOnly: true type: array data_sources: description: List of data source summaries for the end user items: $ref: '#/components/schemas/DataSource' readOnly: true type: array end_user_id: description: id defined by user; links to the end_user_id for transactions example: 6a1d7831-8953-4f9f-a544-423cd8f48eb6 maxLength: 140 minLength: 1 type: string heron_id: description: Unique id for end user generated by Heron example: eus_5yWkT2NZzCevkyPwbGhn2Z readOnly: true type: string is_portfolio: description: Whether the end user is part of a lending portfolio example: true type: boolean last_processed_at: description: When the end user was last successfully processed in Heron system example: '2026-08-14T12:24:30.678624' format: date-time readOnly: true type: string last_updated: description: When the end user was last updated in Heron system example: '2026-08-14T12:24:30.665119' format: date-time readOnly: true type: string meta: additionalProperties: type: string description: 'Arbitrary key-value metadata. Max 20 keys, key ≤64 chars, value ≤256 chars, total ≤4KB. Example: {"attribution_key": "lender_42"}' type: - object - 'null' name: description: Name of end user; may help to improve categorisation accuracy example: Company Name Inc. maxLength: 128 type: - string - 'null' profit_and_loss_layout: {} tags: description: Tags currently applied to this end user, read-only. Absent unless the endpoint returns them. items: $ref: '#/components/schemas/TagSchema' readOnly: true type: array required: - end_user_id type: object DetailDefendant: properties: additional_fields: description: Unmapped source values as label and value pairs. items: $ref: '#/components/schemas/DetailLabelValue' type: array address: description: Source-provided address; null when unavailable. type: - string - 'null' dob: description: Source-provided date of birth; null when unavailable. type: - string - 'null' name: description: Source-provided defendant name; null when unavailable. type: - string - 'null' sex: description: Source-provided sex; null when unavailable. type: - string - 'null' type: object BackgroundCheckAffiliateReport: properties: kind: description: Whether the report is for an affiliated business or person. enum: - person - business type: string name: description: Name of the affiliate the report was requested for. type: string ref: description: Stable reference for this affiliate report request; echo it when confirming a candidate or removing the request. type: string status: description: 'Report lifecycle: pending until the next screening run pulls it, succeeded when the report is ready, not_found when no confident match was found (a candidate can be confirmed), or failed.' enum: - pending - succeeded - not_found - failed type: string subject: allOf: - $ref: '#/components/schemas/AffiliateSubject' description: The affiliate's search trail and report findings, shaped like a subject; null when it failed. required: - kind - name - ref - status type: object UCCFilingEntrySchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: collateral_description: description: Collateral description on the filing. type: - string - 'null' collateral_descriptions: description: Collateral descriptions across the filing chain. items: type: string type: array debtor_address: description: Address of the debtor. type: - string - 'null' debtor_name: description: Debtor named on the filing. type: - string - 'null' expire_date: description: Filing lapse date; null when unavailable. format: date type: - string - 'null' file_date: description: Filing date; null when unavailable. format: date type: - string - 'null' filing_number: description: Filing reference number. type: - string - 'null' filing_office_name: description: Office where the filing was recorded. type: - string - 'null' filing_state: description: State where the filing was recorded. type: - string - 'null' filing_type: description: Filing type, such as FINANCING STATEMENT, CONTINUATION, or TERMINATION. type: - string - 'null' in_recent_cluster: description: True when the filing is among at least three new UCC liens in the last six months. type: boolean is_recent: description: True when the filing originated recently. type: boolean original_file_number_full: description: Full reference for the original filing in the chain. type: - string - 'null' record_type: description: Source-provided record class. type: - string - 'null' reference_file_number: description: Reference linking this row to the original filing in the chain. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high secured_party_address: description: Address of the secured party. type: - string - 'null' secured_party_name: description: Name of the secured party. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' type: object SearchInputsUsed: properties: address: description: Address sent on this step; null when unused. type: - string - 'null' address_source: description: 'Application address used: company_physical_address or company_billing_address.' enum: - company_physical_address - company_billing_address - null type: - string - 'null' business_name: description: The business name queried on this step; null on person attempts. type: - string - 'null' business_name_source: description: Which name variant was queried; null on person attempts. enum: - legal - dba - candidate_fallback - linked_address_fallback - null type: - string - 'null' corporation_id: description: Corporation identifier sent on this step; null when unused. type: - string - 'null' date_of_birth: description: Date of birth sent on this step; null when unused. format: date type: - string - 'null' email: description: Email sent on this step; null when unused. type: - string - 'null' filing_state: description: Filing state sent on this step; null when unused. type: - string - 'null' fuzzy: description: True when this step allowed fuzzy matching. type: boolean name: description: Person name sent on this step; null when unused. type: - string - 'null' phone: description: Phone number sent on this step; null when unused. type: - string - 'null' ssn: description: Masked SSN sent on this step; null when unused. type: - string - 'null' state: description: State sent on this step; null when unused. type: - string - 'null' required: - fuzzy type: object BackgroundCheckAffiliationsViewSchema: properties: businesses: description: Businesses the owners are affiliated with, from their background check reports. items: $ref: '#/components/schemas/BackgroundCheckAffiliationRow' type: array persons: description: People associated with the owners, from their background check reports. items: $ref: '#/components/schemas/BackgroundCheckAffiliationPersonRow' type: array status: description: Run lifecycle of the underlying background check. Lists reflect the most recent succeeded run; while a newer run is processing or failed they keep the last completed data and pending report requests show as pending. enum: - never_run - processing - succeeded - failed - missing_input_data type: string required: - businesses - persons - status type: object BackgroundCheckAffiliationPersonRow: properties: city_state: description: Reported city and state. type: - string - 'null' date_of_birth: description: Date of birth; null when unavailable. format: date type: - string - 'null' has_entity_id: description: Whether CLEAR identified this associate. When true a report pulls directly; when false a search runs first and may require confirming a candidate. type: boolean index: description: Position in that report's list. type: integer name: description: Name of the associate. type: - string - 'null' relationship: description: Source-provided relationship to the owner. type: - string - 'null' report: allOf: - $ref: '#/components/schemas/BackgroundCheckAffiliationReportState' description: State of the most recent report requested for this associate; null when never requested. subject_key: description: 'The report that names this person: owner_1 or owner_2 for an owner''s associate, or business for an unreported corporate officer.' enum: - owner_1 - owner_2 - business type: string required: - has_entity_id - index - subject_key type: object SearchAttemptOutcomeReasonDetail: properties: label: description: Display label for the outcome detail. type: string value: description: Value paired with the label; null when unavailable. required: - label type: object SearchAttemptOutcomeReason: properties: details: description: Label and value pairs explaining the search outcome. items: $ref: '#/components/schemas/SearchAttemptOutcomeReasonDetail' type: array label: description: Summary of the search outcome. type: string required: - details - label type: object PolicyEvaluationResult: properties: policy_heron_id: description: Heron ID of the policy that was evaluated type: string policy_name: description: Name of the policy that was evaluated type: string result: description: Result of the policy evaluation enum: - passed - failed - review_required - missing_data use_case: description: Use case of the policy; null only for evaluations predating the backfill enum: - background_check - cashflow - null type: object BackgroundCheckCheckCounts: properties: fail: description: Number of failed policy checks. type: integer pass: description: Number of passed policy checks. type: integer review: description: Number of policy checks requiring review. type: integer required: - fail - pass - review type: object CandidateTraceModifier: properties: detail: description: Free-text specifics; display verbatim. type: - string - 'null' effect: description: The strength delta this adjustment contributed. type: number kind: description: 'Adjustment applied: aka_lift, dba_basis, or premises_composite.' enum: - aka_lift - corroboration_admitted - dba_basis - middle_initial_cap - partial_agreement_floor - premises_composite type: string required: - effect - kind type: object DuplicateEndUser: properties: created: description: When the duplicate end user was created example: '2026-08-07T12:24:30.699612' format: date-time type: string end_user_heron_id: description: Heron ID of the duplicate end user example: eus_abc123 type: string name: description: Name of the duplicate end user example: Acme Corp type: - string - 'null' required: - created - end_user_heron_id type: object AffiliateSubject: properties: application: allOf: - $ref: '#/components/schemas/BackgroundCheckApplication' description: Identity searched, taken from the application data. candidates: description: Every deduplicated candidate returned across the subject's searches, with its match score. items: $ref: '#/components/schemas/BackgroundCheckCandidate' type: array case_ref: description: Reserved case reference; null in normal use. type: - string - 'null' decision: allOf: - $ref: '#/components/schemas/BackgroundCheckDecision' description: Audit of how the winning candidate was selected; null when no scoring decision was needed. duns_numbers: description: D&B DUNS numbers of the resolved business. Empty for person subjects. items: type: string type: array key: description: Identifier for an affiliate report, such as affiliate_business_bcs_x7Kp2 - not one of the three fixed subject keys. type: string kind: description: 'Subject type: person or business.' enum: - person - business type: string name: description: 'Label for the subject: the matched record''s filed name for a business, the searched name for a person. Null when neither is known.' type: - string - 'null' related_party_officers: description: Business-filing officers who match a related party on the deal. items: type: string type: array resolution: allOf: - $ref: '#/components/schemas/BackgroundCheckResolution' description: How and whether the subject was matched. role: description: Subject's role on the deal; null when unavailable. type: - string - 'null' searches: description: Search waterfall in attempted order, including each step's inputs and outcome. items: $ref: '#/components/schemas/SearchAttempt' type: array sections: description: Report findings grouped by record type. items: $ref: '#/components/schemas/BackgroundCheckSection' type: array unreported_officers: description: Officers on active business filings who are not listed as owners on the application. Empty for person subjects. items: type: string type: array required: - application - candidates - key - kind - resolution - searches - sections - unreported_officers type: object BackgroundCheckCandidateOverrideSchema: properties: business: description: Selected candidate ID for the business; null when not overridden. type: - string - 'null' owner_1: description: Selected candidate ID for owner_1; null when not overridden. type: - string - 'null' owner_2: description: Selected candidate ID for owner_2; null when not overridden. type: - string - 'null' type: object CandidateScoreContribution: properties: allocation: description: Fraction of the 100-point maximum. type: number application_value: description: The compared application value when it differs from the hoisted application block; null otherwise. type: - string - 'null' candidate_value: description: Candidate value compared for this contribution; null when absent. type: - string - 'null' cause: description: Why an absent verdict has no evidence; null on scoreable rows. enum: - missing_application_value - missing_candidate_value - null type: - string - 'null' field: description: Application field evaluated by this contribution. type: string identifier_source: description: For an identifier-echo corroboration (corp_number_echo), which system supplied the re-searched number; null on other rows. enum: - sos_registry - clear_filing - null type: - string - 'null' kind: description: 'Contribution type: field (a direct comparison), corroboration, penalty, or quality.' enum: - field - corroboration - quality - penalty type: string points: description: This row's contribution to the total, as a fraction. type: number strength: description: Comparator strength in [-1, 1]; null when the field wasn't comparable (fall back to the verdict). type: - number - 'null' trace: allOf: - $ref: '#/components/schemas/CandidateFieldTrace' description: How the strength was derived; null when trivially derived. verdict: description: 'Comparison verdict: agree, fuzzy, diverge, or absent.' enum: - agree - fuzzy - diverge - absent type: string required: - allocation - field - kind - points - verdict type: object CandidateFieldTrace: properties: base: description: Comparator strength before named modifiers are applied. type: number components: description: Per-part evidence used to derive the strength. items: $ref: '#/components/schemas/CandidateTraceComponent' type: array mode: description: 'How the strength was derived: exact, similarity, stepped, or composite.' enum: - exact - similarity - stepped - composite type: string modifiers: description: Named adjustments applied to the base strength. items: $ref: '#/components/schemas/CandidateTraceModifier' type: array required: - base - components - mode - modifiers type: object CorporateFilingHistoryEntrySchema: properties: history_code: description: Code assigned to the filing event by the source. type: - string - 'null' history_desc: description: Source-provided description of the filing event. type: - string - 'null' type: object CriminalChargeEntrySchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: actual_release_date: description: Actual release date from custody; null when unavailable. format: date type: - string - 'null' arrest_date: description: Date of the arrest; null when unavailable. format: date type: - string - 'null' arresting_agency: description: Arresting agency named on the source record; null when unavailable. type: - string - 'null' case_number: description: Court case reference; null when unavailable. type: - string - 'null' case_status: description: The court's live case status, such as DISCHARGE or PENDING. Can resolve a case even when no disposition is recorded; null when unavailable. type: - string - 'null' case_status_date: description: Date of the case status; null when unavailable. format: date type: - string - 'null' categories: description: 'Offence classifications: fraud, violent, dui, drug, burglary, domestic_violence, child_related, sex_offense, murder_homicide, fiduciary, or other.' items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array category: description: Source-provided offence category string. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' crime_date: description: Date the offence occurred, distinct from the case filing date; null when unavailable. format: date type: - string - 'null' disposition: description: Case or charge outcome; null when unavailable. type: - string - 'null' disposition_date: description: Date of the disposition; null when unavailable. format: date type: - string - 'null' filed_date: description: Case filing date; null when unavailable. format: date type: - string - 'null' fine_amount: description: Fine imposed as a decimal string; null when unavailable. type: - number - 'null' grade: description: 'Offence grade: felony, misdemeanor, petty_misdemeanor, infraction, or unknown.' enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown is_dismissed: description: True when the case was dismissed or not prosecuted. type: boolean is_felony: description: True when any charge on the case is a felony. type: boolean number_of_counts: description: Number of counts; null when unavailable. type: - integer - 'null' offense: description: Offence as recorded on the source document. type: - string - 'null' offense_location: description: Where the offence took place; null when unavailable. type: - string - 'null' parole_status: description: Parole status; null when unavailable. type: - string - 'null' plea: description: The plea entered - the changed plea when one exists, else the original; null when unavailable. type: - string - 'null' plea_date: description: Date of the plea; null when unavailable. format: date type: - string - 'null' probation_end_date: description: Probation end date - the actual end when recorded, else the scheduled end; null when unavailable. format: date type: - string - 'null' probation_violation: description: Probation violation as recorded on the source; null when unavailable. type: - string - 'null' projected_release_date: description: Projected release date from custody, falling back to the tentative then maximum release date; null when unavailable. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high sentence: description: Sentence text; null when unavailable. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true severity_text: description: Source-provided severity string. type: - string - 'null' source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' statute_code: description: Statute code; null when unavailable. type: - string - 'null' type: object ProfileAddress: properties: address: description: Reported address. type: - string - 'null' city_state: description: Reported city and state. type: - string - 'null' first_reported_date: description: First reported date; null when unavailable. format: date type: - string - 'null' is_po_box: description: Whether this specific address is classified as a PO Box. type: boolean last_reported_date: description: Last reported date; null when unavailable. format: date type: - string - 'null' source: description: Source that supplied the record. type: - string - 'null' type: object DetailFiling: properties: certificate_number: description: Source-provided certificate number; null when unavailable. type: - string - 'null' court: description: Source-provided court; null when unavailable. type: - string - 'null' court_county: description: Source-provided court county; null when unavailable. type: - string - 'null' expire_date: description: Source-provided expiry date; null when unavailable. type: - string - 'null' file_date: description: Source-provided file date; null when unavailable. type: - string - 'null' file_number_full: description: Source-provided full file number; null when unavailable. type: - string - 'null' file_pages: description: Source-provided file page count; null when unavailable. type: - string - 'null' filing_date: description: Source-provided filing date; null when unavailable. type: - string - 'null' filing_number: description: Source-provided filing number; null when unavailable. type: - string - 'null' filing_office: description: Source-provided filing office; null when unavailable. type: - string - 'null' filing_office_address: description: Source-provided filing office address; null when unavailable. type: - string - 'null' filing_state: description: Source-provided filing state; null when unavailable. type: - string - 'null' filing_type: description: Source-provided filing type; null when unavailable. type: - string - 'null' hidden_filing_number: description: Source-provided hidden filing number; null when unavailable. type: - string - 'null' original_filing_number: description: Source-provided original filing number; null when unavailable. type: - string - 'null' perfected_date: description: Source-provided perfected date; null when unavailable. type: - string - 'null' reference_file_number: description: Source-provided reference file number; null when unavailable. type: - string - 'null' related_file_date: description: Source-provided related file date; null when unavailable. type: - string - 'null' release_date: description: Source-provided release date; null when unavailable. type: - string - 'null' type_of_action: description: Source-provided type of action; null when unavailable. type: - string - 'null' type_of_filing: description: Source-provided type of filing; null when unavailable. type: - string - 'null' type_of_tax: description: Source-provided type of tax; null when unavailable. type: - string - 'null' type: object MarriageRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: ceremony_type: description: Source-provided marriage ceremony type; null for divorce-only rows. type: - string - 'null' county: description: County named on the record. type: - string - 'null' decree_date: description: Divorce decree date; null for marriage-only rows. format: date type: - string - 'null' filing_date: description: Divorce filing date; null for marriage-only rows. format: date type: - string - 'null' is_active: description: True when the linked divorce case appears active. type: boolean is_divorced: description: True when the marriage has a linked divorce record. type: boolean location: description: Location named on the record. type: - string - 'null' marriage_date: description: Marriage date; null for divorce-only rows. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true spouse_name: description: Spouse name; null for divorce-only rows. type: - string - 'null' type: object CrmSyncEventSchema: properties: crm_record_url: type: - string - 'null' error_message: type: - string - 'null' heron_id: type: string name: type: string occurred_at: format: date-time type: string provider: type: - string - 'null' result: enum: - success - failure - no_sync_attempted success_message: type: - string - 'null' type: object DetailCase: properties: case_details: description: Source-provided case details; null when unavailable. type: - string - 'null' case_number: description: Source-provided case number; null when unavailable. type: - string - 'null' case_title: description: Source-provided case title; null when unavailable. type: - string - 'null' category: description: Source-provided case category; null when unavailable. type: - string - 'null' chapter: description: Source-provided bankruptcy chapter; null when unavailable. type: - string - 'null' company_interest: description: Source-provided company interest; null when unavailable. type: - string - 'null' county: description: Source-provided county; null when unavailable. type: - string - 'null' court: description: Source-provided court; null when unavailable. type: - string - 'null' discharge_date: description: Source-provided discharge date; null when unavailable. type: - string - 'null' disposition: description: Source-provided disposition; null when unavailable. type: - string - 'null' disposition_date: description: Source-provided disposition date; null when unavailable. type: - string - 'null' division: description: Source-provided court division; null when unavailable. type: - string - 'null' docket_number: description: Source-provided docket number; null when unavailable. type: - string - 'null' document_id: description: Source-provided document reference; null when unavailable. type: - string - 'null' filed_date: description: Source-provided filed date; null when unavailable. type: - string - 'null' filing_office: description: Source-provided filing office; null when unavailable. type: - string - 'null' filing_state: description: Source-provided filing state; null when unavailable. type: - string - 'null' final_decree_date: description: Source-provided final decree date; null when unavailable. type: - string - 'null' judge: description: Source-provided judge; null when unavailable. type: - string - 'null' jury_demand: description: Source-provided jury demand; null when unavailable. type: - string - 'null' jury_demand_amount: description: Source-provided jury demand amount; null when unavailable. type: - string - 'null' nature_of_suit: description: Source-provided nature of suit; null when unavailable. type: - string - 'null' nature_of_suit_code: description: Source-provided nature of suit code; null when unavailable. type: - string - 'null' state: description: Source-provided state; null when unavailable. type: - string - 'null' status: description: Source-provided case status; null when unavailable. type: - string - 'null' sub_category: description: Source-provided case subcategory; null when unavailable. type: - string - 'null' type: object CandidateCapTrace: properties: cap: description: The cap the total was clamped to, as a fraction. type: number conflict: description: Conflicting field that caused the score cap. enum: - zero_floor type: string uncapped_total: description: The uncapped total, as a fraction. type: number required: - cap - conflict - uncapped_total type: object DetailCharge: properties: additional_fields: description: Unmapped source values as label and value pairs. items: $ref: '#/components/schemas/DetailLabelValue' type: array amended_offense: description: Source-provided amended offence; null when unavailable. type: - string - 'null' amended_statute: description: Source-provided amended statute; null when unavailable. type: - string - 'null' case_comments: description: Source-provided case comments; null when unavailable. type: - string - 'null' case_information: description: Source-provided case information; null when unavailable. type: - string - 'null' case_number: description: Source-provided case number; null when unavailable. type: - string - 'null' case_status: description: Source-provided case status; null when unavailable. type: - string - 'null' category: description: Source-provided charge category; null when unavailable. type: - string - 'null' citation_number: description: Source-provided citation number; null when unavailable. type: - string - 'null' class_of_offense: description: Source-provided class of offence; null when unavailable. type: - string - 'null' counts: description: Source-provided counts; null when unavailable. type: - string - 'null' court_charge: description: Source-provided court charge; null when unavailable. type: - string - 'null' court_county: description: Source-provided court county; null when unavailable. type: - string - 'null' court_name: description: Source-provided court name; null when unavailable. type: - string - 'null' crime_date: description: Source-provided crime date; null when unavailable. type: - string - 'null' disposition: description: Source-provided disposition; null when unavailable. type: - string - 'null' disposition_date: description: Source-provided disposition date; null when unavailable. type: - string - 'null' duplicate_report: description: True when the charge duplicates another reported entry. type: boolean facts: description: 'Arrest entries only: this entry''s own key facts as label and value pairs, ahead of the unmapped source values.' items: $ref: '#/components/schemas/DetailLabelValue' type: array fee_amount: description: Source-provided fee amount; null when unavailable. type: - string - 'null' filed_date: description: Source-provided filed date; null when unavailable. type: - string - 'null' fined_amount: description: Source-provided fined amount; null when unavailable. type: - string - 'null' max_sentence_months: description: Source-provided maximum sentence months; null when unavailable. type: - string - 'null' offense: description: Source-provided offence; null when unavailable. type: - string - 'null' offense_code: description: Source-provided offence code; null when unavailable. type: - string - 'null' offense_date: description: Source-provided offence date; null when unavailable. type: - string - 'null' offense_notes: description: Source-provided offence notes; null when unavailable. type: - string - 'null' plea: description: Source-provided plea; null when unavailable. type: - string - 'null' probation_months: description: Source-provided probation months; null when unavailable. type: - string - 'null' sentence: description: Source-provided sentence; null when unavailable. type: - string - 'null' sequence: description: Source-provided charge sequence; null when unavailable. type: - string - 'null' severity: description: Source-provided charge severity; null when unavailable. type: - string - 'null' source_entry_id: description: Source-provided source entry reference; null when unavailable. type: - string - 'null' statute: description: Source-provided statute; null when unavailable. type: - string - 'null' warrant_date: description: Source-provided warrant date; null when unavailable. type: - string - 'null' type: object EndUser: properties: confidence: description: Aggregated confidence for the end user across all transactions; between 0 and 1 example: 0.42 readOnly: true type: number created: description: When the end user was created in Heron system example: '2026-07-03T12:24:30.665078' format: date-time readOnly: true type: string criteria: description: List of scorecard metrics items: $ref: '#/components/schemas/Metric' readOnly: true type: array data_sources: description: List of data source summaries for the end user items: $ref: '#/components/schemas/DataSource' readOnly: true type: array end_user_id: description: id defined by user; links to the end_user_id for transactions example: 6a1d7831-8953-4f9f-a544-423cd8f48eb6 maxLength: 140 minLength: 1 type: string heron_id: description: Unique id for end user generated by Heron example: eus_5yWkT2NZzCevkyPwbGhn2Z readOnly: true type: string is_portfolio: description: Whether the end user is part of a lending portfolio example: true type: boolean last_processed_at: description: When the end user was last successfully processed in Heron system example: '2026-08-14T12:24:30.678624' format: date-time readOnly: true type: string last_updated: description: When the end user was last updated in Heron system example: '2026-08-14T12:24:30.665119' format: date-time readOnly: true type: string meta: additionalProperties: type: string description: 'Arbitrary key-value metadata. Max 20 keys, key ≤64 chars, value ≤256 chars, total ≤4KB. Example: {"attribution_key": "lender_42"}' type: - object - 'null' name: description: Name of end user; may help to improve categorisation accuracy example: Company Name Inc. maxLength: 128 type: - string - 'null' profit_and_loss_layout: {} status: description: Status of end user; 'ready' triggers async processing, 'review_requested' triggers manual review request enum: - new - ready - processed - reviewed - review_requested - failed example: ready type: string tags: description: Tags currently applied to this end user, read-only. Absent unless the endpoint returns them. items: $ref: '#/components/schemas/TagSchema' readOnly: true type: array required: - end_user_id type: object BackgroundCheckOverride: properties: at: description: When the reviewer applied the override. format: date-time type: string by: description: Reviewer who applied the override. type: string status: description: Reviewer-selected outcome replacing the automated result. enum: - pass - failed - review_required - missing_data required: - at - by - status type: object CandidateAnchorTrace: properties: anchor: description: 'Identifier that resolved the match outright: ein or corp_number_echo.' enum: - ein - corp_number_echo type: string guard_field: description: Candidate field used to guard the anchor match; null when no guard was needed. enum: - business_name - address - owner - null type: - string - 'null' guard_strength: description: Guard field's comparison strength; null when no guard was evaluated. type: - number - 'null' permitted: description: False records an anchor-grade identifier the guard denied. type: boolean required: - anchor - permitted type: object BackgroundCheckRawReportSchema: properties: file_b64: description: Base64-encoded raw report bytes type: string filename: description: Suggested download filename type: string mime_type: description: MIME type of the raw report type: string required: - file_b64 - filename - mime_type type: object DataSource: properties: status: description: Status of the data source entity, where applicable (e.g. pdfs, integration links) enum: - new - parsing - parsed - processed - human_reviewing - approved - rejected - failed - transactions_loaded - transactions_unloaded - pending - active - syncing - erroring - sync_disabled - deleted_in_plaid - unknown example: new type: string type: description: Data source type enum: - api - csv - pdf - integration_link - legacy - legacy_pdf - legacy_integration_link example: pdf type: string required: - type type: object EndUserAddressLocationSchema: properties: company_physical_address: allOf: - $ref: '#/components/schemas/AddressLocation' type: object DetailAttorney: properties: address: description: Source-provided address; null when unavailable. type: - string - 'null' bar_number: description: Source-provided bar number; null when unavailable. type: - string - 'null' email: description: Source-provided email address; null when unavailable. type: - string - 'null' firm: description: Source-provided firm; null when unavailable. type: - string - 'null' name: description: Source-provided attorney name; null when unavailable. type: - string - 'null' phone: description: Source-provided phone number; null when unavailable. type: - string - 'null' role: description: Source-provided role; null when unavailable. type: - string - 'null' status: description: Source-provided status; null when unavailable. type: - string - 'null' type: object BankruptcyRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: chapter: description: Bankruptcy chapter number; null when unavailable. type: - integer - 'null' chapter_kind: description: 'Bankruptcy chapter classification: chapter_7, chapter_11, chapter_12, chapter_13, other, or unknown.' enum: - chapter_7 - chapter_11 - chapter_12 - chapter_13 - other - unknown debtor_name: description: Debtor named on the filing. type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request document_id: description: Source document reference; null when unavailable. type: - string - 'null' filed_date: description: Case filing date; null when unavailable. format: date type: - string - 'null' is_open: description: True when status_kind is neither discharged nor dismissed. type: boolean risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true status: description: Bankruptcy status value matching status_kind. type: - string - 'null' status_kind: description: 'Bankruptcy status classification: filed, discharged, dismissed, or unknown. Discharged and dismissed are closed; filed and unknown are open.' enum: - filed - discharged - dismissed - unknown total_assets: description: Total scheduled assets as a decimal string; null when the filing does not record them. type: - number - 'null' total_liabilities: description: Total scheduled liabilities as a decimal string; null when the filing does not record them. type: - number - 'null' type: object ProfileEmail: properties: email: description: Email address. type: - string - 'null' source: description: Source that supplied the record. type: - string - 'null' type: object CriminalRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: actual_release_date: description: Actual release date from custody; null when unavailable. format: date type: - string - 'null' arrest_date: description: Date of the arrest; null when unavailable. format: date type: - string - 'null' arresting_agency: description: Arresting agency named on the source record; null when unavailable. type: - string - 'null' case_number: description: Court case reference; null when unavailable. type: - string - 'null' case_status: description: The court's live case status, such as DISCHARGE or PENDING. Can resolve a case even when no disposition is recorded; null when unavailable. type: - string - 'null' case_status_date: description: Date of the case status; null when unavailable. format: date type: - string - 'null' categories: description: 'Offence classifications: fraud, violent, dui, drug, burglary, domestic_violence, child_related, sex_offense, murder_homicide, fiduciary, or other.' items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array category: description: Source-provided offence category string. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' crime_date: description: Date the offence occurred, distinct from the case filing date; null when unavailable. format: date type: - string - 'null' detail: allOf: - $ref: '#/components/schemas/BackgroundCheckRecordDetail' description: Only populated when include_section_detail=true is passed on the request disposition: description: Case or charge outcome; null when unavailable. type: - string - 'null' disposition_date: description: Date of the disposition; null when unavailable. format: date type: - string - 'null' entry_count: description: Number of underlying source entries combined into this record. type: integer filed_date: description: Case filing date; null when unavailable. format: date type: - string - 'null' fine_amount: description: Fine imposed as a decimal string; null when unavailable. type: - number - 'null' grade: description: 'Offence grade: felony, misdemeanor, petty_misdemeanor, infraction, or unknown.' enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown is_dismissed: description: True when the case was dismissed or not prosecuted. type: boolean is_felony: description: True when any charge on the case is a felony. type: boolean is_unclassified: description: True when the offence could not be classified. type: boolean number_of_counts: description: Number of counts; null when unavailable. type: - integer - 'null' offense: description: Offence as recorded on the source document. type: - string - 'null' offense_location: description: Where the offence took place; null when unavailable. type: - string - 'null' parole_status: description: Parole status; null when unavailable. type: - string - 'null' plea: description: The plea entered - the changed plea when one exists, else the original; null when unavailable. type: - string - 'null' plea_date: description: Date of the plea; null when unavailable. format: date type: - string - 'null' probation_end_date: description: Probation end date - the actual end when recorded, else the scheduled end; null when unavailable. format: date type: - string - 'null' probation_violation: description: Probation violation as recorded on the source; null when unavailable. type: - string - 'null' projected_release_date: description: Projected release date from custody, falling back to the tentative then maximum release date; null when unavailable. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high sentence: description: Sentence text; null when unavailable. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true severity_text: description: Source-provided severity string. type: - string - 'null' shared_case_key: description: Stable key for a record that appears on both owner and business reports; null when not shared. type: - string - 'null' shared_relationship: description: 'Where the shared record also appears: also_on_business or also_on_owner; null when not shared.' enum: - also_on_owner - also_on_business - null type: - string - 'null' source_entries: description: Underlying source rows combined into this record. items: $ref: '#/components/schemas/CriminalChargeEntrySchema' type: array source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' source_entry_ids: description: References for the underlying source rows combined into this record. items: type: string type: array statute_code: description: Statute code; null when unavailable. type: - string - 'null' type: object Owner: properties: credit_score: type: - integer - 'null' date_of_birth: example: '1990-01-01' format: date type: - string - 'null' email_address: type: - string - 'null' first_name: type: - string - 'null' has_signed: type: - boolean - 'null' home_address: $ref: '#/components/schemas/Address' home_phone: type: - string - 'null' last_name: type: - string - 'null' middle_name: type: - string - 'null' mobile_phone: type: - string - 'null' ownership_percentage: description: Percentage of ownership example: 100 type: - number - 'null' prefix: description: Name prefix example: Mr type: - string - 'null' signed_date: format: date type: - string - 'null' social_security_number: type: - string - 'null' suffix: description: Generational or professional suffix example: Jr type: - string - 'null' type: object WorkAffiliation: properties: address: description: Address of the business; null when unavailable. type: - string - 'null' business_name: description: Business the subject is affiliated with. type: - string - 'null' role: description: Role at the business, such as CEO, DIRECTOR, or Registered Agent. type: - string - 'null' since_date: description: Date the affiliation began; null when unavailable. format: date type: - string - 'null' status: description: Source-provided status of the affiliation. type: - string - 'null' type: object Address: properties: city: type: - string - 'null' line_1: type: - string - 'null' line_2: type: - string - 'null' state: type: - string - 'null' zip: type: - string - 'null' type: object BackgroundCheckAffiliationRow: properties: address: description: Address of the business; null when unavailable. type: - string - 'null' address_state: description: State of the business address; null when unavailable. type: - string - 'null' business_name: description: Business the owner is affiliated with. type: - string - 'null' index: description: Position in that report's list; echo it when requesting a report. type: integer legal_business_name: description: Legal name of the business as filed; null when unavailable. type: - string - 'null' organization_type: description: Source-provided organisation type, such as CORPORATION; null when unavailable. type: - string - 'null' report: allOf: - $ref: '#/components/schemas/BackgroundCheckAffiliationReportState' description: State of the most recent report requested for this affiliation; null when never requested. role: description: Role at the business, such as CEO, DIRECTOR, or Registered Agent. type: - string - 'null' roles: description: All roles the owner holds at the business, such as Officer or Registered Agent. items: type: string type: array since_date: description: Date the affiliation began; null when unavailable. format: date type: - string - 'null' status: description: Source-provided status of the affiliation. type: - string - 'null' subject_key: description: 'The report that names this business: owner_1 or owner_2 for an owner''s affiliation, or business for a company named as an officer on the business''s own filings.' enum: - owner_1 - owner_2 - business type: string year_established: description: Year the business was established as recorded on the source; null when unavailable. type: - string - 'null' required: - index - subject_key type: object BackgroundCheckDecision: properties: anchored_by: description: 'Anchor identifier that resolved the match outright: ein or corp_number_echo; null when unanchored.' type: - string - 'null' near_tie: allOf: - $ref: '#/components/schemas/BackgroundCheckNearTie' description: Top-two score comparison; null when the candidates were not close. pooled_count: description: Number of candidates pooled and scored. type: - integer - 'null' tie_break: description: How the winner separated from the runner-up; null when there was no winner/runner-up. enum: - score - key_order - flag_probe - null type: - string - 'null' type: object AssociateRecordSchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: age: description: Reported age of the associate. type: - integer - 'null' association_description: description: Source description of the association, such as Shared Address. type: - string - 'null' city_state: description: Reported city and state. type: - string - 'null' date_of_birth: description: Date of birth; null when unavailable. format: date type: - string - 'null' death_date: description: Reported date of death; null when unavailable. format: date type: - string - 'null' entity_id: description: Source entity identifier; null when unavailable. type: - string - 'null' first_reported_date: description: First reported date; null when unavailable. format: date type: - string - 'null' is_deceased: description: True when the associate is reported deceased. type: boolean is_high_risk: description: True when the associate is marked high risk. type: boolean last_reported_date: description: Last reported date; null when unavailable. format: date type: - string - 'null' name: description: Name of the associate. type: - string - 'null' relationship: description: Source-provided relationship to the subject. type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high severity: description: Record severity tier, mirroring risk. readOnly: true shares_address: description: True when the associate shares an address with the subject. type: boolean shares_phone: description: True when the associate shares a phone number with the subject. type: boolean strength_of_association: description: Source strength score for the association; null when unavailable. type: - integer - 'null' type: object DetailSource: properties: publication_date: description: Source-provided publication date; null when unavailable. type: - string - 'null' source_document_guid: description: Source-provided source document reference; null when unavailable. type: - string - 'null' source_name: description: Source-provided source name; null when unavailable. type: - string - 'null' source_state: description: Source-provided source state; null when unavailable. type: - string - 'null' type: object Metric: properties: context: description: Context for how to interpret the metric, e.g., whether a higher value is 'better' than a lower value enum: - higher_is_better - lower_is_better - null example: higher_is_better type: - string - 'null' currency: description: The ISO currency code for metric, where applicable type: - string - 'null' date_range: description: Metric date range enum: - latest - last_30_days - last_90_days - last_120_days - last_180_days - last_365_days - next_30_days - next_60_days - next_90_days - next_180_days - last_1_calendar_months - last_3_calendar_months - last_4_calendar_months - last_6_calendar_months - last_12_calendar_months - last_15_calendar_months - last_24_calendar_months - last_1_full_calendar_months - last_2_full_calendar_months - last_3_full_calendar_months - last_6_full_calendar_months - last_12_full_calendar_months - last_60_days - last_45_days - last_2_calendar_months example: last_180_days type: string description: description: Description of metric example: The number of unique transactions with a timestamp type: - string - 'null' group: description: The type of metric enum: - data_quality - processing_quality - balance - profit_and_loss - debt - risk_flag - forecast - heron - ml_feature example: data_quality type: string label: description: Metric label, slugified example: unique_transactions type: string status: description: either 'calculated' or 'not_available' depending on the requested date range vs. date range of the data enum: - available - partially_available - not_available - null example: not_available type: - string - 'null' unit: description: The unit of measurement for metric enum: - n - day - ratio - amount - weekday - array - probability example: n type: string value: description: The metric value example: 42.42 type: object CriminalSectionEntrySchema: description: A background-check finding. Risk and severity carry the same none, low, medium, or high tier. properties: actual_release_date: description: Actual release date from custody; null when unavailable. format: date type: - string - 'null' arrest_date: description: Date of the arrest; null when unavailable. format: date type: - string - 'null' arresting_agency: description: Arresting agency named on the source record; null when unavailable. type: - string - 'null' bail_amount: description: Bail amount on this entry as a decimal string; null when unavailable. type: - number - 'null' booking_number: description: Booking reference on this entry; null when unavailable. type: - string - 'null' case_number: description: Court case reference; null when unavailable. type: - string - 'null' case_status: description: The court's live case status, such as DISCHARGE or PENDING. Can resolve a case even when no disposition is recorded; null when unavailable. type: - string - 'null' case_status_date: description: Date of the case status; null when unavailable. format: date type: - string - 'null' categories: description: 'Offence classifications: fraud, violent, dui, drug, burglary, domestic_violence, child_related, sex_offense, murder_homicide, fiduciary, or other.' items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array category: description: Source-provided offence category string. type: - string - 'null' court_county: description: County of the court; null when unavailable. type: - string - 'null' court_name: description: Court name; null when unavailable. type: - string - 'null' crime_date: description: Date the offence occurred, distinct from the case filing date; null when unavailable. format: date type: - string - 'null' disposition: description: Case or charge outcome; null when unavailable. type: - string - 'null' disposition_date: description: Date of the disposition; null when unavailable. format: date type: - string - 'null' filed_date: description: Case filing date; null when unavailable. format: date type: - string - 'null' fine_amount: description: Fine imposed as a decimal string; null when unavailable. type: - number - 'null' grade: description: 'Offence grade: felony, misdemeanor, petty_misdemeanor, infraction, or unknown.' enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown is_dismissed: description: True when the case was dismissed or not prosecuted. type: boolean is_felony: description: True when any charge on the case is a felony. type: boolean mugshot_record_id: description: Stable identifier used to request this entry's mug shot; null when it has none. type: - string - 'null' number_of_counts: description: Number of counts; null when unavailable. type: - integer - 'null' offense: description: Offence as recorded on the source document. type: - string - 'null' offense_location: description: Where the offence took place; null when unavailable. type: - string - 'null' parole_status: description: Parole status; null when unavailable. type: - string - 'null' plea: description: The plea entered - the changed plea when one exists, else the original; null when unavailable. type: - string - 'null' plea_date: description: Date of the plea; null when unavailable. format: date type: - string - 'null' probation_end_date: description: Probation end date - the actual end when recorded, else the scheduled end; null when unavailable. format: date type: - string - 'null' probation_violation: description: Probation violation as recorded on the source; null when unavailable. type: - string - 'null' projected_release_date: description: Projected release date from custody, falling back to the tentative then maximum release date; null when unavailable. format: date type: - string - 'null' risk: description: Record risk tier. enum: - none - low - medium - high sentence: description: Sentence text; null when unavailable. type: - string - 'null' severity: description: Record severity tier, mirroring risk. readOnly: true severity_text: description: Source-provided severity string. type: - string - 'null' source_entry_id: description: Stable reference for the underlying source row; null when unavailable. type: - string - 'null' state: description: State this entry was reported in; null when unavailable. type: - string - 'null' statute_code: description: Statute code; null when unavailable. type: - string - 'null' type: object CandidateTraceComponent: properties: part: description: Compared part of a compound field, such as street, city, zip, or name similarity. enum: - name_similarity - full_name_similarity - house - street - city - state - zip - zip5 - zip4 type: string value: description: Bool for exact part matches, a 0-1 float for fuzzy ones; null when uncompared. required: - part type: object BackgroundCheckAffiliationsBlock: properties: business: description: Reports requested for affiliated businesses, in request order. items: $ref: '#/components/schemas/BackgroundCheckAffiliateReport' type: array person: description: Reports requested for affiliated people, in request order. items: $ref: '#/components/schemas/BackgroundCheckAffiliateReport' type: array required: - business - person type: object BackgroundCheckPolicy: properties: checks: description: One entry per configured policy check. items: $ref: '#/components/schemas/BackgroundCheckCheck' type: array result: description: 'Worst configured policy outcome: passed, review_required, failed, or missing_data.' enum: - passed - failed - review_required - missing_data required: - checks - result type: object BackgroundCheckAffiliationReportState: properties: kind: description: Whether the report is for an affiliated business or person. enum: - person - business type: string ref: description: Stable reference for this affiliate report request; echo it when confirming a candidate or removing the request. type: string status: description: 'Report lifecycle: pending until the next screening run pulls it, succeeded when the report is ready, not_found when no confident match was found (a candidate can be confirmed), or failed.' enum: - pending - succeeded - not_found - failed type: string required: - kind - ref - status type: object BackgroundCheckApplication: description: The application identity used for the search. All fields are nullable; SSNs remain masked. properties: address: description: Application address used to search this subject; null when unavailable. type: - string - 'null' business_name: description: Application business name; null for person subjects. type: - string - 'null' date_of_birth: description: Date of birth; null when unavailable. format: date type: - string - 'null' ein: description: Employer Identification Number used for the search; null when unavailable. type: - string - 'null' email: description: Email address; null when unavailable. type: - string - 'null' name: description: Application person name; null for business subjects. type: - string - 'null' owner: description: Named owner used when searching a business subject; null for person subjects. type: - string - 'null' phone: description: Phone number; null when unavailable. type: - string - 'null' ssn: description: Masked SSN. Only the first five digits are ever held or returned; the full SSN never appears. type: - string - 'null' state: description: Application state; null when unavailable. type: - string - 'null' type: object DetailParty: properties: address: description: Source-provided address; null when unavailable. type: - string - 'null' akas: description: Also-known-as names on the party. items: type: string type: array attorneys: description: Attorneys the source ties to this party. items: $ref: '#/components/schemas/DetailAttorney' type: array name: description: Source-provided party name; null when unavailable. type: - string - 'null' phone: description: Source-provided phone number; null when unavailable. type: - string - 'null' reported_date: description: Source-provided reported date; null when unavailable. type: - string - 'null' role: description: Source-provided role; null when unavailable. type: - string - 'null' sex: description: Source-provided sex; null when unavailable. type: - string - 'null' status: description: Source-provided status; null when unavailable. type: - string - 'null' type: object securitySchemes: ApiKeyAuth: in: header name: x-api-key type: apiKey externalDocs: description: Read Tutorial url: https://docs.herondata.io/