Appending Processor Tokens

What is this?

After users & processor tokens have been registered via POST /v2/invite-tokens, you might need to add more processor tokens to unclaimed emails or email + invite code pairs using Append processor tokens to an existing invite.

For example:

• You created an invite token for [email protected] with one Plaid processor token representing her checking account.
• Later, Alice links her savings account too. You now have a second processor token for her. Alice has not registered for Bloom+ yet.
• Instead of deleting and recreating the invite token, you use this endpoint to append the new processor token to Alice's existing invite.

This can be done for multiple emails at once — up to 100 emails in a single request.

Note: This endpoint only works for organizations that have processor tokens enabled. If your organization only uses invite codes (no processor tokens), this endpoint will return an error.

Quick start

Append one token to one email

curl -X PATCH https://<your-bloom-api-host>/v2/invite-tokens/processor-tokens \
  -H "Content-Type: application/json" \
  -H "x-partner: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "items": [
      {
        "email": "[email protected]",
        "processor_tokens": ["processor-sandbox-new-token"]
      }
    ]
  }'

Append multiple tokens to multiple emails

curl -X PATCH https://<your-bloom-api-host>/v2/invite-tokens/processor-tokens \
  -H "Content-Type: application/json" \
  -H "x-partner: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "items": [
      {
        "email": "[email protected]",
        "processor_tokens": [
          "processor-sandbox-alice-savings",
          "processor-sandbox-alice-investment"
        ]
      },
      {
        "email": "[email protected]",
        "processor_tokens": [
          "processor-sandbox-bob-savings"
        ]
      }
    ]
  }'

Replace <your-bloom-api-host> with the base URL provided by your Bloom representative. Replace the x-partner UUID with your actual organization ID.

Before you begin

1. You need existing invite tokens

This endpoint adds processor tokens to existing invite tokens. It does not create new invite tokens. If the email doesn't already have an invite token, the request will fail for that email.

To create invite tokens in the first place, use the batch create endpoint:

POST /v2/invite-tokens

See the Batch Invite Tokens documentation for details.

2. The invite token must be unused and not expired

You can only append processor tokens to invite tokens that:

• Have not been used yet (the user hasn't enrolled)
• Have not expired (the expiration date hasn't passed)

If the invite token has already been used or has expired, the request will fail for that email.

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

What's the difference between this endpoint and POST /v2/invite-tokens?

Bloom API call

PATCH /v2/invite-tokens/processor-tokens

Appends processor tokens to multiple existing invite tokens at once. Requires authentication via the x-partner header.

API reference: Append processor tokens to an existing invite

Headers

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

Request body

{
  "items": [
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-new-token-1"]
    },
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-new-token-2", "processor-sandbox-new-token-3"]
    }
  ]
}

Each item in the items array:

Example

Suppose Alice already has an invite token with one processor token (existing-checking-token), and you want to add a second one for her savings account.

Request:

{
  "items": [
    {
      "email": "[email protected]",
      "processor_tokens": ["new-savings-token"]
    }
  ]
}

Response:

{
  "success_count": 1,
  "succeeded": [
    {
      "email": "[email protected]",
      "processor_tokens": ["existing-checking-token", "new-savings-token"]
    }
  ],
  "failed": []
}

Notice that processor_tokens in the response includes all tokens — both the one Alice already had (existing-checking-token) and the one you just added (new-savings-token). You always get the full picture back.

That's it. You send the email and the new tokens, and you get back the complete list of everything that's now associated with that invite.

Response

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

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

Note: succeeded and failed are always JSON arrays, never null. If all items succeed, failed will be []. If all fail, succeeded will be [].

Note: The response preserves the order of the input. If you sent [alice, bob, charlie], the response items will be in the same order across both succeeded and failed.

Each item in succeeded:

Each item in failed:

After the request

Compare success_count against the number of items you sent — did they all go through?

Check the processor_tokens array in each succeeded item — it shows the full list of tokens after the append, so you can confirm the new ones were added.

Check failed for any items that didn't go through. Read the error field to understand why and fix accordingly.

Do not assume everything succeeded just because the HTTP status is 200. Always check both succeeded and failed.

Example: All succeed

You already created invite tokens for Alice and Bob with one processor token each. Now you're adding a second token to each.

Request:

{
  "items": [
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-alice-savings"]
    },
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-bob-savings"]
    }
  ]
}

