> ## Documentation Index > Fetch the complete documentation index at: https://docs.mnai.com/llms.txt > Use this file to discover all available pages before exploring further. # Onboarding your customer > Enroll customers into a program, complete required onboarding steps, and activate their Meridian Account. 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](/products/meridian-accounts/guides/choose-your-integration-model) * [Authentication overview](/products/meridian-accounts/guides/authentication-overview) * [Server-to-server authentication with HMAC](/products/meridian-accounts/guides/server-to-server-authentication-with-hmac) * [Client-server authentication with JWT](/products/meridian-accounts/guides/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: Determine which Meridian program the customer should be enrolled into. The program defines the context in which the Meridian Account will exist. Call `POST /v1/auth/token` to create an access token for the customer in the selected program context. Call `GET /v1/enrollment` to determine whether the customer already has an enrollment for that program. If the returned enrollment status is `INACTIVE`, call `POST /v1/enrollment/activate` to activate or resume the enrollment for that program. 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. 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 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](/products/meridian-accounts/guides/getting-started) * [Choose your integration model](/products/meridian-accounts/guides/choose-your-integration-model) * [Authentication overview](/products/meridian-accounts/guides/authentication-overview) * [API reference overview](/products/meridian-accounts/api-reference) * [Webhooks overview](/products/meridian-accounts/webhooks) * [Enrollment webhooks](/products/meridian-accounts/webhooks/webhooks-enrollment) * [Information Request webhooks](/products/meridian-accounts/webhooks/webhooks-information-request)