/

15 minute read

November 25, 2020

KYC Verification

Use the /kyc endpoint to perform Know Your Customer (KYC) verification tasks for your account holders.

This endpoint can only be used to perform KYC verification for individuals or businesses in the United States. Also, be aware that this endpoint does not work in your sandbox environment, only in production.

For more information about KYC verification, see About KYC Verification.

For more information about account holders, see About Account Holders.

Perform KYC

Action: POST
Endpoint: /kyc

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to verify the identity of an account holder in the United States, either a user or a business.

Required fields

In order to perform KYC verification, the user or business resource on which you perform the check must have the following fields configured with valid values:

User Fields Required for KYC Business Fields Required for KYC
  • first_name

  • last_name

  • address1 (cannot be PO Box)

  • city

  • state

  • postal_code

  • country

  • birth_date

  • ssn (full nine-digit SSN)

  • business_name_legal

  • business_name_dba

  • office_location (cannot be PO Box)

  • taxpayer_id

  • incorporation.incorporation_type

  • incorporation.state_of_incorporation

  • date_established

  • proprietor_or_officer

  • beneficial_owner (maximum of four beneficial owners)

  • attestation_consent

  • attester_name

  • attestation_date

Body field details (request)

Fields Description

token

string
Optional

The unique identifier of the identity check.

If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated.

Allowable Values:

36 char max

notes

string
Optional

Notes pertaining to a manual override. This field is returned in the response only when the manual_override field is set to true.

Allowable Values:

255 char max

manual_override

boolean
Optional

Set to true to designate a user account holder as having passed a verification check without Marqeta performing the check.

Use this override when you perform verification through another mechanism, such as with an alternative KYC provider or directly with the account holder. You must obtain explicit, written approval from Marqeta before using the manual_override field for KYC. Consult your Customer Success representative for more information.

You cannot use manual override for business KYC validation, only for user KYC.

Allowable Values:

true, false

Default value:
false

reference_id

string
Optional

Can be specified only if manual_override=true. If you verified a user account holder’s identity by performing a KYC verification outside of the Marqeta platform, you can use the reference_id field to store the reference number returned by that KYC provider.

Note
When you submit a KYC verification request with manual_override=false, the Marqeta platform performs the verification through one of its KYC providers. If the KYC provider responds with a reference ID, that ID is passed to you by way of this field in the response.

Allowable Values:

32 char max

user_token

OR

business_token

string
Required

Specifies the account holder on which to perform the identity check.

Pass either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

User KYC response

This section contains information relevant to KYC verification on user account holders.

Body field details (user response)

Fields Description

created_time

datetime
Returned

Time when the KYC verification was performed.

Allowable Values:

UTC timestamp

last_modified_time

datetime
Returned

Time when the KYC was last updated.

Allowable Values:

UTC timestamp

token

string
Conditionally returned

The unique identifier of the identity check.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

user_token

string
Conditionally returned

The account holder on which the identity check was performed.

Allowable Values:

Existing user token.

result

object
Conditionally returned

Contains information about the KYC verification result.

Allowable Values:

manual_override

boolean
Conditionally returned

If true, the user account holder is designated as having passed a verification check without Marqeta performing the check.

This override is used when verification is performed through another mechanism, such as with an alternative KYC provider or directly with the account holder.

Allowable Values:

true, false

Default value:
false

notes

string
Conditionally returned

Notes pertaining to a manual override. This field is included in the response only when the manual_override field is set to true.

Allowable Values:

255 char max

reference_id

string
Conditionally returned

If you verified the account holder’s identity by performing a KYC verification outside of the Marqeta platform, you can use the reference_id field to store the reference number returned by that KYC provider. This field is included in the response only when the manual_override field is set to true.

Note
When you send a KYC verification request with manual_override=false, the Marqeta platform performs the verification through one of its KYC providers. If the KYC provider responds with a reference ID, that ID is passed to you by way of this field in the response.

Allowable Values:

