/

15 minute read

September 23, 2020

KYC Verification

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

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 (a user or business).

Required fields

In order to perform a KYC check, 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)

  • business_name_legal

  • business_name_dba

  • office_location (cannot be PO Box)

  • taxpayer_id

  • incorporation.incorporation_type

  • incorporation.state_of_incorporation

  • phone (the top-level phone field)

  • date_established

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:

manual_override

boolean
Optional

Set to true to designate an 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.

Allowable Values:

true, false

Default value:
false

reference_id

string
Optional

Can be specified only if manual_override=true. 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 your KYC provider.

Note
When you sent 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.

Body field details (response)

Fields Description

created_time

datetime
Returned

Time when the KYC check was performed.

Allowable Values:

last_modified_time

datetime
Returned

Time when the KYC was last updated.

Allowable Values:

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

OR

business_token

string
Conditionally returned

The account holder on which the identity check is performed.

Either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

result

object
Conditionally returned

Contains information about the KYC result.

Allowable Values:

manual_override

boolean
Conditionally returned

If true, the 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
Included if a manual override is used

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:

questions

object
Conditionally returned

Contains information about the questions presented during the check, if applicable.

Allowable Values:

reference_id

string
Conditionally returned

This field is included in the response only when the manual_override field is set to true. 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 your KYC provider.

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 result object (response)

Fields Description

status

string
Conditionally returned

Status of the KYC check.

Allowable Values:

SUCCESS, FAILURE, PENDING

codes

object
Conditionally returned

Contains information about the KYC result codes, if status is FAILURE or PENDING.

Allowable Values:

Existing codes object.

failed_questions_count

integer
Conditionally returned

Keeps the count of incorrect answers to questions. Included if questions are presented.

Allowable Values:

0–5

The questions object (response)

Fields Description

key

string
Conditionally returned

Acceptable answers to the challenge question, if applicable.

Allowable Values:

Existing key string.

question

string
Conditionally returned

The challenge question presented, if applicable.

Allowable Values:

Existing question string.

answers

array
Conditionally returned

Answers given in response to the question, if applicable.

Allowable Values:

Existing answers array.

The result.codes object (response)

Fields Description

created_time

datetime
Returned

Time when the KYC check was performed.

Allowable Values:

last_modified_time

datetime
Returned

Time when the KYC was last updated.

Allowable Values:

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

OR

business_token

string
Conditionally returned

The account holder on which the identity check is performed.

Either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

result

object
Conditionally returned

Contains information about the KYC result.

Allowable Values:

manual_override

boolean
Conditionally returned

If true, the 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
Included if a manual override is used

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:

questions

object
Conditionally returned

Contains information about the questions presented during the check, if applicable.

Allowable Values:

reference_id

string
Conditionally returned

This field is included in the response only when the manual_override field is set to true. 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 your KYC provider.

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 result object (response)

Fields Description

status

string
Conditionally returned

Status of the KYC check.

Allowable Values:

SUCCESS, FAILURE, PENDING

codes

object
Conditionally returned

Contains information about the KYC result codes.

Allowable Values:

Existing codes object.

failed_questions_count

integer
Included if questions are presented

Keeps the count of incorrect answers to questions.

Allowable Values:

0–5

The questions object (response)

Fields Description

key

string
Conditionally returned

Acceptable answers to the question.

Allowable Values:

Existing key string.

question

string
Conditionally returned

The challenge question presented.

Allowable Values:

Existing question string.

answers

array
Conditionally returned

Answers given in response to the question.

Allowable Values:

Existing answers array.

The result.codes object (response)

Fields Description

code

string
Conditionally returned

Result code.

Allowable Values:

Result codes vary, depending on the KYC provider.

message

string
Conditionally returned

Result code description.

Allowable Values:

Result code descriptions vary, depending on the KYC provider.

User KYC failure codes (response)

The following table lists KYC failure codes potentially returned in the response when a user fails verification.

Failure Code Failure Description

AddressIssue

Missing, invalid, mismatched, or PO Box address.

DateofBirthIssue

Invalid or mismatched date of birth.

DriversLicenseIssue

Invalid or unknown driver’s license number.

EmailIssue

Unknown email address or high-risk characteristics.

IPAddressIssue

Unknown location or high-risk characteristics.

NameIssue

Invalid or mismatched name.

OFAC

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

PhoneIssue

Unknown, mismatched, or invalid phone number.

RiskIssue

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

SSNIssue

Missing, invalid, or mismatched Social Security Number (SSN), or SSN is of a deceased person.

Business KYC failure codes (response)

The following table lists KYC failure codes potentially returned in the response when a business fails verification.

Failure Code Failure Description

AddressIssue

Missing, invalid, mismatched, or PO Box address.

NameIssue

Invalid or mismatched name.

OFAC

Appears on an OFAC list.

PhoneIssue

Unknown, mismatched, or invalid phone number.

RegistrationIssue

Inactive, not registered, or not in good standing with the Secretary of State, or recently reported or not recently updated.

RiskIssue

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

TINIssue

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

Sample request body

{
  "token": "my_kyc01",
  "user_token": "my_user01",
  "manual_override": false
}

Is this helpful?

Sample response bodies

