> ## 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. # Post Application > Submits a new financial-service account application to Marqeta Use the Applications API to start onboarding a cardholder into your White Label App (WLA) program. It's the only step in WLA onboarding that requires a call from you — once Marqeta approves an application, account and card setup happen automatically, with no additional requests on your end.

Submit an application

Send a POST request to `/applications` with the applicant's identity details to submit a new application. Authenticate with your API key credential over HTTP Basic auth; this endpoint requires WRITE authority. Marqeta screens the applicant against sanctions and politically exposed persons (PEP) lists for their region, then returns a `kyc_url` once the application reaches `KYC` status. Redirect the applicant to that URL to complete Know Your Customer (KYC) or Know Your Business (KYB) verification through a hosted webview that walks them through ID capture and a selfie. The `user` object is required and must include `id`, `name`, `email`, and `phone_number`. You can optionally include `national_id`, `address`, `shipping_address`, `tax_profile`, `financial_profile`, `terms`, and `device` to reduce how much information the applicant has to provide during KYC. The response includes `kyc_url` only if `status` is `KYC`. To retrieve a user's existing applications, see [Get Applications](/docs/core-api/white-label-app-get-applications/).

Application lifecycle

An application only moves forward through its lifecycle, never backward, with status changes only occurring from a perivous state to a subsequent state in the list. For example, an application can transition from `SUBMITTED` to `KYC` or `APPROVED`. Once a state is reached, it cannot move back to a previous state. | Status | Description | Final State | | -------------- | -------------------------------------------------------------- | ----------- | | SUBMITTED | Submitted and received by the banking partner. | No | | KYC | Know Your Customer (KYC) verification is in progress. | No | | MANUAL\_REVIEW | Under manual review by the banking partner's team. | No | | APPROVED | Approved. Marqeta can now create an account for the applicant. | Yes | | REJECTED | Rejected. Marqeta creates no account. | Yes | | EXPIRED | Expired. Marqeta creates no account. | Yes | Subscribe to the outbound application events below to track each status change instead of polling `/applications`.

Outbound application events