32 char max

The user result object (user response)

Fields Description

status

string
Conditionally returned

KYC verification status.

Allowable Values:

SUCCESS, FAILURE, PENDING

codes

object
Conditionally returned

Contains information about the KYC result codes.

Allowable Values:

Existing outcome_reason object

The result.codes object (user response)

Fields Description

code

string
Conditionally returned

Result code.

Allowable Values:

For any PENDING or FAILURE outcome, see the User KYC failure codes table.

message

string
Conditionally returned

Result code description.

Allowable Values:

Result code description.

User KYC failure codes (user response)

The following table lists KYC failure codes potentially returned in the response when a user does not pass verification. It also includes a list of acceptable documents that your customers can submit to resolve PENDING outcomes.

Failure Code and State Description Accepted Documents

AddressIssue
PENDING

Missing, invalid, mismatched, or PO Box address.

One of the following documents. Document must show the full name and address:

  • Current state-issued driver’s license or ID card

  • US Military Identification Card

  • Utility bill

  • Bank statement

  • Current rental or lease agreement

  • Mortgage statement

  • Insurance policy

  • State property tax bill or statement

  • Most recent three months' bank or credit card statement showing the user’s full name and address

DateofBirthIssue
PENDING

Invalid or mismatched date of birth.

Current government-issued photo ID that has name and date of birth:

  • Driver’s license or state-issued ID card

  • Passport or US passport card

  • Military Identification Card, Common Access Card (Active Military, Active Reserve, or Active Selected Reserve), or DD-214

  • American Indian Card (I-872)

NameIssue
PENDING

Invalid or mismatched name.

Current government-issued photo ID that has name and date of birth:

  • Driver’s license or state-issued ID card

  • Passport or US passport card

  • Military Identification Card, Common Access Card (Active Military, Active Reserve, or Active Selected Reserve), or DD-214

  • American Indian Card (I-872)

OFAC
FAILURE

Appears on an Office of Foreign Assets Control (OFAC) list.

None

RiskIssue
PENDING

Appears on a non-OFAC screening list, bankruptcy, or alert list, or has an insufficient record.

None

SSNFail
FAILURE

Social Security Number (SSN) appears on Network Alert List, is of a deceased person, or was issued before the individual’s date of birth.

None

SSNIssue
PENDING

Missing, invalid, or mismatched SSN.

  • Social Security card

  • Recent W-2 or 1099 showing nine-digit SSN, full name, and address.

User sample request and response bodies

These sample request and response bodies pertain to KYC verification for user account holders.

Sample request body for a user
{
  "token": "my_kyc01",
  "user_token": "my_user01",
  "manual_override": false
}

Is this helpful?

Sample response body for a user
{
  "token": "my_kyc01",

  "user_token": "my_user01",
  "result": {
    "status": "pending",
    "codes": [
      {
        "code": "failed check: AddressIssue"
      }
    ]
  },
  "manual_override": false,
  "created_time": "2020-02-08T19:52:58Z",
  "last_modified_time": "2020-02-08T19:52:58Z"
}

Is this helpful?

Business KYC response

This section contains information relevant to KYC verification on business account holders.

Body field details (business response)

Fields Description

token

string
Returned

The unique identifier of the identity check.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

business_token

string
Conditionally returned

The account holder on which the identity check was performed.

Allowable Values:

Existing business token.

status

string
Conditionally returned

KYC verification status.

Allowable Values:

SUCCESS, FAILURE, PENDING, VENDOR_PENDING

  • If any business component fails KYC verification, the KYC status is FAILURE.

  • If any business component has pending KYC verification, the KYC status is PENDING.

  • If any business component has been successfully submitted for verification, but the outcome was not determined in the allotted time, the KYC status is VENDOR_PENDING.

  • If all business components pass KYC verification, the KYC status is SUCCESS.

results

array
Conditionally returned

A list of KYC verification results for each business component.

Allowable Values:

The business result array (business response)

