Bring Your Own Token

About

Bloom allows organizations to register users ahead of time by creating invite tokens - codes given to users to make it even easier for them to enroll. Each invite token is tied to a single email address and can only be used once to import financial accounts into Bloom. A user can receive multiple invite tokens.

This same functionality can be achieved without giving the user an invite token. Processor tokens can be imported for users to link their financial accounts ahead of time without returning an invite token.

These options are not available by default, but can easily by enabled by a Bloom representative.

Your organization has two options for bring your own token:

• Processor Tokens Only — You provide a token from a supported connector (e.g. a Plaid processor token) alongside each email. Users then enroll by supplying their email and personal information in Bloom+. The processor token is used to automatically link the user's bank account.
• Invite Tokens - You provide a token from a supported connector (e.g. a Plaid processor token) alongside each email. Bloom generates a short code (like ABCD-EFGH-IJKL) for each token. You send the code to users. Users then enroll by supplying their email, token, and personal information in Bloom+. The processor token is used to automatically link the user's bank account.

The process is simple:

1. Get your organization set up with a Bloom representative for invite token generation.
2. Call the Bloom API's HTTP endpoint to generate invite tokens. You create invite tokens in batches (up to 100 at a time) using this endpoint.
3. Inform your users of their ability to register, either with invite code or without.

Before you begin

You need two things before you can use this endpoint:

1. Your organization ID (x-partner)

This is a UUID that identifies your organization, in UUID format. For example:

a1b2c3d4-e5f6-7890-abcd-ef1234567890

If you don't have your organization ID, reach out to your Bloom representative.

2. Know your organization's mode

Your org is configured in one of three modes. Your Bloom representative will tell you which one applies to you. The mode determines what you send in your requests and what you get back:

Bloom API call

To generate invite tokens in the Bloom database, call the Bloom API endpoint to Create invite tokens in batch for BYOT flow.

https://api.bloomplus.dev/v2/invite-tokens

Authentication

Check out the API Authentication page to learn how to retrieve and use an organization access token to authenticate your API requests.

Headers

If x-partner is missing, invalid, or doesn't match a known organization, you will get a 401 Unauthorized error.

Base URL

Use the following Base URL depending on the environment:

• Use the Development URL when testing or working in a development environment.
• Use the Production URL when making live requests.

Request body

Example (detailed examples in Behavior By Mode

{
  "expiration_days": 30,
  "tokens": [
    {
      "email": "[email protected]",
      "processor_tokens": ["proc-token-abc123"]
    },
    {
      "email": "[email protected]",
      "processor_tokens": ["proc-token-abc456", "proc-token-abc789"]
    }
  ]
}

Each item in the tokens array:

Important rules

• Emails are case-insensitive. [email protected] and [email protected] are treated as the same email.
• Whitespace is trimmed automatically. Leading and trailing spaces on emails and processor tokens are stripped before processing.
• No duplicate emails. Each email can only appear once in a single request.
• Duplicate processor tokens are deduped. If the same processor token appears more than once under a single email, duplicates are silently removed. However, the same token cannot appear across different emails in the same request.
• One active token per email per organization. If you already created a token for [email protected], creating another one will fail with a conflict error.
• Processor tokens are globally unique. A processor token can only be used once, even across different organizations.

Behavior by mode

Mode 1: Processor tokens only

Your send an email + a processor token for each user to the API. Users do not require an invite token. Once a user has been registered via the API, they input their email in Bloom+ to begin enrollment. After entering their information, their bank account is automatically linked.

A processor token is obtained from a supported connector. It gives Bloom permission to access the user's bank account data during onboarding. In these examples, we are using a Plaid processor token. Bloom's enablement services provides a document on generating these in lower environments for testing. The process for generating these tokens is the same when used in the context of Bloom invite tokens.

Request:

{
  "expiration_days": 30,
  "tokens": [
    { "email": "[email protected]", "processor_tokens": ["processor-sandbox-abc123"] },
    { "email": "[email protected]", "processor_tokens": ["processor-sandbox-xyz789"] }
  ]
}

Response:

{
  "success_count": 2,
  "succeeded": [
    { "email": "[email protected]", "processor_tokens": ["processor-sandbox-abc123"] },
    { "email": "[email protected]", "processor_tokens": ["processor-sandbox-xyz789"] }
  ],
  "failed": []
}

What to do next: Direct your users to the Bloom enrollment page. When they enter their email, Bloom will automatically find their processor token — no invite code needed. Their bank account is automatically linked via the processor token.

Mode 2: Invite Tokens

Your send an email + a processor token for each user to the API, and receive invite tokens for each user. Once a user has been registered via the API, they input their email and invite token in Bloom+ to begin enrollment. After entering their information, their bank account is automatically linked.

Request:

{
  "expiration_days": 14,
  "tokens": [
    { "email": "[email protected]", "processor_tokens": ["processor-sandbox-abc123"] }
  ]
}

Response:

{
  "success_count": 1,
  "succeeded": [
    {
      "email": "[email protected]",
      "invite_code": "YZAB-CDEF-GHIJ",
      "processor_tokens": ["processor-sandbox-abc123"]
    }
  ],
  "failed": []
}

What to do next: Send the user their invite code. When they enter it on the Bloom enrollment page, their bank account is also automatically linked via the processor token.

Bloom API Response

Every response has the same shape, regardless of how many tokens succeeded or failed:

{
  "success_count": 1,
  "succeeded": [ ... ],
  "failed": [ ... ]
}

Each item in succeeded:

Each item in failed:

Partial success

Important: a single request can have some tokens succeed and others fail. The HTTP status will still be 200 OK even if some tokens failed. Always check both arrays.

Example of partial success:

{
  "success_count": 1,
  "succeeded": [
    { "email": "[email protected]", "invite_code": "MNOP-QRST-UVWX" }
  ],
  "failed": [
    { "email": "[email protected]", "error": "email already has an active invite token" }
  ]
}

In this example, Bob's token was created, but Alice's failed because she already has one.

Error reference

Per-token errors (inside failed)

These are errors for individual tokens. The request still returns HTTP 200 — the error is reported per token in the failed array.

HTTP errors

When the API returns an HTTP error response, no tokens were created. The entire request is rejected. Processor tokens can be used again when calling the Bloom API since they were not ingested.

Limits