Perform KYC

Action: POST
Endpoint: /kyc

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/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 business_name_legal
last_name business_name_dba
address1 (Cannot be PO Box) office_location (Cannot be PO Box)
city taxpayer_id
state incorporation.incorporation_type
zip incorporation.state_of_incorporation
country phone (the top-level phone field)
birth_date date_established
ssn (full or last four)

Body field details

Name Type Required? Description Allowable Values
token string No 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 API 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.
36 char max
notes string No Notes pertaining to a manual override. This field is returned in the response only when the manual_override field is set to true.
manual_override boolean No 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.
true | false

Default: false
reference_id string No 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 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.
32 char max
user_token

OR

business_token
string Yes Specifies the account holder on which to perform the identity check.

Pass either user_token or business_token, not both.
Existing user or business token.

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

The result.failed_questions_count field (response)

Name Type Required? Description Allowable Values
result.failed_questions_count integer Present if questions
are presented
Keeps the count of incorrect answers to questions. 0–5

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
BizTaxIDFailure The business tax ID number (TIN) is incorrect. (taxpayer_id field)
AddressResidential The address provided is registered as a residential address.
DBAFailure The fictitious business name (DBA) is incorrect. (business_name_dba field)
GoodStandingFailure The business is listed as "not in good standing" by the Secretary of State in the business's registered state.
OFACFailure The registered business location is on the international OFAC list.
WatchlistFailure The registered business location is on another governmental watchlist.
BizInactive The business is listed as inactive by the Secretary of State in the business's registered state.
OtherFailure The business entity is not confirmed at the address provided.

Sample request body

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

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"
}

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: BizTaxIDFailure"
},
{
"code": "failed check: OtherFailure"
}
]
},
"manual_override": false
}


Retrieve KYC result

Action: GET
Endpoint: /kyc/{token}

Use this endpoint to retrieve a specific KYC result.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the KYC result to retrieve. Existing KYC token.

Issue a GET 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": "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
}


Update KYC with answers

Action: PUT
Endpoint: /kyc/{token}

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

Name Type Required? Description Allowable Values
token string Yes Identifies the KYC to update. Existing KYC token.

Issue a GET 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 request

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

Sample response

{
"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"
}


List KYC results for user

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

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

This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user whose KYC results you want to list. Existing user token.

Issue a GET to /users to retrieve user tokens.

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
}
]
}


List KYC results for business

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

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

This endpoint supports field filtering and pagination.

URL path parameters

Name Type Required? Description Allowable Values
business_token string Yes Identifies the business whose KYC results you want to list. Existing business token.

Issue a GET to /businesses to retrieve business tokens.

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
}
]
}