> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or Preinitiate a Microdeposit
> Use this endpoint to create a microdeposit. To create a microdeposit include the `first_name`, `last_name`, `email`, `account_number`, `routing_number`, and `account_type` in the request body. The response will include the new microdeposit record with a status of `INITIATED`.
You can also use this endpoint to pre-initiate a microdeposit. If you want to preinitiate only include the `first_name`, `last_name`, and `email` in the request body. The response will include the new microdeposit record with a status of `PREINITIATED`.
Pre-initiating a microdeposit is optional. However, if you choose to implement this flow, it should be used for all Connect Widget sessions in verification mode.
Pre-initiating a microdeposit enables you to pass the end user's first name, last name, and email, if this data has already been collected. If the end user selects an institution which requires the microdeposit flow, the pre-initiated `micro_deposit` will be used and the Connect Widget step that normally requests this info from the end user will be skipped. However, if the end user selects an institution which supports IAV, the pre-initiated `micro_deposit` will be deleted and IAV will be used instead. When requesting a Connect Widget URL after pre-inititiating, make sure to set the `current_microdeposit_guid` to the resulting microdeposit's guid and set the mode to verification.
## OpenAPI
````yaml openapi/platform-api/v20111101.yaml POST /users/{user_guid}/micro_deposits
openapi: 3.0.0
info:
contact:
name: MX Platform API
url: https://www.mx.com/products/platform-api
description: >
The MX Platform API is a powerful, fully-featured API designed to make
aggregating and enhancing financial data easy and reliable. It can
seamlessly connect your app or website to tens of thousands of financial
institutions.
title: MX Platform API
version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: authorization
- name: widgets
- name: users
- name: members
- name: institutions
- name: accounts
- name: transactions
- name: microdeposits
- name: managed data
- name: transaction rules
- name: statements
- name: merchants
- name: categories
- name: insights
- name: investment holdings
- name: spending plan
- name: goals
- name: budgets
- name: monthly cash flow profile
- name: notifications
- name: taggings
- name: tags
- name: deprecated
- name: processor token
- name: verifiable credentials
- name: rewards
- name: ach return
paths:
/users/{user_guid}/micro_deposits:
post:
tags:
- microdeposits
summary: Create or pre-initiate a microdeposit
description: >
Use this endpoint to create or pre-initiate a microdeposit. The response
will include the new microdeposit record with a status of `INITIATED` or
`PREINITIATED` respectively.
To pre-initiate a microdeposit, you only need to set `email` (string),
`first_name` (string), and `last_name` (string) in the request body.
Pre-initiating a microdeposit allows you to pass the end user's first
name, last name, and email if this data has already been collected. If
the end user selects an institution which requires the microdeposit
flow, the pre-initiated `micro_deposit` will be used and the Connect
Widget step that normally requests this info from the end user will be
skipped. However, if the end user selects an institution which supports
IAV, the pre-initiated `micro_deposit` will be deleted and IAV will be
used instead. When requesting a Connect Widget URL after pre-initiating,
make sure to set the `current_microdeposit_guid` to the resulting
microdeposit's `guid` and set the `mode` to `verification`. If you use
this enhanced flow, a `micro_deposit` should be pre-initiated for all
connect sessions in verification mode. After pre-initiating a
microdeposit, pass the GUID to the config as `current_microdeposit_guid`
and set the `mode` to `verification` when requesting a Connect URL.
Pre-initiating a microdeposit is optional. If you choose to implement
this flow, it should be used for all Connect Widget sessions in
verification mode.
operationId: createMicrodeposit
parameters:
- $ref: '#/components/parameters/userGuid'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositRequestBody'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositResponseBody'
components:
parameters:
userGuid:
description: The unique identifier for a `user`, beginning with the prefix `USR-`.
example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
in: path
name: user_guid
required: true
schema:
type: string
schemas:
MicrodepositRequestBody:
properties:
micro_deposit:
$ref: '#/components/schemas/MicrodepositElements'
type: object
MicrodepositResponseBody:
properties:
micro_deposit:
items:
allOf:
- $ref: '#/components/schemas/MicrodepositElements'
- $ref: '#/components/schemas/MicrodepositResponse'
type: object
MicrodepositElements:
properties:
account_name:
example: My test account
type: string
account_number:
example: '3331261'
type: string
account_type:
example: CHECKING
type: string
email:
example: joshyboy2@example.com
type: string
first_name:
example: Joshy
type: string
last_name:
example: Grobanne
type: string
routing_number:
example: '091000019'
type: string
required:
- account_number
- account_type
- routing_number
MicrodepositResponse:
properties:
error_message:
example: null
nullable: true
type: string
guid:
type: string
example: MIC-09ba578e-8448-4f7f-89e1-b62ff2517edb
institution_code:
example: mxbank
type: string
institution_name:
example: MX Bank
type: string
status:
example: INITIATED
type: string
updated_at:
example: '2023-06-01T19:18:06Z'
type: string
verified_at:
example: null
nullable: true
type: string
type: object
securitySchemes:
basicAuth:
scheme: basic
type: http
````