ACTIVE.
Prerequisites
Before you implement onboarding, decide:- whether your integration is
SINGLE_USERorMULTI_USER - whether the current request is using partner HMAC authentication or a Meridian JWT bearer token
- Choose your integration model
- Authentication overview
- Server-to-server authentication with HMAC
- Client-server authentication with JWT
How Meridian Account onboarding works
Your integration is responsible for choosing the correct program for the customer. Once you create an access token in that program context, you can begin the enrollment orchestration for that customer. The Meridian user identity and the program enrollment are separate concerns. A customer may already have a MeridianuserId but still need a new enrollment in the program you selected for the current flow.
At a high level, the onboarding flow is:
1
Select the program
Determine which Meridian program the customer should be enrolled into. The
program defines the context in which the Meridian Account will exist.
2
Create an access token
Call
POST /v1/auth/token to create an access token for the customer in the
selected program context.3
Check the enrollment
Call
GET /v1/enrollment to determine whether the customer already has an
enrollment for that program.4
Activate enrollment when needed
If the returned enrollment status is
INACTIVE, call
POST /v1/enrollment/activate to activate or resume the enrollment for that
program.5
Complete the Information Request
Meridian creates an Information Request, which is a schema-driven
information collection system. Your integration should present and complete
the latest Information Request until it is ready for submission.
6
Wait for ACTIVE status
After the Information Request is submitted and approved, the enrollment
status moves to
ACTIVE and Meridian sends a webhook notification.Enrollment is the program-level record
Think of the enrollment as the record that connects a Meridian user to a specific program. The same customer may exist in your system independently of Meridian. A Meridian Account is not ready until that customer has an active enrollment in the target program.GET /v1/enrollment always returns the enrollment state for the current program context. If the status is INACTIVE, the customer still needs enrollment activation and/or onboarding completion before you can use the account.
First-time enrollment flow
Use this sequence for a customer who is entering the program for the first time:- Create an access token with
POST /v1/auth/token. - Call
GET /v1/enrollment. - If the enrollment status is
INACTIVE, callPOST /v1/enrollment/activate. - Read the returned enrollment state and
latestInformationRequestdetails. - Use the Information Request endpoints to collect the required customer information.
- Submit the Information Request for review.
- Listen for webhook updates until the enrollment becomes
ACTIVE.
INACTIVE with a latestInformationRequest while onboarding is still in progress. The enrollment exists, but the customer still has required information to complete before the account can be used.
Understanding the Information Request
In Meridian Accounts, an Information Request is the mechanism used to collect the information and documentation required to complete enrollment. The Information Request is schema-driven, which means your integration should use the structure returned by the API to determine:- which requirements to show
- which fields are required
- whether documents must be uploaded
- whether the Information Request is complete and ready to submit
Information Request lifecycle
Use the Information Request endpoints to drive onboarding from the current Meridian state instead of hardcoding your own form flow.1. Find the active Information Request
After you activate an enrollment, check the enrollment response forlatestInformationRequest. If the customer already has an in-progress onboarding flow, use that Information Request ID to continue from the existing state.
You can also call GET /v1/information-requests to list Information Requests in the current program context, then call GET /v1/information-requests/{informationRequestId} to load the full schema for the latest Information Request.
2. Render the Information Request from the schema
UseGET /v1/information-requests/{informationRequestId} to load the current Information Request definition.
The response holds a list of requirements. Each requirement carries:
requirementKey,title, anddescriptionto identify and label the sectioncardinalityto say whether it takes one entry or severaldataSchemato describe the fields to collectdocumentsto list the files to uploadentriesto hold the values and files collected so farvalidationStatusto show whether it isMISSING,INVALID, orVALID
Field labels
Each requirement’sdataSchema carries the label to show for every field, so you do not write your own. Use title as the field label and placeholder as the hint text.
3. Collect data and documents
Each requirement tells you what to collect in two parts. A requirement can have data, documents, or both.dataSchema: the values to collect in your UI. Meridian uses the JSON Schema standard for this definition. Send the values withPOST /v1/information-requests/{informationRequestId}/data.documents: the files to collect. Upload each file withPOST /v1/information-requests/{informationRequestId}/documents.
documents is a document slot. Use it to enforce Meridian’s file requirements:
documentKeyto identify the slotminFilesandmaxFilesfor the file countsupportedMimeTypesfor the allowed file typesmaxFileSizeBytesfor the maximum file sizemaxPdfPagesfor the maximum number of pages in a PDF
400. See Upload rules for the limits and error codes.
Treat the API response as the source of truth for collection behavior.
4. Handle single and repeated requirements
Each requirement’scardinality tells you how many entries it takes:
modeisSINGLEfor one entry, orMULTIPLEfor repeated entries, such as several beneficial ownersminandmaxset how many entries are allowed. Amaxofnullmeans there is no fixed upper limit
entries holds the entries collected so far. Each one has an entryId. Send that entryId when you update the entry or attach a file to it.
5. Save values and re-read validation
UsePOST /v1/information-requests/{informationRequestId}/data to save values as the customer progresses through onboarding. One call can write several entries.
requirementKeyfor the requirement being updatedentryIdfor the entry to update. Omit it to add a new entry to aMULTIPLErequirementclientReferenceId, which is optional, to match the entry to your own recordsdatafor the values, shaped by the requirement’sdataSchema
422 when the data fails the requirement’s validation, and 409 when the Information Request can no longer be edited, for example after you submit it.
After saving values or uploading files, read the updated Information Request response and use Meridian’s validation state to decide what happens next.
The API returns validationStatus at three levels:
- on the Information Request, to show whether it is complete
- on each requirement, to show whether that requirement is satisfied
- on each entry, to show whether its data and documents are valid
- which errors to show
- which sections still need attention
- whether the customer can continue
- whether the Information Request is ready to submit
6. Submit for review
When the Information Request is complete, callPOST /v1/information-requests/{informationRequestId}/submit to send it for review.
On submit, Meridian also checks the Information Request against existing data. It rejects a business whose legal name or tax number already belongs to another business, and reports the rejection in validationErrors.
A submitted Information Request does not mean the customer is fully onboarded yet. After submission, the Information Request may move through review before the enrollment becomes ACTIVE.
7. Wait for status updates
After submission, continue monitoring both enrollment and Information Request state. Your integration should:- consume
information_request_status_updatedwebhooks to detect review progress - consume
enrollment_status_updatedwebhooks to know when onboarding is complete - treat enrollment
ACTIVEas the final signal that the Meridian Account is ready to use
When the account is ready
The Meridian Account is ready for use only after the enrollment reachesACTIVE. Until then, the customer is still in onboarding even if Meridian has created the enrollment record.
Once the enrollment becomes ACTIVE:
- the required onboarding flow is complete
- Meridian sends an enrollment webhook
- your integration can treat the Meridian Account as ready for use
ACTIVE carries only the scopes needed for onboarding.
Recommended integration behavior
Your integration should:- store the program context used for onboarding
- treat enrollment status
INACTIVEas the condition for callingPOST /v1/enrollment/activate - drive the onboarding UI from the latest Information Request schema
- treat enrollment status
ACTIVEas the final ready-for-use signal, andINACTIVEas the activation or onboarding-in-progress state - wait for enrollment
ACTIVEbefore enabling account functionality - consume enrollment and Information Request webhooks so your system stays synchronized with Meridian state