> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC Verification
> Use the KYC endpoint to perform Know Your Customer (KYC) verification tasks for your individual and business account holders.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Perform KYC verification
**Action:** `POST`\
**Endpoint:** `/kyc`
{/* */}
Use this endpoint to verify the identity of an account holder in the United States, either a user or a business. You can perform KYC verification on an account holder, provided the following are true:
* The KYC status of the account holder is `UNVERIFIED`, `LIMITED`, or `ACTIVE`.
* The account holder has not been submitted for KYC verification more than twice.
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` (legal first name only, no prefixes)
- `last_name` (legal last name only, no suffixes)
- `address1` (cannot be a PO Box)
- `city`
- `state`
- `postal_code`
- `country`
- `birth_date`
- `identifications` (nine digits, no delimiters)
- `email` (required in some cases)
- `phone` (required in some cases) | - `business_name_legal` (128 char max)
- `business_name_dba` ("Doing Business As" or fictitious business name; enter the legal business name in this field if your business does not use a fictitious business name)
- `office_location` (cannot be a PO Box; `state` field must use a valid state, provincial, territorial, or federal abbreviation)
- `identifications` (nine digits, no delimiters)
- `incorporation.incorporation_type`
- `incorporation.state_of_incorporation`
- `date_established`
- `proprietor_or_officer`
- `beneficial_owner` (maximum of four beneficial owners)
- `proprietor_is_beneficial_owner` (required if the business proprietor or officer is also a beneficial owner)
- `attestation_consent`
- `attester_name`
- `attestation_date`
- `general_business_description` |
Valid state, provincial, territorial, and federal abbreviations
The following list includes all valid two-letter abbreviations for US states, territories, and military (APO/FPO/DPO) addresses. It also includes two-letter abbreviations for Canadian provinces and territories and three-letter abbreviations for supported countries. State, provincial, territorial, and federal abbreviations are case sensitive, and must be in uppercase as they appear in this list:
* `AL`: Alabama
* `AK`: Alaska
* `AB`: Alberta
* `AS`: American Samoa
* `AZ`: Arizona
* `AR`: Arkansas
* `AE`: Armed Forces
* `AA`: Armed Forces Americas
* `AP`: Armed Forces Pacific
* `BC`: British Columbia
* `CA`: California
* `CAN`: Canada
* `CO`: Colorado
* `CT`: Connecticut
* `DE`: Delaware
* `DC`: District of Columbia
* `FL`: Florida
* `GA`: Georgia
* `GU`: Guam
* `HI`: Hawaii
* `ID`: Idaho
* `IL`: Illinois
* `IN`: Indiana
* `IA`: Iowa
* `KS`: Kansas
* `KY`: Kentucky
* `LA`: Louisiana
* `ME`: Maine
* `MB`: Manitoba
* `MD`: Maryland
* `MA`: Massachusetts
* `MI`: Michigan
* `MN`: Minnesota
* `MS`: Mississippi
* `MO`: Missouri
* `MT`: Montana
* `NE`: Nebraska
* `NV`: Nevada
* `NB`: New Brunswick
* `NH`: New Hampshire
* `NJ`: New Jersey
* `NM`: New Mexico
* `NY`: New York
* `NF`: Newfoundland
* `NC`: North Carolina
* `ND`: North Dakota
* `NT`: Northwest Territories
* `NS`: Nova Scotia
* `NU`: Nunavut
* `OH`: Ohio
* `OK`: Oklahoma
* `ON`: Ontario
* `OR`: Oregon
* `PA`: Pennsylvania
* `PE`: Prince Edward Island
* `PR`: Puerto Rico
* `QC`: Quebec
* `RI`: Rhode Island
* `SK`: Saskatchewan
* `SC`: South Carolina
* `SD`: South Dakota
* `TN`: Tennessee
* `TX`: Texas
* `USA`: United States of America
* `UT`: Utah
* `VT`: Vermont
* `VI`: Virgin Islands
* `VA`: Virginia
* `WA`: Washington
* `WV`: West Virginia
* `WI`: Wisconsin
* `WY`: Wyoming
* `YT`: Yukon Territory
Request body
| Fields | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| business\_token
string
Optional | Specifies the business account holder on which to perform the identity check. Do not pass this field if your request includes the `user_token` field.
Send a `GET` request to `/businesses` to retrieve business tokens.
**Allowable Values:**
1–36 chars |
| manual\_override
boolean
Optional | Set to `true` to designate a user account holder as having passed a verification check without Marqeta performing the check through one of its KYC providers.
Use this override when you perform verification through another mechanism, such as 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 verification. This feature is only available to programs that are enabled to perform their own Customer Identification Program (CIP) KYC verification. Consult your Marqeta representative for more information.
**Allowable Values:**
`true`, `false`
**Default value:**
`false` |
| 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 |
| 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 identifier, that identifier is passed to you by way of this field in the response.
**Allowable Values:**
32 char max |
| token
string
Optional | 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.
**Allowable Values:**
1–36 chars |
| user\_token
string
Optional | Specifies the user account holder on which to perform the identity check. Do not pass this field if your request includes the `business_token` field.
Send a `GET` request to `/users` to retrieve user tokens.
**Allowable Values:**
1–36 chars
Existing user token |
Sample request body
**Sample request body for a user**
```json JSON lines wrap theme={null}
{
"token": "my_userkyc01",
"user_token": "my_user01",
"manual_override": false
}
```
**Sample request body for a business**
```json JSON lines wrap theme={null}
{
"token": "my_bizkyc01",
"business_token": "my_biz01"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| business\_token
string
Conditionally returned | The business account holder on which the identity check was performed.
**Allowable Values:**
Existing business token |
| created\_time
datetime
Returned | Time when the KYC verification was performed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Time when the KYC verification was last updated.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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 an alternative KYC provider or directly with the account holder.
**Allowable Values:**
`true`, `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 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 identifier, that identifier is passed to you by way of this field in the response.
**Allowable Values:**
32 char max |
| result
object
Conditionally returned | Contains information about the KYC verification result.
**Allowable Values:**
Existing KYC verification object |
| result.**codes**
array of objects
Conditionally returned | An array of KYC verification result code objects.
**Allowable Values:**
One or more KYC verification result code objects |
| result.codes\[].**code**
string
Conditionally returned | For any `pending` or `failure` outcome, see the User KYC failure codes table, the Outcome reasons for the business table, or the Outcome reasons for individuals associated with a business table.
**Allowable Values:**
`AddressIssue`, `DateofBirthIssue`, `Denied KYC`, `NameIssue`, `NoRecordFound`, `OFACFailure`, `RiskIssue`, `SSNIssue`, `warm address alert` |
| result.codes\[].**message**
string
Conditionally returned | Result code description.
**Allowable Values:**
255 char max |
| result.**status**
string
Conditionally returned | KYC verification status.
**Allowable Values:**
`success`, `failure`, `pending` |
| token
string
Conditionally returned | The unique identifier of the identity check.
**Allowable Values:**
Existing identity check token |
| user\_token
string
Conditionally returned | The user account holder on which the identity check was performed.
**Allowable Values:**
Existing user token |
Sample response body
**Sample response body for a user**
```json JSON lines wrap theme={null}
{
"token": "my_userkyc01",
"user_token": "my_user01",
"result": {
"status": "failure",
"codes": [
{
"code": "AddressIssue"
}
]
},
"manual_override": false,
"created_time": "2025-02-08T19:52:58Z",
"last_modified_time": "2025-02-08T19:52:58Z"
}
```
**Sample response body for a business**
```json JSON expandable lines wrap theme={null}
{
"token": "my_bizkyc01",
"business_token": "my_biz01",
"status": "pending",
"created_time": "2025-02-08T19:52:58Z",
"last_modified_time": "2025-02-08T19:52:58Z",
"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": []
}
]
}
```
List KYC results for a business
**Action:** `GET`\
**Endpoint:** `/kyc/business/{business_token}`
{/* */}
Use this endpoint to retrieve all KYC verification results for a business.
This endpoint supports [pagination](/core-api/sorting-and-pagination/).
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
- Utility bill
- Current lease or rental agreement
- Insurance policy |
| BusinessNameIssue
`pending` | Invalid or mismatched name. | Articles or certificate of incorporation. |
| OFACFailure
`failure` | Business appears on an Office of Foreign Assets Control (OFAC) list. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| RegistrationIssue
`pending` | Business is inactive, not registered, or not in good standing with the Secretary of State; recently reported or not recently updated. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| Sanctions List Non-OFAC
`pending` | Business appears on a non-OFAC screening list, bankruptcy, or alert list. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| TINIssue
`pending` | Missing, invalid, or mismatched Tax Identification Number (TIN). | IRS Notice Letter 147C or CP575, or most recent tax return. |
| Watchlist
`failure` | Appears on government watchlist (such as OFAC) or other relevant watchlists. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
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. | One of the following documents. Document must show the full name and address:
- Unexpired state-issued driver’s license or identification card
- US Military Identification Card
- Utility bill
- Bank statement
- Current rental or lease agreement
- Mortgage statement |
| DateOfBirthIssue
`pending` | Invalid or mismatched date of birth. | Unexpired government-issued photo identification that shows name and date of birth:
- Driver’s license or state-issued identification card
- Passport |
| Denied KYC
`failure` | KYC denied for cardholder | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| NameIssue
`pending` | Invalid or mismatched name. | Unexpired government-issued photo identification that has name and date of birth:
- Driver’s license or state-issued identification card
- Passport or US passport card |
| NoRecordFound
`failure` | No records were found for this individual. | As no record was found for this individual, supporting documentation must be provided for each attribute (name, date of birth, address, and SSN):
- To verify an individual’s address, provide one of these documents:
- Unexpired state-issued driver’s license or identification card
- US Military Identification Card
- Utility bill
- Bank statement
- Current rental or lease agreement
- Mortgage statement
- To verify an individual’s name and date of birth, provide one of these documents:
- Driver’s license or state-issued identification card
- Passport
- To verify an individual’s Social Security Number, provide one of these documents:
- Social Security card
- Recent W-2 or 1099 showing nine-digit SSN, full name, and address
- ITIN card or document showing ITIN approval |
| OFACFailure
`failure` | Appears on an Office of Foreign Assets Control (OFAC) list. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| RiskIssue
`failure` | Appears on a non-OFAC screening list, bankruptcy, or alert list, or has an insufficient record. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative.
`failure` |
| SSNIssue
`pending` | Missing, invalid, or mismatched SSN. | - Social Security card
- Recent W-2 or 1099 showing nine-digit SSN, full name, and address
- ITIN card or document showing ITIN approval |
| warm address alert
`failure` | Address is a PO box or other post office address, virtual address, UPS store, mail forward, or mail drop. Such addresses are not valid for KYC verification. | One of the following documents. Document must show the full name and valid street address:
- US Military Identification Card
- Utility bill
- Current rental or lease agreement
- Mortgage statement |
| Watchlist
`failure` | Appears on government watchlist (such as OFAC) or other relevant watchlists. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
URL path parameters
| Fields | Description |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| business\_token
string
Required | The unique identifier of the business resource for which you want to retrieve KYC verification results.
**Allowable Values:**
Existing business token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count
integer
Optional | The number of resources to retrieve.
**Allowable Values:**
1-10 |
| start\_index
integer
Optional | The sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of KYC verification response objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more KYC verification response objects |
| data\[].**business\_token**
string
Conditionally returned | The business account holder on which the identity check was performed.
**Allowable Values:**
Existing business token |
| data\[].**created\_time**
datetime
Returned | Time when the KYC verification was performed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**last\_modified\_time**
datetime
Returned | Time when the KYC verification was last updated.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**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 an alternative KYC provider or directly with the account holder.
**Allowable Values:**
`true`, `false` |
| data\[].**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 |
| data\[].**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 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 identifier, that identifier is passed to you by way of this field in the response.
**Allowable Values:**
32 char max |
| data\[].**result**
object
Conditionally returned | Contains information about the KYC verification result.
**Allowable Values:**
Existing KYC verification object |
| data\[].result.**codes**
array of objects
Conditionally returned | An array of KYC verification result code objects.
**Allowable Values:**
One or more KYC verification result code objects |
| data\[].result.codes\[].**code**
string
Conditionally returned | For any `pending` or `failure` outcome, see the User KYC failure codes table, the Outcome reasons for the business table, or the Outcome reasons for individuals associated with a business table.
**Allowable Values:**
`AddressIssue`, `DateofBirthIssue`, `Denied KYC`, `NameIssue`, `NoRecordFound`, `OFACFailure`, `RiskIssue`, `SSNIssue`, `warm address alert` |
| data\[].result.codes\[].**message**
string
Conditionally returned | Result code description.
**Allowable Values:**
255 char max |
| data\[].result.**status**
string
Conditionally returned | KYC verification status.
**Allowable Values:**
`success`, `failure`, `pending` |
| data\[].**token**
string
Conditionally returned | The unique identifier of the identity check.
**Allowable Values:**
Existing identity check token |
| data\[].**user\_token**
string
Conditionally returned | The user account holder on which the identity check was performed.
**Allowable Values:**
Existing user token |
| end\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| start\_index
integer
Conditionally returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
Sample response body
```json JSON lines wrap theme={null}
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"created_time": "2024-09-25T05:35:02Z",
"last_modified_time": "2024-09-25T05:35:02Z",
"token": "164dc008-1503-4932-a42d-27739346710f",
"business_token": "my-business-token",
"result": {
"status": "pending"
},
"manual_override": false
}
]
}
```
List KYC results for a user
**Action:** `GET`\
**Endpoint:** `/kyc/user/{user_token}`
{/* */}
Use this endpoint to retrieve all KYC results for a user.
This endpoint supports [pagination](/core-api/sorting-and-pagination/).
User KYC failure codes
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 failures.
| Failure Code and State | Description | Accepted Documents |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AddressIssue
`failure` | Missing, invalid, mismatched, or PO Box address. | One of the following documents. Document must show the full name and address:
- Unexpired state-issued driver’s license or identification card
- US Military Identification Card
- Utility bill
- Bank statement
- Current rental or lease agreement
- Mortgage statement |
| DateOfBirthIssue
`failure` | Invalid or mismatched date of birth. | Unexpired government-issued photo identification that shows name and date of birth:
- Driver’s license or state-issued identification card
- Passport |
| Denied KYC
`failure` | KYC denied for cardholder. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| EmailIssue
`failure` | Invalid, insufficient, mismatched, or other risk signal on provided email address. | Unexpired government-issued photo identification that shows name and date of birth:
- Driver’s license or state-issued identification card
- US Passport
- US Military identification Card
- Native American tribal identification card
- Government employee identification card
- Permanent Resident Alien Card |
| NameIssue
`failure` | Invalid or mismatched name. | Unexpired government-issued photo identification that has name and date of birth:
- Driver’s license or state-issued identification card
- Passport or US passport card |
| NoRecordFound
`failure` | No records were found for this individual. | As no record was found for this individual, supporting documentation must be provided for each attribute (name, date of birth, address, and SSN):
- To verify an individual’s address, provide one of these documents:
- Unexpired state-issued driver’s license or identification card
- US Military Identification Card
- Utility bill
- Bank statement
- Current rental or lease agreement
- Mortgage statement
- To verify an individual’s name and date of birth, provide one of these documents:
- Driver’s license or state-issued identification card
- Passport
- To verify an individual’s Social Security Number, provide one of these documents:
- Social Security card
- Recent W-2 or 1099 showing nine-digit SSN, full name, and address
- ITIN card or document showing ITIN approval |
| OFACFailure
`failure` | Appears on an Office of Foreign Assets Control (OFAC) list. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| PhoneIssue
`failure` | Invalid, insufficient, mismatched, or other risk signal on provided phone number. | Unexpired government-issued photo identification that shows name and date of birth:
- Driver’s license or state-issued identification card
- US Passport
- US Military identification Card
- Native American tribal identification card
- Government employee identification card
- Permanent Resident Alien Card |
| RiskIssue
`failure` | Appears on a non-OFAC screening list, bankruptcy, or alert list, or has an insufficient record. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
| SSNIssue
`failure` | Missing, invalid, or mismatched SSN. | - Social Security card
- Recent W-2 or 1099 showing nine-digit SSN, full name, and address
- ITIN card or document showing ITIN approval |
| warm address alert
`failure` | Address is a PO box or other post office address, virtual address, UPS store, mail forward, or mail drop. Such addresses are not valid for KYC verification. | One of the following documents. Document must show the full name and valid street address:
- US Military Identification Card
- Utility bill
- Current rental or lease agreement
- Mortgage statement |
| Watchlist
`failure` | Appears on government watchlist (such as OFAC) or other relevant watchlists. | This outcome requires a manual review by Marqeta to determine the next appropriate step. Contact your Marqeta representative. |
URL path parameters
| Fields | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_token
string
Required | Unique identifier of the user resource for which you want to retrieve KYC verification results.
**Allowable Values:**
Existing user resource token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources to retrieve.
**Allowable Values:**
1-10 |
| start\_index
integer
Optional | Sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model
**Default value:**
`-createdTime` |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of KYC verification response objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more KYC verification response objects |
| data\[].**business\_token**
string
Conditionally returned | The business account holder on which the identity check was performed.
**Allowable Values:**
Existing business token |
| data\[].**created\_time**
datetime
Returned | Time when the KYC verification was performed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**last\_modified\_time**
datetime
Returned | Time when the KYC verification was last updated.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**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 an alternative KYC provider or directly with the account holder.
**Allowable Values:**
`true`, `false` |
| data\[].**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 |
| data\[].**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 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 identifier, that identifier is passed to you by way of this field in the response.
**Allowable Values:**
32 char max |
| data\[].**result**
object
Conditionally returned | Contains information about the KYC verification result.
**Allowable Values:**
Existing KYC verification object |
| data\[].result.**codes**
array of objects
Conditionally returned | An array of KYC verification result code objects.
**Allowable Values:**
One or more KYC verification result code objects |
| data\[].result.codes\[].**code**
string
Conditionally returned | For any `pending` or `failure` outcome, see the User KYC failure codes table, the Outcome reasons for the business table, or the Outcome reasons for individuals associated with a business table.
**Allowable Values:**
`AddressIssue`, `DateofBirthIssue`, `Denied KYC`, `NameIssue`, `NoRecordFound`, `OFACFailure`, `RiskIssue`, `SSNIssue`, `warm address alert` |
| data\[].result.codes\[].**message**
string
Conditionally returned | Result code description.
**Allowable Values:**
255 char max |
| data\[].result.**status**
string
Conditionally returned | KYC verification status.
**Allowable Values:**
`success`, `failure`, `pending` |
| data\[].**token**
string
Conditionally returned | The unique identifier of the identity check.
**Allowable Values:**
Existing identity check token |
| data\[].**user\_token**
string
Conditionally returned | The user account holder on which the identity check was performed.
**Allowable Values:**
Existing user token |
| end\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| start\_index
integer
Conditionally returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"created_time": "2025-03-07T23:17:36Z",
"last_modified_time": "2025-03-07T23:17:36Z",
"token": "my_user_01_kyc_02",
"user_token": "my_user_01",
"result": {
"status": "success"
},
"manual_override": false
},
{
"created_time": "2025-03-08T18:00:00Z",
"last_modified_time": "2025-03-08T18:00:00Z",
"token": "my_user_01_kyc_01",
"user_token": "my_user_01",
"result": {
"status": "failure"
},
"manual_override": false
}
]
}
```
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 | Unique identifier of the KYC verification for which you want to retrieve the result.
**Allowable Values:**
Existing identity check token |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| business\_token
string
Conditionally returned | The business account holder on which the identity check was performed.
**Allowable Values:**
Existing business token |
| created\_time
datetime
Returned | Time when the KYC verification was performed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Time when the KYC verification was last updated.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| 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 an alternative KYC provider or directly with the account holder.
**Allowable Values:**
`true`, `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 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 identifier, that identifier is passed to you by way of this field in the response.
**Allowable Values:**
32 char max |
| result
object
Conditionally returned | Contains information about the KYC verification result.
**Allowable Values:**
Existing KYC verification object |
| result.**codes**
array of objects
Conditionally returned | An array of KYC verification result code objects.
**Allowable Values:**
One or more KYC verification result code objects |
| result.codes\[].**code**
string
Conditionally returned | For any `pending` or `failure` outcome, see the User KYC failure codes table, the Outcome reasons for the business table, or the Outcome reasons for individuals associated with a business table.
**Allowable Values:**
`AddressIssue`, `DateofBirthIssue`, `Denied KYC`, `NameIssue`, `NoRecordFound`, `OFACFailure`, `RiskIssue`, `SSNIssue`, `warm address alert` |
| result.codes\[].**message**
string
Conditionally returned | Result code description.
**Allowable Values:**
255 char max |
| result.**status**
string
Conditionally returned | KYC verification status.
**Allowable Values:**
`success`, `failure`, `pending` |
| token
string
Conditionally returned | The unique identifier of the identity check.
**Allowable Values:**
Existing identity check token |
| user\_token
string
Conditionally returned | The user account holder on which the identity check was performed.
**Allowable Values:**
Existing user token |
Sample response body
```json JSON lines wrap theme={null}
{
"created_time": "2025-03-07T22:52:39Z",
"last_modified_time": "2025-03-07T22:52:39Z",
"token": "my_user_01_kyc_01",
"user_token": "my_user_01",
"result": {
"status": "success"
},
"manual_override": false
}
```
## Related topics
- [About KYC Verification](/docs/developer-guides/about-kyc.md)
- [Businesses](/docs/core-api/businesses.md)
- [2023 Release Notes](/docs/developer-guides/release-notes-2023.md)
- [Users](/docs/core-api/users.md)
- [Account Holders Overview](/docs/developer-guides/account-holders-landing-page.md)