> ## 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. # Get Applications > Retrieves a user's existing financial-service account applications Use this endpoint to check whether a user already has an application in progress or has already been onboarded, before you start a new White Label App (WLA) onboarding flow. Send a GET request to `/applications` with the user's ID; the response includes every application submitted for that user, ordered by `created_on` in ascending order. Reasons to call this endpoint include: * **Resuming an interrupted signup:** Check for an existing application in the `KYC` status before redirecting the applicant to start over, then reuse the `kyc_url` from that application instead of submitting a duplicate. * **Displaying application status in your app:** Poll this endpoint to show the applicant where they stand, as a fallback for cases where you cannot process outbound application events. * **Preventing duplicate submissions:** Check for any non-final application (`SUBMITTED`, `KYC`, or `MANUAL_REVIEW`) for the user before you submit a new one. Set `active_only` to `false` if you also need to see applications in a final status, such as `APPROVED`, `REJECTED`, or `EXPIRED`. If the specified user has no applications, the response returns an empty `applications` array rather than an error. If the user has more applications than fit in a single page, use the `next_cursor` value from the response as the `cursor` parameter in your next request to page through the rest. ## OpenAPI ````yaml GET /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: get: tags: - Application summary: Get user applications description: > Get existing applications for a given user within the program. The results are ordered by the `created_on` field in ascending order. If no items are found for the user, an **empty array** is returned. Note that a user has at most one application per program, so this endpoint returns either zero or one item. > This endpoint is not side-effect free. For an application in `KYC` or > `SUBMITTED` status it re-reads the KYC workflow and refreshes > `kyc_url`, and it may advance the application to `MANUAL_REVIEW` if > the KYC provider reports the case as pending. This is intentional — > it is the supported way to reconcile an application whose status may > have drifted. operationId: getUserApplications parameters: - $ref: '#/components/parameters/ProgramShortCode' - name: user_id in: query description: The platform's own user ID, as supplied in `user.id` on submission. required: true schema: type: string - in: query name: active_only description: > Indicate if only active applications should be returned. An active application is one that has a status **other than** `APPROVED`, `REJECTED`, or `EXPIRED`. required: false schema: type: boolean default: true - in: query name: limit description: >- Maximum number of items to return. If not present, no limit should be applied. required: false schema: type: integer minimum: 1 maximum: 100 - in: query name: cursor description: >- Cursor to a specific position in the results. If not present, the first page should be returned. required: false schema: type: string example: eyJpZCI6IjEyMyJ9 responses: '200': $ref: '#/components/responses/GetUserApplicationsResponse' '400': $ref: '#/components/responses/ErrorResponse' '401': description: >- Unauthorized — missing or invalid credential, or the credential is not authorized for the requested program. '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 responses: GetUserApplicationsResponse: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/GetUserApplicationsResponse' ErrorResponse: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: GetUserApplicationsResponse: type: object required: - applications properties: applications: description: The list of applications for the user. type: array minItems: 0 items: $ref: '#/components/schemas/Application' next_cursor: type: string description: Cursor to fetch the next results. example: eyJpZCI6IjEyMyJ9 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 Application: type: object required: - id - status - user - created_on - updated_on properties: id: type: string description: Marqeta-generated application ID. status: $ref: '#/components/schemas/ApplicationStatus' kyc_url: description: >- The webview URL for starting the KYC flow with the user. Must be present if `status` is `KYC`. type: string example: >- https://kyc-provider.example.com/verify?code=8E13_EWEF5a9GuatLqwm5eD6kQRFloKKxIkHM14YiIbkrxpfSNft8 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' financial_profile: $ref: '#/components/schemas/FinancialProfile' terms: type: array items: $ref: '#/components/schemas/Term' device: $ref: '#/components/schemas/Device' created_on: type: string format: date-time example: '2021-09-01T12:00:00Z' updated_on: type: string format: date-time example: '2021-09-01T12:00:00Z' extras: type: object description: > Map of additional program-specific information. This is the extension point for attributes that only one program needs. Prefer adding a key here over widening a shared schema or enum. Keys in use for a program are agreed during program onboarding. additionalProperties: type: string 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. 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 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. 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 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' 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. ````