Skip to main content
A Meridian Account always exists within the context of a program. In Meridian, that program relationship is represented by an enrollment. Before your customer can use a Meridian Account, you must enroll them into the correct program, collect any required information, and wait for the enrollment to become ACTIVE.

Prerequisites

Before you implement onboarding, decide:
  • whether your integration is SINGLE_USER or MULTI_USER
  • whether the current request is using partner HMAC authentication or a Meridian JWT bearer token
Those choices determine how the target user is identified before enrollment starts. Review:

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 Meridian userId 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:
  1. Create an access token with POST /v1/auth/token.
  2. Call GET /v1/enrollment.
  3. If the enrollment status is INACTIVE, call POST /v1/enrollment/activate.
  4. Read the returned enrollment state and latestInformationRequest details.
  5. Use the Information Request endpoints to collect the required customer information.
  6. Submit the Information Request for review.
  7. Listen for webhook updates until the enrollment becomes ACTIVE.
A newly activated enrollment is typically returned as 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
Depending on the enrollment requirements, the Information Request may ask for business details, controller details, beneficial ownership information, or supporting documents. For a walkthrough of what Meridian collects and how to prepare it, see Information we collect.

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 for latestInformationRequest. 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

Use GET /v1/information-requests/{informationRequestId} to load the current Information Request definition. The response holds a list of requirements. Each requirement carries:
  • requirementKey, title, and description to identify and label the section
  • cardinality to say whether it takes one entry or several
  • dataSchema to describe the fields to collect
  • documents to list the files to upload
  • entries to hold the values and files collected so far
  • validationStatus to show whether it is MISSING, INVALID, or VALID
Do not assume every customer sees the same requirements or the same fields. Render the onboarding flow from the returned schema.

Field labels

Each requirement’s dataSchema 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.
Show the labels as returned, so your screens match what Meridian asks for.

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 with POST /v1/information-requests/{informationRequestId}/data.
  • documents: the files to collect. Upload each file with POST /v1/information-requests/{informationRequestId}/documents.
Each entry in documents is a document slot. Use it to enforce Meridian’s file requirements:
  • documentKey to identify the slot
  • minFiles and maxFiles for the file count
  • supportedMimeTypes for the allowed file types
  • maxFileSizeBytes for the maximum file size
  • maxPdfPages for the maximum number of pages in a PDF
Meridian checks the page limit when you upload. Meridian rejects a PDF over the limit, or one that needs a password to open, with a 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’s cardinality tells you how many entries it takes:
  • mode is SINGLE for one entry, or MULTIPLE for repeated entries, such as several beneficial owners
  • min and max set how many entries are allowed. A max of null means 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

Use POST /v1/information-requests/{informationRequestId}/data to save values as the customer progresses through onboarding. One call can write several entries.
Each entry identifies:
  • requirementKey for the requirement being updated
  • entryId for the entry to update. Omit it to add a new entry to a MULTIPLE requirement
  • clientReferenceId, which is optional, to match the entry to your own records
  • data for the values, shaped by the requirement’s dataSchema
Meridian returns 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
Use these validation states to decide:
  • which errors to show
  • which sections still need attention
  • whether the customer can continue
  • whether the Information Request is ready to submit
Do not decide completeness from local form rules alone. Use the validation returned by Meridian as the source of truth.

6. Submit for review

When the Information Request is complete, call POST /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.
In Sandbox, use a new legal name and tax number for each test business. A duplicate that reaches activation leaves the enrollment INACTIVE with the status reason ACTIVATION_REJECTED, even when the Information Request is approved.
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_updated webhooks to detect review progress
  • consume enrollment_status_updated webhooks to know when onboarding is complete
  • treat enrollment ACTIVE as the final signal that the Meridian Account is ready to use
If your system needs to recover state after a webhook delivery issue, reload the enrollment and latest Information Request from the API and continue from the latest returned state.

When the account is ready

The Meridian Account is ready for use only after the enrollment reaches ACTIVE. 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
Mint a new access token before you call the account, beneficiary, or transaction endpoints. A token issued before the enrollment was ACTIVE carries only the scopes needed for onboarding. Your integration should:
  • store the program context used for onboarding
  • treat enrollment status INACTIVE as the condition for calling POST /v1/enrollment/activate
  • drive the onboarding UI from the latest Information Request schema
  • treat enrollment status ACTIVE as the final ready-for-use signal, and INACTIVE as the activation or onboarding-in-progress state
  • wait for enrollment ACTIVE before enabling account functionality
  • consume enrollment and Information Request webhooks so your system stays synchronized with Meridian state

Next steps

After implementing this flow, review: