Possible Flows | Parallel Developer Documentation

Version: Current – v2.x

When a user clicks the Parallel Login button

When a user clicks the Parallel Login button, they will load https://app.parallelmarkets.com/ (via redirect or embedded iframe) to authenticate and might need to complete an accreditation or identity verification flow. As a partner, you can choose which flow(s) a user experiences after clicking the Parallel Login button by using the force_accreditation_check and force_identity_check parameters in your initial login() JS SDK call). Before starting any flow, all users will be asked for their consent to share any information they provide — based on the scopes you request — unless they've previously given consent. The post-consent flow options available to you, as a partner, are described below.

Enable Accreditation Check (Default)

If you need to determine whether an individual or business is accredited, you should enforce an accreditation check for users with an unknown accreditation status (e.g., new users or those with expired accreditations). By default, the force_accreditation_check parameter in your initial login() call in the JS SDK is set to true. When set to true, this option ensures that all users will be guided through the accreditation application process unless:

1. The user indicates they or their business is not accreditable (i.e., they cannot meet the required standards) or
2. They or their business are already accredited or
3. They or their business have a pending accreditation application

When Should You Use This?

Enable this flow if you want to grant access solely to accredited users, such as for 506(c) Offerings. In these situations, you'd want to ascertain a user's accreditation status promptly. All new users (and any others with unknown accreditation status) should then complete an accreditation flow before being redirected back to you.

Skip Accreditation Check

If you only want to authenticate a user and gain permission to access their profile, set force_accreditation_check=false. Every user will still be prompted to share information with you (unless they have already consented). However, they won't enter an accreditation flow, even if their current accreditation status is unknown. The user might already have existing accreditations, which you can access once they grant consent.

When Should You Use This?

This flow is ideal if you're not concerned about accreditation status and only want a streamlined login for Parallel Markets users. If required in the future, you can later send the user back to Parallel Markets, enforcing an accreditation check to determine their status.

Enable Identity Check (Default)

If you need to verify the identity details of a user, make sure to enforce an identity check for those without current identity information (e.g., new users or those who provided details long ago). By default, the force_identity_check parameter in your initial login() call in the JS SDK is set to true. When set to true, this option ensures that all users will enter the identity verification flow unless:

1. The user has already provided identity details that have not expired or
2. They need to meet additional flow requirements due to an identity_claim_override_id you've specified

When Should You Use This?

Enable this flow if you want to allow access only to users who have provided their identity details, perhaps to adhere to CIP KYC/AML regulations. In such scenarios, you'd want to review a user's identity details immediately. Users new to the system (and those without recent identity info) should be directed to an identity verification flow before being redirected back to you.

Skip Identity Check

If you only want to authenticate the user and gain permission to view their profile, set force_identity_check=false. Every user will still be prompted to share information with you (unless they have already consented). However, they won't enter an identity verification flow. Some users might have previously provided identity details, which you can access once they grant consent.

When Should You Use This?

This flow is ideal if you're not focused on identity verification specifics and only want a streamlined login for Parallel Markets users. If required in the future, you can later send the user back to Parallel Markets, enforcing an identity check to collect their details.

Mixing Flows

