Bring Your Own Token

About

Your organization has two options for Bring Your Own Token:

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

The BYOT Process:

1. Receive Organization environment credentials for BYOT.
2. Authenticate into your Organization's environment.
3. Call the Bloom API's endpoint to register your users. You create invite tokens in batches (up to 500 at a time) using this endpoint.
4. Inform your users of their ability to register, either with an invite code or without.

To 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. 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 organization is configured in one of two modes. The mode determines what you send in your requests and what you get back:

BYOT Workflow

Base URL

Use the following base URL depending on your environment:

Sandbox processor tokens (e.g. processor-sandbox-...) must be used with the sandbox base URL. Production processor tokens must be used with the production base URL.

Authentication

This endpoint uses an organization access token passed as a bearer token in the Authorization header.

Headers

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

Endpoint

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

Request body

Example (detailed examples in Behavior By Mode):

JSON

{
  "expiration_days": 30,
  "tokens": [
    {
      "email": "user1@example.com",
      "processor_tokens": ["proc-token-abc123"]
    },
    {
      "email": "user2@example.com",
      "processor_tokens": ["proc-token-abc456", "proc-token-abc789"]
    }
  ]
}

Each item in the tokens array:

Important rules

• Emails are NOT case sensitive. User@Example.com and user@example.com 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. The same token cannot appear across different emails in the same request.
• One active invite token per email per organization. If an invite token already exists for an email that hasn't expired yet, creating another 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

You send an email and a processor token for each user. Users do not receive an invite code. Once registered via the API, users enter their email in Bloom+ to begin enrollment. Their bank account is automatically linked via the processor token.

A processor token is obtained from a supported financial connector. It gives Bloom permission to access the user's bank account data during onboarding. These examples use a Plaid processor token. See Plaid's documentation for how to generate processor tokens. The process is the same when used in the context of Bloom invite tokens.

Request:

JSON

{
  "expiration_days": 30,
  "tokens": [
    { "email": "alice@example.com", "processor_tokens": ["processor-sandbox-abc123"] },
    { "email": "bob@example.com", "processor_tokens": ["processor-sandbox-xyz789"] }
  ]
}

Response:

JSON

{
  "success_count": 2,
  "succeeded": [
    { "email": "alice@example.com", "processor_tokens": ["processor-sandbox-abc123"] },
    { "email": "bob@example.com", "processor_tokens": ["processor-sandbox-xyz789"] }
  ],
  "failed": []
}

What to do next: Direct users to the Bloom enrollment page at app.bloomplus.com/[organizationslug]. When they enter their email, Bloom automatically finds their processor token. No invite code is needed. Their bank account is linked automatically.

Mode 2: Invite Tokens

You send an email and a processor token for each user and receive an invite code per user. Once registered via the API, users enter their email and invite code in Bloom+ to begin enrollment. Their bank account is automatically linked via the processor token.

Request:

JSON

{
  "expiration_days": 14,
  "tokens": [
    { "email": "alice@example.com", "processor_tokens": ["processor-sandbox-abc123"] }
  ]
}

Response:

JSON

{
  "success_count": 1,
  "succeeded": [
    {
      "email": "alice@example.com",
      "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 at app.bloomplus.com/[organizationslug], their bank account is linked automatically via the processor token.

Bloom API Response

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

JSON

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

Each item in succeeded:

Each item in failed:

Partial Success

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 the succeeded and failed arrays.

Example:

JSON

{
  "success_count": 1,
  "succeeded": [
    { "email": "bob@example.com", "invite_code": "MNOP-QRST-UVWX", "processor_tokens": ["processor-sandbox-xyz789"] }
  ],
  "failed": [
    { "email": "alice@example.com", "error": "email already has an active token" }
  ]
}

Bob's token was created. Alice's failed because she already has an active token that hasn't expired yet.

Error reference

Per-token Errors (inside failed)

These errors apply to 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, no tokens were created and the entire request is rejected. Processor tokens that were not ingested can be reused in a subsequent call.

Limits

What's next

Appending processor tokens — add additional bank accounts to a user who has already enrolled and received an invite code.