Onboarding your customer

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:

• 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 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:

​

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 steps 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.

​

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 is organized into steps and requirements. Use that response to determine:

• which sections to show
• which fields belong to each section
• whether a requirement has a single entry or repeated entries
• how each field must be collected
• whether each step, requirement, or field is currently MISSING, INVALID, or VALID

Do not assume every customer sees the same fields or the same number of steps. Render the onboarding flow from the returned schema.

​

3. Use the two collection modes

Each Information Request item tells you how Meridian expects that field to be collected by using collectionMode. The two collection modes are:

• DIRECT_INPUT: collect a value directly in your UI and send it with PATCH /v1/information-requests/{informationRequestId}
• FILE_UPLOAD: collect one or more files and upload them with POST /v1/information-requests/{informationRequestId}/file-uploads

For DIRECT_INPUT items, use the directInput schema on the item to understand the expected value shape. Meridian uses the JSON Schema standard for this definition. A direct-input item may represent a single value, or a structured object whose data fields you must collect together. For FILE_UPLOAD items, use the fileUpload configuration on the item to enforce Meridian’s file requirements, including:

• minimum and maximum file count
• allowed MIME types
• allowed file extensions
• maximum file size

Treat the API response as the source of truth for collection behavior. If an item is marked DIRECT_INPUT, do not treat it as a document upload. If it is marked FILE_UPLOAD, do not try to satisfy it with a text field.

​

4. Handle single and repeated requirements

Each requirement also tells you whether it is SINGLE or MULTIPLE.

• SINGLE means the requirement has one set of values
• MULTIPLE means the customer may need to provide repeated entries, such as multiple beneficial owners

For MULTIPLE requirements, use the metadata returned by the API to guide the experience:

• addInstanceLabel to label the add action
• instanceHeaderPrefix to label each repeated entry
• minInstanceCount and maxInstanceCount to control how many entries are allowed
• instances to render the values already collected

When updating a repeated requirement, include instanceIndex in each patch item so Meridian can associate the value with the correct entry.

​

5. Save values and re-read validation

Use PATCH /v1/information-requests/{informationRequestId} to save direct-input values as the customer progresses through onboarding. Each patch item identifies:

• requirementKey for the requirement being updated
• itemKey for the specific field
• value for the field value
• instanceIndex when the requirement supports multiple entries

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 guides valid collection in three ways:

• step-level validationStatus shows whether the section is complete
• requirement-level validationStatus shows whether that requirement is satisfied
• field-level validation on current values shows whether an individual value is missing, invalid, or 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. 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

​

Recommended integration behavior

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:

• Getting started
• Choose your integration model
• Authentication overview
• API reference overview
• Webhooks overview
• Enrollment webhooks
• Information Request webhooks