KYC Prefill

KYC Prefill accelerates onboarding by pre-populating verified identity data from just a phone number. Rather than asking the account holder to manually enter their information, frameOS looks up and pre-fills their first name, last name, address, date of birth, and last 4 of SSN — so they only need to confirm what's already there.

KYC Prefill also acts as a fraud signal. If the phone number can't be trusted, the account holder will be asked to submit their identity information manually. That prefill failure is factored into frameOS's internal evaluation of whether KYC should pass or fail — and if KYC fails, the associated capabilities will not be enabled.

ENDPOINTS

POST/v1/accounts

How it works

Create an account with the kyc_prefill capability and the account holder's phone number.
frameOS looks up verified identity data tied to that phone number, including name, address, date of birth, and last 4 of SSN.
The onboarding session is pre-populated with that data. The account holder confirms the details and provides one additional verification factor — either date of birth or last 4 of SSN.
frameOS evaluates the result. If the phone number is trusted and the details match, KYC passes. If the phone number has a low trust score or the submitted details don't match verified records, the evaluation fails.

KYC Prefill is designed to work alongside KYC. Add both capabilities to an account to get the full prefill-and-verify flow.

Prefilled data

When a phone number is matched, frameOS pre-populates the following fields in the onboarding session:

Field	Description
First name	Legal first name tied to the phone number
Last name	Legal last name tied to the phone number
Address	Most recent address on record
Date of birth	Account holder's date of birth
Last 4 of SSN	Last four digits of the Social Security Number

The account holder must confirm one additional verification factor during onboarding: either date of birth or last 4 of SSN.

Fraud prevention

KYC Prefill evaluates the trustworthiness of the phone number as part of the verification process. If the phone number has a low trust score, prefill will not succeed and the account holder will be prompted to submit their identity information manually instead.

That prefill failure doesn't immediately block the account — but it is used as a signal in frameOS's internal KYC evaluation. If the overall evaluation determines that KYC should fail, the associated capabilities will not be enabled.

Create an account with KYC Prefill

Add kyc_prefill to the capabilities array when creating the account. Include kyc as well to run the full verification flow. The account holder's phone number is required — it's the key used to look up their verified identity data.

Parameters

typestringrequired

Must be individual. KYC Prefill is only supported for individual accounts.

capabilitiesarrayrequired

Include kyc_prefill to enable prefill. Add kyc alongside it to run the full identity verification flow.

profile.individual.phoneobjectrequired

Object containing number and country_code. Used to look up the account holder's verified identity data.

profile.individual.emailstringoptional

The account holder's email address.

profile.individual.name.first_namestringoptional

The account holder's first name. If provided, this will be shown for confirmation during onboarding.

profile.individual.name.last_namestringoptional

The account holder's last name. If provided, this will be shown for confirmation during onboarding.

POST/v1/accounts

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["kyc", "kyc_prefill"],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'

RESPONSE

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "account",
  "type": "individual",
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "kyc",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567893",
      "object": "capability",
      "name": "kyc_prefill",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": null,
        "middle_name": null,
        "last_name": null,
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Complete onboarding

Once the account is created, create an onboarding session to launch the prefill flow. frameOS will look up the phone number, pre-populate the session with verified data, and prompt the account holder to confirm their details.

REQUEST

curl --request POST \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "return_url": "https://example.com/onboarding/complete"
}'

After the account holder completes the session, retrieve the account to check the kyc capability status. A status of active means verification passed. A status of failed means the phone number could not be trusted or the provided details did not match verified records.