Fields Description

component

string
Returned

The business component submitted for KYC verification.

Allowable Values:

BUSINESS, PROPRIETOR, BENEFICIAL_OWNER1, BENEFICIAL_OWNER2, BENEFICIAL_OWNER3, BENEFICIAL_OWNER4

reference_id

string
Conditionally returned

The internal reference identifier for the KYC verification check on this business component.

Allowable Values:

32 char max

outcome

string
Conditionally returned

The outcome of KYC verification for this business component.

Note
The VENDOR_PENDING outcome indicates that the KYC request was successfully submitted, but the result was not determined within the allotted time. In such cases, the outcome will be sent to you through a webhook.

Allowable Values:

SUCCESS, FAILURE, PENDING, VENDOR_PENDING

outcome_reasons

array
Conditionally returned

A list of outcome reasons for each business component that did not pass KYC verification.

Allowable Values:

See the Business KYC outcome reasons (business response) table for outcome reasons and descriptions.

Business KYC outcome reasons (business response)

The following tables describe KYC outcome reasons potentially returned in the outcome_reasons field of the business result response object when a business is in a PENDING or FAILURE state. Where possible, they also describe acceptable documents that your customers can submit to resolve PENDING outcomes.

Outcome reasons for the business

These outcome reasons pertain to the business organization itself.

Outcome Reason and State Description Accepted Documents

AddressIssue
PENDING

Missing, invalid, mismatched, or PO Box address.

One of the following documents. Document must show the full business name and address:

  • Bank statement (last 60 days)

  • Utility bill (last 60 days)

  • Current lease or rental agreement, including the signature page

  • Insurance policy

  • State property tax bill or statement

  • Credit card statement (last 60 days)

BusinessNameIssue
PENDING

Invalid or mismatched name.

Articles or certificate of incorporation

OFACIssue
FAILURE

Business appears on an OFAC list.

None

RegistrationIssue
PENDING

Business is inactive, not registered, or not in good standing with the Secretary of State; recently reported or not recently updated.

None

Sanctions List Non-OFAC
PENDING

Business appears on a non-OFAC screening list, bankruptcy, or alert list.

None

TINIssue
PENDING

Missing, invalid, or mismatched Tax Identification Number (TIN).

IRS notice letter or most recent tax return

Outcome reasons for individuals associated with a business

These outcome reasons pertain to individuals associated with a business: proprietors, business officers, and beneficial owners.

Outcome Reason and State Description Accepted Documents

AddressIssue
PENDING

Missing, invalid, mismatched, or PO Box address for the individual.

One of the following documents. Document must show the full name and address:

  • Current state-issued driver’s license or ID card

  • US Military Identification Card

  • Utility bill

  • Bank statement

  • Current rental or lease agreement

  • Mortgage statement

  • Insurance policy

  • State property tax bill or statement

  • Most recent three months' bank or credit card statement showing the user’s full name and address

DateofBirthIssue
PENDING

Invalid or mismatched date of birth.

Current government-issued photo ID that has name and date of birth:

  • Driver’s license or state-issued ID card

  • Passport or US passport card

  • Military Identification Card, Common Access Card (Active Military, Active Reserve, or Active Selected Reserve), or DD-214

  • American Indian Card (I-872)

NameIssue
PENDING

Invalid or mismatched name.

Current government-issued photo ID that has name and date of birth:

  • Driver’s license or state-issued ID card

  • Passport or US passport card

  • Military Identification Card, Common Access Card (Active Military, Active Reserve, or Active Selected Reserve), or DD-214

  • American Indian Card (I-872)

OFAC
FAILURE

Proprietor, officer, or beneficial owner appears on an Office of Foreign Assets Control (OFAC) list.

None

SSNFail
FAILURE

Social Security Number (SSN) appears on Network Alert List, is of a deceased person, or was issued before the individual’s date of birth.

None

SSNIssue
PENDING