Response:

{
  "success_count": 2,
  "succeeded": [
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-alice-checking", "processor-sandbox-alice-savings"]
    },
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-bob-checking", "processor-sandbox-bob-savings"]
    }
  ],
  "failed": []
}

Notice that processor_tokens in the response includes all tokens — both the original ones (*-checking) and the newly appended ones (*-savings).

Example: Partial success

Alice's append works, but Bob's fails because he doesn't have an invite token yet.

Response:

{
  "success_count": 1,
  "succeeded": [
    {
      "email": "[email protected]",
      "processor_tokens": ["processor-sandbox-alice-checking", "processor-sandbox-alice-savings"]
    }
  ],
  "failed": [
    {
      "email": "[email protected]",
      "error": "no unused, non-expired invite token found for email"
    }
  ]
}

Example: Tokens already associated

You try to append "tok-1" to Alice, but she already has "tok-1". This is not an error — it's a no-op. The response shows success and returns her full token list.

Request:

{
  "items": [
    {
      "email": "[email protected]",
      "processor_tokens": ["tok-1"]
    }
  ]
}

Response:

{
  "success_count": 1,
  "succeeded": [
    {
      "email": "[email protected]",
      "processor_tokens": ["tok-1", "tok-2"]
    }
  ],
  "failed": []
}

Alice already had tok-1 and tok-2. You tried to add tok-1 again. Nothing changed, and the response shows her full list.

Example: Processor token conflict

You try to append "tok-xyz" to Alice, but "tok-xyz" is already used by someone else (maybe in a different organization). Alice's entire item fails.

Response:

{
  "success_count": 0,
  "succeeded": [],
  "failed": [
    {
      "email": "[email protected]",
      "error": "processor tokens already in use: tok-xyz"
    }
  ]
}

If multiple tokens conflicted, all conflicting tokens are listed in the error message:

{
  "success_count": 0,
  "succeeded": [],
  "failed": [
    {
      "email": "[email protected]",
      "error": "processor tokens already in use: tok-xyz, tok-abc"
    }
  ]
}

Example: Capacity exceeded

Alice already has 23 processor tokens. You try to add 5 more, which would bring her total to 28 (over the limit of 25).

Response:

{
  "success_count": 0,
  "succeeded": [],
  "failed": [
    {
      "email": "[email protected]",
      "error": "cannot exceed 25 processor tokens per email (current: 23, adding: 5)"
    }
  ]
}

Important rules

Emails

• 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 are stripped before processing.
• No duplicate emails in the same request. Each email can only appear once. If you need to add tokens from two separate lists to the same email, combine them into one item.
• The email must already have an invite token. If you haven't created one yet via POST /v2/invite-tokens, this endpoint won't work for that email.

Processor tokens

• Whitespace is trimmed automatically. Leading and trailing spaces on processor tokens are stripped.
• Tokens are deduped within each email. If you accidentally send ["tok-1", "tok-1"] for one email, the duplicate is silently removed.
• No duplicate tokens across emails in the same request. If [email protected] and [email protected] both include "tok-xyz", the second email will fail. Each processor token can only appear under one email per request.
• Processor tokens are globally unique. A processor token can only be associated with one invite token in the entire system, across all organizations. If "tok-xyz" is already used by anyone (even in a different organization), it cannot be appended.
• Tokens already on this invite are skipped, not rejected. If you try to append "tok-1" to an email that already has "tok-1", we treat it as a no-op — the email is reported as succeeded, and the full list of tokens (including "tok-1") is returned.
• Max 25 processor tokens per email, total. This is the total count — existing tokens plus the new ones you're appending. If an email already has 20 tokens and you try to add 10 more, it will fail because 30 > 25.
• Max 500 total processor tokens per request. The total number of processor tokens across all items in a single request cannot exceed 500.
• Per-email all-or-nothing. If any processor token for an email conflicts (e.g. it's already used by someone else), the entire email is rejected — none of the tokens are added for that email. Fix or remove the conflicting token and retry the whole email.

Error reference

Per-item errors (inside failed)

These are errors for individual items. The request still returns HTTP 200 — the error is reported per item in the failed array. Other items in the same request may still succeed.

HTTP errors (the whole request fails)

These errors mean nothing was processed. The entire request is rejected.

Limits