Heron End Users API

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:
    

# --- truncated at 32 KB (207 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/heron/refs/heads/main/openapi/heron-endusers-api-openapi.yml