Missing, invalid, or mismatched SSN.

  • Social Security card

  • Recent W-2 or 1099 showing nine-digit SSN, full name, and address.

Business sample request and response bodies

These sample request and response bodies pertain to KYC verification for business account holders.

Sample request body for a business
{
  "token": "xyz-987",
  "business_token": "abc-123",
}

Is this helpful?

Sample response body for a business

An unsuccessful KYC verification on a business returns outcome reasons such as those shown in the following response:


{
  "token" : "xyz-987",
  "business_token": "abc-123",
  "status" : "PENDING",
  "results" : [
      {
     "component" : "BUSINESS",
	   "reference_id" : "xxxxx",
	   "outcome" : "SUCCESS",
	   "outcome_reasons" : []
      },
      {
     "component" : "PROPRIETOR",
	   "reference_id" : "yyyyy",
	   "outcome" : "PENDING",
	   "outcome_reasons" : ["SSNIssue", "DOBIssue"]
      },
      {
     "component" : "BENEFICIAL_OWNER1",
	   "reference_id" : "aaaaa",
	   "outcome" : "PENDING",
	   "outcome_reasons" : ["AddressIssue"]
      },
      {
     "component" : "BENEFICIAL_OWNER2",
	   "reference_id" : "bbbbb",
	   "outcome" : "SUCCESS",
	   "outcome_reasons" : []
      },
      {
     "component" : "BENEFICIAL_OWNER3",
	   "reference_id" : "ccccc",
	   "outcome" : "SUCCESS",
	   "outcome_reasons" : []
      },

      {
     "component" : "BENEFICIAL_OWNER4",
	   "reference_id" : "ddddd",
	   "outcome" : "SUCCESS",
	   "outcome_reasons" : []
      }
  ]
}

Is this helpful?

Retrieve KYC result

Action: GET
Endpoint: /kyc/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a specific KYC result.

URL path parameters

Fields Description

token

string
Required

Identifies the KYC result to retrieve.

Allowable Values:

Existing KYC token.

Send a GET request to /kyc/user/{user_token} to retrieve KYC tokens for a particular user or to /kyc/business/{business_token} to retrieve KYC tokens for a particular business.

Sample response body

{
  "created_time": "2020-03-07T22:52:39Z",
  "last_modified_time": "2020-03-07T22:52:39Z",
  "token": "my_user_01_kyc_01",
  "user_token": "my_user_01",
  "result": {
    "status": "success",
  },
  "manual_override": false
}

Is this helpful?

List KYC results for a user

Action: GET
Endpoint: /kyc/user/{user_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve all KYC results for a user.

This endpoint supports field filtering and pagination.

URL path parameters

Fields Description

user_token

string
Required

Identifies the user whose KYC results you want to list.

Allowable Values:

Existing user token

Send a GET request to /users to retrieve user tokens.

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "created_time": "2020-03-07T23:17:36Z",
      "last_modified_time": "2020-03-07T23:17:36Z",
      "token": "my_user_01_kyc_02",
      "user_token": "my_user_01",
      "result": {
        "status": "success",
      },
      "manual_override": false
    },
    {
      "created_time": "2020-03-07T22:52:39Z",
      "last_modified_time": "2020-03-07T22:52:39Z",
      "token": "my_user_01_kyc_01",
      "user_token": "my_user_01",
      "result": {
        "status": "pending",
      },
      "manual_override": false
    }
  ]
}

Is this helpful?

List KYC results for business

Action: GET
Endpoint: /kyc/business/{business_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve all KYC results for a business.

This endpoint supports field filtering and pagination.

URL path parameters

Fields Description

business_token

string
Required

Identifies the business whose KYC results you want to list.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "created_time": "2020-09-25T05:35:02Z",
      "last_modified_time": "2020-09-25T05:35:02Z",
       "token": "164dc008-1503-4932-a42d-27739346710f",
       "business_token": "my-business-token",
        "result": {
          "status": "pending"
         },
      "manual_override": false
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.