You can direct a user through any combination of the described flows. For instance, some of you might choose not to enforce an accreditation check during login. You'd still receive user data if it's available (e.g., past or present accreditation or if a user claims they don't meet accreditation standards) — but they won't be required to complete an accreditation flow if that information is yet unknown. Later on, if a user expresses an interest in investing, you can:

1. Immediately approve the investment if they have current accreditation or
2. Redirect them through a mandatory accreditation check if their status is unknown

This staged, incremental approach is supported, and it's entirely up to you how to use it.

Using an External Identifier

Individuals or businesses that complete the Parallel flow will end up as records within the Case Management system - these records support an external_id that can be set with a custom value. This is useful when you want to identify a Parallel record with a unique ID from one of your systems, for example, an identifier from a CRM or your own database.

To set an external_id, provide the external_id parameter in your initial login() call in the JS SDK.

If an external_id is provided:

• An expected_entity_type parameter must be provided in the login() call.
• If an expected_entity_type of self is provided, a first_name and last_name must be provided in the login() call.
• If an expected_entity_type of a business type is provided, an expected_business_name must be provided in the login() call.
  • In this case, a confirmation screen will be presented to the user to ensure they can provide information for the expected entity.

This external_id value will be associated with the created record once the subject authenticates and grants consent to share their information with you.

When Should You Use This?

Using an external identifier is useful when you want to map an existing unique identifier from your own system to a Parallel record to make syncing Parallel updates in your database, or querying the Parallel API, simpler.

Starting a Flow For a Specific Record

In cases where you want to initiate a flow for a particular record in your case management instance, you can pass the required_entity_id parameter in your initial login() call in the JS SDK.

The required_entity_id must be the unique Parallel ID for a particular individual or business record within your Case Management instance.

If an required_entity_id is provided:

• The user completing the flow must match the individual record, or be associated with the business record:
  • For an individual record, the verified email address of the user completing the flow must match the email address associated with the record. To support this, ensure you pass the email attribute to the login() function with the email associated with the record.
  • For a business record, the user must have an admin or a controller role at the matching business in the Parallel system.
• If the above conditions are met, a confirmation screen will be presented to the user to ensure they can provide information for the expected entity.
• Certain pieces of information will be prefilled during the flow with information from the associated record (e.g. first name, last name, address and date of birth for identity flows).

Fields Pre-filled by Scope

When using required_entity_id, fields are pre-filled based on the scopes requested and the data available on the record:

Identity Scope (scope: 'identity')

Accreditation Scope (scope: 'accreditation_status')

Profile Scope (scope: 'profile')

Confirmation Screen

The following screen is what users will see in relevant cases when Using an External ID or Starting a Flow For a Specific Record.

For an individual

For a business

• If the user is able to provide information for the expected entity, the flow will continue.
• If the user is unable to provide information for the expected entity, this will result in a redirect to the redirect_uri with an invalid_entity error. E.g. https://parallelbank.com/onboarding?error=invalid_entity

Pre-filling User Data

If you collect user information before initiating the IDS verification flow, you can pre-fill that data to reduce duplicate entry. There are two approaches depending on how much data you have.

Option A: Basic Pre-fill via SDK

For basic information (name and email only), pass these directly to login():

Parallel.login({
  first_name: 'Jane',
  last_name: 'Smith',
  email: 'jane.smith@example.com',
})

When all three values are provided, users skip the initial signup form and go directly to email confirmation.

Limitations: Only first_name, last_name, and email are supported. Other fields (address, phone, DOB, etc.) cannot be passed this way.

Option B: Pre-create Records via API (Recommended)

For extensive data collection, use the "profile-first" pattern:

1. Create a record via API with your collected data
2. Initiate the SDK flow with required_entity_id pointing to that record
3. User completes flow with data pre-filled

Step 1: Create the Record

Call the Records API to create an individual or business record with your collected data:

POST https://api.parallelmarkets.com/v2/partner-records/individuals
Authorization: Bearer {your_api_key}
Content-Type: application/json
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+12125551234",
  "birth_date": "1985-03-15",
  "residence_location": {
    "address_one": "123 Main St",
    "address_two": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "external_id": "your_internal_user_id_123"
}

The API returns the created record with its Parallel ID:

{
  "data": {
    "id": "UG9kVXNlclJlY29yZDoxNzM=",
    "type": "individual",
    "external_id": "your_internal_user_id_123",
    "..."
  }
}

For business records, you can also include beneficial_owners, control_persons, and primary_contact. See the Records API documentation for all supported fields.

Step 2: Initiate SDK with required_entity_id

Pass the Parallel record ID and matching email to login():

Parallel.login({
  email: 'jane.smith@example.com',
  required_entity_id: 'UG9kVXNlclJlY29yZDoxNzM=',
})

Caution: The email passed to login() must match the email on the record. If they don't match, the user will see an invalid_entity error.

Step 3: User Completes Flow

When the overlay opens:

1. User sees a confirmation screen showing they're providing information for the expected individual/business
2. Data from the record (name, address, DOB) is pre-filled in subsequent screens
3. User confirms or updates the information and completes verification

Which Fields Are Pre-filled?

When using required_entity_id, the following fields are pre-filled from the record:

Info: Pre-filled fields are editable by the user. There is no mechanism to lock fields as read-only. Users must actively confirm the information as part of the attestation process for compliance purposes.

Workflow Diagram

Parallel BackendYour Site w/ Parallel JSYour Site collects user data (name, address, DOB, etc.)User clicks "Verify"✔ Pre-filled flow completeUserPOST /v2/partner-records/individualsCreate recordReturns Parallel record IDClick "Verify"Parallel.login({ email, required_entity_id })Show confirmation screen with record data pre-filledConfirm info & complete verificationauth.login event (status: 'connected')getProfile()Verified profile dataUser