KYC verifications on users (but not businesses) can potentially return a questions field in the response. Whether or not a questions field is returned depends on the identity-check provider and whether challenge questions are available for the user. The following sample response body shows this questions field.

{
  "token": "my_kyc01",
  "questions": [
    {
      "key": "alternate.names.phone",
      "question": "With which name are you associated?",
      "answers": [
        "WINQUIST",
        "WALKER",
        "WALEED",
        "WINCHEZ",
        "None of the above"
      ]
    },
    {
      "key": "prior.residence.state.multiyear",
      "question": "Between 1979 and 1980, in which State did you live?",
      "answers": [
        "KENTUCKY",
        "MISSOURI",
        "KANSAS",
        "NEW YORK",
        "None of the above"
      ]
    }
  ],
  "user_token": "my_user01",
  "result": {
    "status": "pending",
    "codes": [
      {
        "code": "low risk score"
      }
    ]
  },
  "manual_override": false,
  "created_time": "2016-02-08T19:52:58Z",
  "last_modified_time": "2016-02-08T19:52:58Z"
}

Is this helpful?

A failed KYC check on a business returns failure codes such as those shown in the following response:

{
  "created_time": "2017-03-04T00:28:09Z",
  "last_modified_time": "2017-03-04T00:28:09Z",
  "token": "my_business_01_kyc_01",
  "business_token": "my_business_01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "failed check: TINIssue"
      },
      {
        "code": "failed check: AddressIssue"
      }
    ]
  },
  "manual_override": false
}

Is this helpful?

Retrieve KYC result

Action: GET
Endpoint: /kyc/{token}

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.

Develop Now!

Sign in and use your sandbox to access the API Explorer

Sample response body

{
  "created_time": "2017-03-07T22:52:39Z",
  "last_modified_time": "2017-03-07T22:52:39Z",
  "token": "my_user_01_kyc_01",
  "user_token": "my_user_01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "full_ssn_required"
      }
    ]
  },
  "manual_override": false
}

Is this helpful?

Update KYC with answers

Action: PUT
Endpoint: /kyc/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

If a user fails KYC and the original KYC returns a questions field, use this endpoint to update the KYC with answers. (You obtain the answers by way of a separate request to the user.)

Note
A program-level setting determines the amount of time provided to answer the questions. The default value is 240 seconds. Marqeta can adjust this setting if necessary.

URL path parameters

Fields Description

token

string
Required

Identifies the KYC to update.

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.

Body field details (request)

Fields Description

answers

object
Required

Contains information about acceptable answers to a KYC challenge question.

Allowable Values:

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.

The answers object (request)

Fields Description

answer

string
Optional

Answer given in response to a challenge question.

Allowable Values:

255 char max

key

string
Optional

Acceptable answer to the challenge question.

Allowable Values:

255 char max

Sample request body

{
  "answers": [
    { "key": "alternate.names.phone", "answer": "None of the above" },
    { "key": "prior.residence.state.multiyear", "answer": "NEW YORK" }
  ]
}

Is this helpful?

Sample response body

{
  "token": "my_kyc01",
  "user_token": "my_user01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "low risk score"
      }
    ]
  },
  "manual_override": false,
  "created_time": "2016-02-08T19:52:58Z",
  "last_modified_time": "2016-02-08T19:52:58Z"
}

Is this helpful?

List KYC results for 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.

count

integer
Optional

Number of items to retrieve.

Allowable Values:

Default value:
5

start_index

integer
Optional

Start index.

Allowable Values:

Default value:
0

fields

string
Optional

Comma-delimited list of fields to return (e.g. question,answers,key,..). Leave blank to return all fields.

Allowable Values:

sort_by

string
Optional

Sort order.

Allowable Values:

Default value:
-createdTime

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "created_time": "2017-03-07T23:17:36Z",
      "last_modified_time": "2017-03-07T23:17:36Z",
      "token": "my_user_01_kyc_02",
      "user_token": "my_user_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "unknown"
          }
        ]
      },
      "manual_override": false
    },
    {
      "created_time": "2017-03-07T22:52:39Z",
      "last_modified_time": "2017-03-07T22:52:39Z",
      "token": "my_user_01_kyc_01",
      "user_token": "my_user_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "full_ssn_required"
          }
        ]
      },
      "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.

count

integer
Optional

Number of items to retrieve.

Allowable Values:

Default value:
5

start_index

integer
Optional

Start index.

Allowable Values:

Default value:
0

fields

string
Optional

Comma-delimited list of fields to return (e.g. question,answers,key,..). Leave blank to return all fields.

Allowable Values:

sort_by

string
Optional

Sort order.

Allowable Values:

Default value:
-createdTime

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "created_time": "2017-03-06T19:06:32Z",
      "last_modified_time": "2017-03-06T19:06:32Z",
      "token": "89807a33-f46f-4562-b068-52a5de769542",
      "business_token": "my_business_01",
      "result": {
        "status": "success"
      },
      "manual_override": true
    },
    {
      "created_time": "2017-03-04T00:28:09Z",
      "last_modified_time": "2017-03-04T00:28:09Z",
      "token": "my_business_01_kyc_01",
      "business_token": "my_business_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "failed check: BizTaxIDFailure"
          },
          {
            "code": "failed check: OtherFailure"
          }
        ]
      },
      "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.