Marqeta sends application status-change events to your configured webhook endpoint. Every event payload includes `application_id` and `user_id`. The payload also includes `kyc_url` if the event type is `APPLICATION_KYC`. Some events are optional, which means that the you can opt to not send these. | Event type | Delivery | Notes | | --------------------------- | -------- | ----------------------- | | APPLICATION\_SUBMITTED | Optional | — | | APPLICATION\_KYC | Required | Might include `kyc_url` | | APPLICATION\_MANUAL\_REVIEW | Optional | — | | APPLICATION\_APPROVED | Required | Final status | | APPLICATION\_REJECTED | Required | Final status | | APPLICATION\_EXPIRED | Optional | Final status | Configure your webhook endpoint using the same webhook resources described in [Webhooks](/docs/core-api/webhooks/), including ping and retry behavior. ## OpenAPI ````yaml POST /applications openapi: 3.0.3 info: title: Application version: 0.1.0 termsOfService: /docs/terms-of-use description: > An **Application** represents a request for creating a financial service account. Marqeta is the source of truth for Application data. The calling platform submits an application on behalf of one of its users; Marqeta creates, advances, and terminates the application, and reports every status change back to the platform through Application event webhooks. The level of detail required in an application submission depends on the market and on the requirements of the underlying banking partner for the program. The platform collects the required user information through its own onboarding flow and submits it here. # Multi-program model Every request is scoped to a single **program**, identified by the `X-Marqeta-Program-Short-Code` header. The program determines the market, the KYC workflow, the banking partner, and the set of valid values for program-configured reference data such as `user.role` and `user.loyalty_tier`. A credential is authorized for one or more specific programs; a request for a program the caller is not authorized for is rejected with `401`. # Table of contents - [Create application endpoint](#tag/Application) - [Get user applications endpoint](#tag/Application) - [Application event](#tag/ApplicationEvent) servers: - url: https://sandbox-api.marqeta.com/v3 security: [] tags: - name: Application description: Endpoints for managing applications - name: ApplicationEvent description: Application event paths: /applications: post: tags: - Application summary: Create application description: > Submit a new financial service account application for a user. **Idempotency.** Applications are keyed on (`X-Marqeta-Program-Short-Code`, `user.id`). Re-submitting for a user who already has an application returns that application rather than creating a second one — a user has at most one application per program at a time. A retry that arrives while the original submission is still in flight returns `409`; retry it after a short delay. **Validation applied on first submission only.** The checks below run when the user record is created. A repeat submission for an existing user is not re-validated, and does not update the stored record. - `user.email` and `user.phone_number` must not already be linked to another user **within the same program**. - `user.phone_number` must match `^\+[1-9]\d{0,2}\d+$` and be at most 255 characters. `user.email` must be at most 255 characters. - Every entry in `terms` must have `accepted: true`. - `user.date_of_birth`, if present, must be a real calendar date. - `user.role` and `user.loyalty_tier`, if present, must be an active, valid combination for the program (see the schema notes on those fields). operationId: createApplication parameters: - $ref: '#/components/parameters/ProgramShortCode' requestBody: $ref: '#/components/requestBodies/CreateApplicationRequest' responses: '200': $ref: '#/components/responses/CreateApplicationResponse' '400': $ref: '#/components/responses/ErrorResponse' '401': description: >- Unauthorized — missing or invalid credential, or the credential is not authorized for the requested program. '409': $ref: '#/components/responses/ConflictResponse' '500': description: Internal Server Error security: - zionToken: [] components: parameters: ProgramShortCode: name: X-Marqeta-Program-Short-Code in: header required: true description: > Identifies the program this request belongs to. Every application, and every piece of program-configured reference data it refers to, is scoped by this value. A missing or empty value is rejected with `400`. A value the credential is not authorized for is rejected with `401`. schema: type: string maxLength: 50 example: ubpuk requestBodies: CreateApplicationRequest: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApplicationRequest' responses: CreateApplicationResponse: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/CreateApplicationResponse' ErrorResponse: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ConflictResponse: description: >- A submission for this user is already in progress. The original request is still being processed; retry after a short delay. `reason.code` is `APPLICATION_CONFLICT`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: CreateApplicationRequest: type: object required: - user properties: user: $ref: '#/components/schemas/User' national_id: $ref: '#/components/schemas/NationalId' address: $ref: '#/components/schemas/Address' shipping_address: $ref: '#/components/schemas/Address' tax_profile: $ref: '#/components/schemas/TaxProfile' terms: type: array items: $ref: '#/components/schemas/Term' device: $ref: '#/components/schemas/Device' options: $ref: '#/components/schemas/CreateApplicationOptions' financial_profile: $ref: '#/components/schemas/FinancialProfile' extras: type: object description: >- Map of additional program-specific information. See `Application.extras`. additionalProperties: type: string CreateApplicationResponse: type: object required: - id properties: id: type: string description: Marqeta-generated application ID. example: 16c4fb2d-3321-46b3-acf6-567ceba2d3fc status: $ref: '#/components/schemas/ApplicationStatus' kyc_url: type: string description: >- The webview URL for starting the KYC flow with the user. This must be present if the `status` value is `KYC`. example: >- https://kyc-provider.example.com/verify?code=8E13_EWEF5a9GuatLqwm5eD6kQRFloKKxIkHM14YiIbkrxpfSNft8 ErrorResponse: type: object required: - reason properties: reason: $ref: '#/components/schemas/Reason' extras: type: object description: >- Map of additional information that can be returned for investigation purposes. additionalProperties: type: string User: required: - id - first_name - last_name - email - phone_number type: object description: Information on the user that is applying for an account. properties: id: type: string description: >- The calling platform's own identifier for the user. Must be unique within the program. This value is echoed back in every Marqeta-emitted event for the application, and is the lookup key for `GET /applications`. example: >- 8E13_EWEF5a9GuatLqwm5eD6kQRFloKKxIkHM14YiIbkrxpfSNft8_-AyiMUmZHkd-zp7qrhiJITsCBlOeJ4db0NOfG5kas5QDcVR1cxU36EGwaxcgB0Qk4xgj-ViS-TMw== status: $ref: '#/components/schemas/UserStatus' gender: $ref: '#/components/schemas/Gender' first_name: type: string description: User's first name. example: John middle_name: type: string description: User's middle name. example: Garrett last_name: type: string description: User's last name. example: Doe email: type: string maxLength: 255 description: The user email address. Must be unique within the program. example: john@mail.com phone_number: type: string maxLength: 255 pattern: ^\+[1-9]\d{0,2}\d+$ description: >- The user phone number in E.164 form. Must be unique within the program. example: '+14155552671' date_of_birth: type: object description: User informed date of birth. properties: day: type: integer description: day portion of user's date of birth. example: 1 month: type: integer description: month portion of user's of birth. example: 1 year: type: integer description: year portion of user's date of birth. example: 1980 place_of_birth: type: object description: >- User informed birth place. **Not currently persisted or forwarded to the KYC provider** — accepted for forward compatibility only. properties: city: type: string description: city user was born in. example: San Francisco region: type: string description: region user was born in. example: CA country_iso2: $ref: '#/components/schemas/CountryCode' country_iso2: $ref: '#/components/schemas/UserCountryCode' role: $ref: '#/components/schemas/UserRole' loyalty_tier: $ref: '#/components/schemas/LoyaltyTier' signup_date: type: string description: > The date the user signed up for the calling platform. For programs whose KYC workflow includes a sole-trader / business check, this value is also submitted to the KYC provider as the date of incorporation. Do not send it for programs where that equivalence does not hold — confirm the mapping during program onboarding. format: date-time example: '2021-09-01T12:00:00Z' NationalId: required: - id - type - issuer_country_iso2 type: object description: Information about the user's national ID. properties: id: type: string description: >- The document number ID, with no formatting characters such as `.` and `-`. This value should not be present on `get` API calls. example: '419550000' type: $ref: '#/components/schemas/NationalIdType' issuer_country_iso2: $ref: '#/components/schemas/CountryCode' additional_national_ids: type: array items: $ref: '#/components/schemas/AdditionalNationalId' description: >- Additional national IDs that the user may have. This is an optional field and can be used to provide more information about the user's national IDs. Address: required: - address - city - postal_code type: object description: >- Information about the user's address. Note that depending on the country, some of the address components may not be available. properties: address: type: string description: The address first line, which can be a street name. example: Elm Street address2: type: string description: >- The address second line, which can be other additional address information. example: Mission District street_number: type: string description: The street number for the address. example: '5678' unit: type: string description: The unit for the address. example: 2A neighborhood: type: string description: The neighborhood name. example: Dolores Heights city: type: string description: The city name. example: San Francisco region: type: string description: The region / state / province location of the address. example: CA country_iso2: $ref: '#/components/schemas/CountryCode' postal_code: type: string description: The address postal code. example: '94110' TaxProfile: type: object description: Information about the user's tax profile. properties: entity_type: type: string description: The entity type of the user. enum: - INDIVIDUAL - ORGANIZATION organization_name: type: string description: >- The name of the organization, if the user's `entity_type` is `ORGANIZATION`. example: Acme Corp. jurisdiction_country_iso2: $ref: '#/components/schemas/CountryCode' tin: type: string description: Tax Identification Number (TIN) for the user. example: NL123456789B12 no_tin_reason: type: string description: >- Justification from the user for not having a TIN in cases that this information is required. citizenships: type: array items: $ref: '#/components/schemas/CountryCode' description: List of citizenships for the user. additional_tax_residencies: type: array items: $ref: '#/components/schemas/AdditionalTaxProfile' description: >- List of additional tax residencies for the user. This is an optional field and can be used to provide more information about the user's tax profile. Term: required: - name - accepted - accepted_on type: object description: >- A term the user was presented with. Every term submitted must have `accepted` set to `true`; a non-accepted term is rejected with `400`. properties: name: type: string accepted: type: boolean accepted_on: type: string format: date-time Device: required: - id type: object description: Information about the user device used to submit the application. properties: id: type: string description: >- The device ID, as generated by the calling platform, will be labeled `"unverified"` if it was not possible to provide the information. example: f3402095-26be-4d34-b263-ab665470295a model: type: string description: >- The device model, will be labeled `"unverified"` if it was not possible to provide the information. example: SM-A156U os_name: type: string description: >- The device operating system name, will be labeled `"unverified"` if it was not possible to provide the information. example: android os_version: type: string description: >- The device operating system version, will be labeled `"unverified"` if it was not possible to provide the information. example: '14' CreateApplicationOptions: type: object description: >- Options for application creation. **Not currently implemented** — any value supplied is ignored. properties: override_existing_account: type: boolean description: >- Indicates whether an existing account for the user should be overridden. FinancialProfile: type: object description: Information about the user's financial profile. properties: account_purpose: type: string description: The purpose of the account for the user. example: Business expenses source_of_funds: type: object description: The source of funds for the user. properties: funds_origin: type: string description: The origin of the funds for the user. example: Self-employment via online platforms primary_source: type: string description: The primary source of funds for the user. example: Revenue from self-employment ApplicationStatus: type: string description: > The status of the application. It can be used to determine the next steps in the application process. - "SUBMITTED" The application has been submitted and received. - "KYC" The application is in KYC (Know Your Customer) status. - "MANUAL_REVIEW" The application is under manual review. - "APPROVED" The application has been approved (final state). - "REJECTED" The application has been rejected (final state). - "EXPIRED" The application has expired (final state). Status changes only occur from a previous state to a subsequent state in the list. For example, an application can transition from `SUBMITTED` to `KYC` or `APPROVED`. Once a state is reached, it cannot move back to a previous state. Not every program produces every status — `MANUAL_REVIEW` and `EXPIRED` in particular depend on the program's KYC workflow and banking partner. Treat any status in this list as possible, and do not depend on a specific one being emitted. For asynchronous flows the initial state is `SUBMITTED`, and status changes are delivered to the platform via Application event webhooks. enum: - SUBMITTED - KYC - MANUAL_REVIEW - APPROVED - REJECTED - EXPIRED example: KYC Reason: type: object required: - code description: | Describes the reason why the operation was not successfully executed. The `reason` value should be present in all error responses and events. properties: code: type: string enum: - APPLICATION_ERROR - APPLICATION_CONFLICT - APPLICATION_DECLINED - APPLICATION_SUSPECTED_FRAUD - APPLICATION_CONFIRMED_FRAUD - APPLICATION_COMPLIANCE - APPLICATION_USER_REQUEST - APPLICATION_LOST_OR_STOLEN - APPLICATION_TERMS_OF_SERVICES_VIOLATION - CLIENT_ERROR - CLIENT_INVALID_ARGUMENT - CLIENT_INVALID_OPERATION - CLIENT_TOO_MANY_REQUESTS - SERVER_ERROR - SERVER_TIMEOUT - SERVER_NOT_IMPLEMENTED message: type: string description: >- Descriptive message that may help developers understand the issue. It should not be displayed to the end user directly. UserStatus: type: string description: The status of the user's account on the calling platform. enum: - ACTIVATED - DEACTIVATED Gender: type: string description: >- User informed gender. **Not currently persisted or forwarded to the KYC provider** — accepted for forward compatibility only. enum: - MALE - FEMALE - NON_BINARY - DECLINED - OTHER CountryCode: type: string description: >- The country two-letters identifier, as defined in the [ISO 3166 specification](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). minLength: 2 maxLength: 2 example: US UserCountryCode: type: string description: >- The user's country of residence, as an ISO 3166 two-letter code. **Not currently persisted or forwarded to the KYC provider** — the KYC submission uses `address.country_iso2`. minLength: 2 maxLength: 2 example: US UserRole: type: string maxLength: 255 description: > The user's role or segment on the calling platform, as a program-configured code. Values are **not fixed by this API**. Each program declares its own set of active role codes during program onboarding, and only those codes are accepted. A code that is not configured for the program is rejected. The role is not part of identity verification and is never submitted to the KYC provider. It is used together with `loyalty_tier` as a two-dimensional segmentation key to resolve the user's rewards entitlement and to filter the offers available to them. Programs with no rewards or offers component can omit it. example: DRIVER LoyaltyTier: type: string maxLength: 255 description: > The user's loyalty or rewards tier on the calling platform, as a program-configured code. Benefits are bound to the tier, so higher tiers typically carry more benefits. Values are **not fixed by this API**. Each program declares its own set of active, ranked tier codes during program onboarding, and only those codes are accepted. A code that is not configured for the program is rejected. The tier is not part of identity verification and is never submitted to the KYC provider. It is used together with `role` to resolve the user's rewards entitlement. Programs with no rewards component can omit it — omit the field entirely rather than sending a placeholder value. example: GOLD NationalIdType: type: string description: > The national ID document type. This enum is scoped to the markets currently supported; entering a new market requires adding its document type here. enum: - SSN - SIN - CPF - INE - CURP - NINO example: SSN AdditionalNationalId: required: - id - type - issuer_country_iso2 type: object description: Information about the user's national ID. properties: id: type: string description: >- The document number ID, with no formatting characters such as `.` and `-`. This value should not be present on `get` API calls. example: '419550000' type: $ref: '#/components/schemas/NationalIdType' issuer_country_iso2: $ref: '#/components/schemas/CountryCode' AdditionalTaxProfile: type: object description: Information about the user's tax profile. properties: jurisdiction_country_iso2: $ref: '#/components/schemas/CountryCode' tin: type: string description: Tax Identification Number (TIN) for the user. example: NL123456789B12 no_tin_reason: type: string description: >- Justification from the user for not having a TIN in cases that this information is required. securitySchemes: zionToken: type: http scheme: basic description: Token used to verify caller identity and authorize use of the service. ````