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 alice@example.com 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

Bash

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 '{\n    "items": [\
      {\
        "email": "alice@example.com",\
        "processor_tokens": ["processor-sandbox-new-token"]\
      }\
    ]\
  }'

Append multiple tokens to multiple emails

Bash

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 '{\n    "items": [\
      {\
        "email": "alice@example.com",\
        "processor_tokens": [\
          "processor-sandbox-alice-savings",\
          "processor-sandbox-alice-investment"\
        ]\
      },\
      {\
        "email": "bob@example.com",\
        "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

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

JSON

{
  "items": [\
    {\
      "email": "alice@example.com",\
      "processor_tokens": ["processor-sandbox-new-token-1"]\
    },\
    {\
      "email": "bob@example.com",\
      "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:

JSON

{
  "items": [\
    {\
      "email": "alice@example.com",\
      "processor_tokens": ["new-savings-token"]\
    }\
  ]
}

Response:

JSON

{
  "success_count": 1,
  "succeeded": [\
    {\
      "email": "alice@example.com",
      "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:

JSON

{
  "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 [].

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:

JSON

{
  "items": [\
    {\
      "email": "alice@example.com",\
      "processor_tokens": ["processor-sandbox-alice-savings"]\
    },\
    {\
      "email": "bob@example.com",\
      "processor_tokens": ["processor-sandbox-bob-savings"]\
    }\
  ]
}

Response:

JSON

{
  "success_count": 2,
  "succeeded": [\
    {\
      "email": "alice@example.com",
      "processor_tokens": ["processor-sandbox-alice-checking", "processor-sandbox-alice-savings"]\
    },\
    {\
      "email": "bob@example.com",
      "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:

JSON

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

Example: Tokens already associated

You try to append `