---
title: "Fetch an Onboarding Form"
method: GET
path: "/onboarding_forms/{onboarding_form_id}"
tags: ["Onboarding Forms"]
---

# Fetch an Onboarding Form

`GET /onboarding_forms/{onboarding_form_id}`

Retrieve the details of an existing `Onboarding Form`.

## Headers

- `Finix-Version` string

## Response `200`

A single `Onboarding Form`

- OnboardingForm
  - `id` string — The ID of the resource.
  - `onboarding_data` OnboardingData — The prefilled information of the user that's being onboarded. For more information, see [Prefilling Fields](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/#prefilling-fields).
    - `additional_underwriting_data` object — Additional underwriting data about the user.
      - `annual_ach_volume` integer — The approximate annual ACH sales expected to be processed (in cents) by this merchant (max 10 characters).
      - `average_ach_transfer_amount` integer — The approximate average ACH sale amount (in cents) for this merchant.
      - `average_card_transfer_amount` integer — The average credit card sale amount (in cents) for this merchant.
      - `business_description` string — Description of this merchant's business (max 200 characters).
      - `card_volume_distribution` object, nullable — The distribution of the merchant's credit card volume The sum of `card_volume_distribution` must be 100.
        - `card_present_percentage` integer — The percentage of the merchant's volume that's card present (between 0 and 100).
        - `ecommerce_percentage` integer — The percentage of the merchant's business that is eCommerce (between 0 and 100).
        - `mail_order_telephone_order_percentage` integer — The percentage of the merchant's business that is a mail or telephone order (between 0 and 100).
      - `credit_check_timestamp` string — A timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z).
      - `credit_check_user_agent` string — The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
      - `merchant_agreement_accepted` boolean — Sets whether this merchant has accepted the terms and conditions of the merchant agreement.
      - `merchant_agreement_ip_address` string — IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).
      - `merchant_agreement_timestamp` string — Timestamp of when the merchant accepted Finix's Terms of Service (e.g., 2021-04-28T16:42:55Z).
      - `merchant_agreement_user_agent` string — The details of the browser that was used when this merchant accepted Finix's Terms of Service (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
      - `refund_policy` 'NO_REFUNDS' | 'MERCHANDISE_EXCHANGE_ONLY' | 'WITHIN_30_DAYS' | 'OTHER' — Include the value that best applies to the merchant's refund policy.
      - `volume_distribution_by_business_type` object, nullable — Merchant's distribution of credit card volume by business type. Sum of `volume_distribution_by_business_type` must be 100.
        - `business_to_business_volume_percentage` integer — The percentage of the merchant's volume that's business to business (between 0 and 100).
        - `business_to_consumer_volume_percentage` integer — The percentage of the merchant's volume that's business to consumer (between 0 and 100).
        - `consumer_to_consumer_volume_percentage` integer — Merchant's percentage of volume that is consumer to consumer (between 0 and 100).
        - `other_volume_percentage` integer — The percentage of the merchant's volume that isn't represented by the previous fields (between 0 and 100).
        - `person_to_person_volume_percentage` integer — The percentage the merchant's volume that's person to person (between 0 and 100).
      - `amex_marketing_consent` object, nullable — Details about the merchant's consent to receive American Express marketing communications.
        - `accepted` boolean — Whether the merchant accepted Amex marketing consent.
        - `ip_address` string — IP address of the merchant when they provided their marketing consent decision.
        - `user_agent` string — The browser user agent details when the merchant provided their marketing consent decision.
        - `timestamp` string — Timestamp of when the merchant provided their marketing consent decision (ISO 8601 format).
    - `associated_entities` object[] — The `entities` saved in the `associated_identities` of the user. For more information, see [Create an Associated Identity](#operation/createAssociatedIdentity).
      - `annual_card_volume` integer — The annual credit card sales (in cents) expected to be processed (max 19 characters).
      - `business_address` object, nullable — The primary address for the legal entity.
        - `city` string — City (max 20 characters).
        - `country` string
        - `line2` string — Second line of the address (max 35 characters).
        - `line1` string — First line of the address (max 35 characters).
        - `postal_code` string — Zip or Postal code (max 7 characters).
        - `region` string — 2-letter state code.
      - `business_name` string, nullable — Abbreviated names of the business. If there are no abbreviated name, leave this field blank.
      - `business_phone` string — Customer service phone number where the merchant can be reached (max 10 characters).
      - `business_tax_id` string — Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN). If the `business_type` is **INDIVIDUAL\_SOLE\_PROPRIETORSHIP** and they do not have an EIN, use the sole proprietor's Social Security Number (SSN).
      - `business_type` 'INDIVIDUAL_SOLE_PROPRIETORSHIP' | 'CORPORATION' | 'LIMITED_LIABILITY_COMPANY' | 'PARTNERSHIP' | 'ASSOCIATION_ESTATE_TRUST' | 'TAX_EXEMPT_ORGANIZATION' | 'GOVERNMENT_AGENCY' — Include the value that best applies to the merchant.
      - `default_statement_descriptor` string, nullable — The description of the `Merchant` that appears on the buyer's bank or card statement.
      - `dob` object — The control owner's date of birth.
        - `day` integer
        - `month` integer
        - `year` integer
      - `doing_business_as` string — Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
      - `email` string — The email address of the principal control owner where they can be reached (max 100 characters).
      - `first_name` string — The legal first name of the control owner (max 20 characters).
      - `has_accepted_credit_cards_previously` boolean — Defaults to **false** if not passed.
      - `incorporation_date` object, nullable — The date the company was founded and registered.
        - `day` integer — Day business was incorporated (between 1 and 31).
        - `month` integer — Month business was incorporated (between 1 and 12).
        - `year` integer — Year business was incorporated (4-digit).
      - `last_name` string — The `Identity` owner's legal last name.
      - `max_transaction_amount` integer — The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).
      - `mcc` string — The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/guides/managing-operations/security-compliance/approved-merchant-category-codes)
      - `ownership_type` string, nullable — Values can be either: - `PUBLIC` to indicate a publicly-traded company. - `PRIVATE` for privately-held businesses.
      - `personal_address` object — The home address of the principal control owner. This field is used for identity verification purposes.
        - `city` string — City (max 20 characters).
        - `country` string — 3-Letter country code (e.g. USA).
        - `line1` string — First line of the address (max 35 characters).
        - `line2` string — Second line of the address (max 35 characters).
        - `postal_code` string — Zip or Postal code (max 7 characters).
        - `region` string — 2-letter State code.
      - `phone` string — The principal control owner's phone number (max 10 characters).
      - `principal_percentage_ownership` integer — Percentage of the company owned by the principal control owner (min 0; max 100).
      - `tax_id` string — Details if the `tax_id` was provided.
      - `title` string — The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).
      - `url` string — The URL of the `Identity` owner's public website.
    - `country` 'USA' | 'CAN' — Country of the Merchant's business
    - `entity` object — The `entity` information saved in the `Identity` of the user.
      - `amex_mid` integer, nullable — Assigned amexMid value. If a value is passed, it must be 10 or 11 digits.
      - `annual_card_volume` integer, nullable — The annual credit card sales (in cents) expected to be processed by this seller (max 19 characters).
      - `business_address` object, nullable — The primary address for the legal entity.
        - `line1` string, nullable — First line of the address (max 35 characters).
        - `line2` string, nullable — Second line of the address (max 35 characters).
        - `city` string, nullable — City (max 20 characters).
        - `region` string, nullable — 2-letter state code.
        - `postal_code` string, nullable — Zip or Postal code (max 7 characters).
        - `country` string, nullable — 3-Letter Country code (e.g. USA).
      - `business_name` string, nullable — The merchant's legal business name (max 120 characters).<ul><li>If <code>INDIVIDUAL_SOLE_PROPRIETORSHIP</code>, pass the owner's legal first name, last name, and middle initial.</li></ul>
      - `business_phone` string, nullable — Customer service phone number where the seller can be reached (max 10 characters).
      - `business_tax_id_provided` boolean — Details if the `business_tax_id` was provided.
      - `business_type` 'INDIVIDUAL_SOLE_PROPRIETORSHIP' | 'CORPORATION' | 'LIMITED_LIABILITY_COMPANY' | 'PARTNERSHIP' | 'LIMITED_PARTNERSHIP' | 'GENERAL_PARTNERSHIP' | 'ASSOCIATION_ESTATE_TRUST' | 'TAX_EXEMPT_ORGANIZATION' | 'GOVERNMENT_AGENCY', nullable — Include the value that best applies to the seller.
      - `default_statement_descriptor` string, nullable — The description of the `Merchant` that appears on the buyer's bank or card statement.
      - `discover_mid` integer, nullable — Assigned discoverMid value.
      - `dob` object, nullable — The control owner's date of birth.
        - `day` integer — Day of birth (between 1 and 31).
        - `month` integer — Month of birth (between 1 and 12).
        - `year` integer — Year of birth (4-digit). Year must be greater than 1900.
      - `doing_business_as` string, nullable — Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
      - `email` string, nullable — The email address of the principal control owner where they can be reached (max 100 characters).
      - `first_name` string, nullable — The legal first name of the merchant's control owner (max 20 characters).
      - `has_accepted_credit_cards_previously` boolean — Defaults to **false** if not passed.
      - `incorporation_date` object, nullable — The date the company was founded and registered with the US.
        - `day` integer — Day business was incorporated (between 1 and 31).
        - `month` integer — Month of birth (between 1 and 12).
        - `year` integer — Year business was incorporated (4-digit).
      - `last_name` string, nullable — The legal last name of the merchant's control owner (max 20 characters).
      - `mcc` string, nullable — The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/guides/managing-operations/security-compliance/approved-merchant-category-codes)
      - `ownership_type` 'PUBLIC' | 'PRIVATE', nullable — Values can be either: <ul><li><strong>PUBLIC</strong> to indicate a publicly-traded company.</li><li><strong>PRIVATE</strong> for privately-held businesses.</li></ul>
      - `personal_address` object, nullable — The home address of the merchant's principal control owner. This field is used for identity verification purposes.
        - `line1` string, nullable — First line of the address (max 35 characters).
        - `line2` string, nullable — Second line of the address (max 35 characters).
        - `city` string, nullable — City (max 20 characters).
        - `region` string, nullable — 2-letter State code.
        - `postal_code` string, nullable — Zip or Postal code (max 7 characters).
        - `country` string, nullable — 3-Letter country code (e.g. USA).
      - `phone` string, nullable — The principal control owner's phone number (max 10 characters).
      - `principal_percentage_ownership` integer, nullable — Percentage of the company owned by the principal control owner (min 0; max 100).
      - `short_business_name` string, nullable — Abbreviated names of the business. If there are no abbreviated name, leave this field blank.
      - `tax_authority` string, nullable — <ul><li>Only required when onboarding a seller with a <code>MCC</code> of <code>9311</code>.</li><li>The <code>tax_authority</code> is the tax gathering entity (e.g., San Francisco Water Authority).</li></ul>
      - `tax_id` string, nullable — The control owner's Social Security Number (SSN). Masked in responses (e.g., `*****3333`).
      - `tax_id_provided` boolean — Details if the `tax_id` was provided.
      - `business_tax_id` string, nullable — Nine digit Tax Identification Number (TIN) or Employer Identification Number (EIN). Masked in responses (e.g., `*****2222`).
      - `title` string, nullable — The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).
      - `url` string, nullable — The URL of the merchant's public website.
    - `payment_instruments` object — The `Payment Instrument` that'll be used to payout the seller. For more information, see [Payouts](/guides/payouts/).
      - `account_number` string — The bank account number (no dashes in between numbers). Canadian bank account numbers cannot exceed 15 characters.
      - `account_type` string — The type of bank account. Use the following respective enum when creating a `Payment Instrument` for:<ul><li><strong>CHECKING: </strong>The checking account of your buyer.</li><li><strong>SAVINGS: </strong>The savings account of your buyer.</li><li><strong>CORPORATE: </strong>A corporate checking account.</li><li><strong>CORP_SAVINGS: </strong>A corporate savings account.</li><li><strong>BUSINESS_CHECKING: </strong>A checking account primarily owned by a business.</li><li><strong>BUSINESS_SAVINGS: </strong>A savings account primarily owned by a business</li><li><strong>PERSONAL_CHECKING: </strong>Seller's using their personal checking account.</li><li><strong>PERSONAL_SAVINGS: </strong>Seller's using their personal savings account.</li></ul>
      - `attempt_bank_account_validation_check` 'CHECKING' | 'SAVINGS' | 'PERSONAL_CHECKING' | 'PERSONAL_SAVINGS' | 'BUSINESS_CHECKING' | 'BUSINESS_SAVINGS' | 'CORPORATE' | 'CORP_SAVINGS'
      - `bank_code` string — The routing number of the bank account.
      - `name` string — The name of the bank account owner.
      - `type` 'BANK_ACCOUNT' — Type of `Payment Instrument`.
      - `country` string — 3-letter country code for the bank account (e.g., USA, CAN).
      - `currency` string — 3-letter ISO currency code for the bank account (e.g., USD, CAD).
    - `max_transaction_amount` integer, required — Maximum card amount that can be transacted for a single transaction in cents (max 12 characters). Must be equal to or less than your `max_transaction_amount`.
    - `ach_max_transaction_amount` integer — Maximum ACH amount that can be transacted for a single transaction in cents (max 12 characters). Must be equal to or less than your `ach_max_transaction_amount`.
    - `associated_files` object[] — List of [Files](#Files) your user uploaded inside their Onboarding Form.
      - `type` string — The `type` of the File.
      - `name` string — The name of the File.
      - `id` string — The `id` of the File.
      - `related_to` string — The `id` of the resource the File is linked to.
  - `merchant_processors` object[] — An array of objects with the processors and gateways users will be onboarded to.
    - `processor` string — The name of the processor you plan to onboard users to.
  - `onboarding_link_details` OnboardingLinkDetails — The information of the initial onboarding link. This is only provided when creating an `onboarding_form`.
    - `expiration_in_minutes` integer, required — How long (in minutes) the link should be valid for. Defaults to 60 minutes.
    - `expired_session_url` string, required — The URL users get sent to if the bearer token expires.
    - `fee_details_url` string, required — The URL of the page where you display the fees related to processing payments (for more info, see [Onboarding Forms](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/)).
    - `merchant_max_transaction_amount` integer — The maximum transaction amount for the merchant's card payment processing.
    - `merchant_ach_max_transaction_amount` integer — The maximum transaction amount for the merchant's ACH payment processing.
    - `return_url` string, required — The URL users get sent to after completing the onboarding flow.
    - `terms_of_service_url` string, required — Your Terms of Service URL. The URL is provided to users for consent along with Finix's Terms of Service.
  - `onboarding_link` OnboardingLink — The information of the initial onboarding link. This is only provided when creating an `onboarding_form`.
    - `expires_at` string — A UTC timestamp detailing when the onboarding form expires and will no longer be available via `link_url`. To generate a new link to the same form, see [Get an Onboarding Form URL](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms/#fetching-an-onboarding-form-link).
    - `link_url` string — The URL of the user's Finix Onboarding Form. Users can use the `link_url` to return to the form until the link expires.
  - `status` 'IN_PROGRESS' | 'COMPLETED' | 'UPDATE_REQUESTED' — Status of the `onboarding_form`.
  - `identity_id` string — The ID of the `identity` resource. This is only provided when the `onboarding_form` is `COMPLETED`.
  - `application_id` string — ID of the `Application` the resource was created under.
  - `created_at` string, date-time — Timestamp of when the object was created.
  - `updated_at` string, date-time — Timestamp of when the object was last updated.
  - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)

## Other responses

- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `404` — Not Found. The requested resource could not be found on the server.
- `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted.

---

[API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)