Delivery Methods

The short version: you do not need to know anything about your recipient to generate a card.Recipient contact details are only required when you want Fluz to do the delivering. If you deliver the link yourself, you send us a card limit, an offer, and a funding account — nothing else. The recipient fills in their own details on the hosted page.

Pick your method

Do you want Fluz to deliver the link, or will you?

If you deliver it yourself — through your own email, your own SMS, in-app, in a portal, or by handing the URL to a downstream client — use GENERATE_URL. No recipient data required.

If Fluz delivers, how?

Email (EMAIL) or SMS (PHONE_NUMBER). You supply one address or number per card.

Do you already hold the recipient's full identity details?

If you do — and you want the recipient to skip data entry entirely — ask your Fluz rep about pre-filled enrollment. This is a gated option, not part of the standard generateVCShareLinks flow.

The four options at a glance

#	Option	`shareMethod`	What you send Fluz	Who delivers the link	What the recipient enters
1	Generate a link	`GENERATE_URL`	Nothing about the recipient	You	Their own details
2	Fluz emails it	`EMAIL`	One email address per card	Fluz	Their own details
3	Fluz texts it	`PHONE_NUMBER`	One phone number per card	Fluz	Their own details
4	Pre-filled enrollment	Gated — contact your rep	Full recipient identity details	You or Fluz	Nothing — they just claim

Options 1–3 are three values of the same shareMethod field on a single mutation. Switching between them is a one-line change — you are not integrating three different APIs.

Option 1 — Generate a link, you deliver it

Most partners want this one. You call the API, you get back an array of URLs, you do whatever you want with them: email them from your own system, text them, drop them into a customer portal, or hand them to a downstream client who distributes them to their own end users. Fluz sends nothing to anyone. We have no recipient contact details on file for these links, because you never gave us any.

Generate URLs

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 1,
    "daysUntilExpiration": 30,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Response

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1"
      ]
    }
  }
}

With GENERATE_URL, both recipientListEmail and recipientListPhone must be empty or omitted. Sending a recipient list alongside GENERATE_URL is a validation error and creates no records.

Set quantity above 1 to mint a batch in a single call. You get one distinct URL per unit, and each URL is claimable exactly once. Distribute the URLs exactly as returned — do not rewrite or re-shorten them.

Option 2 — Fluz emails the link

You supply one email address per card and Fluz sends the email. The recipient clicks through to the same hosted page as in Option 1 and enters their own details there. Use this when you already hold recipient emails and would rather not build delivery yourself.

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["mike.bennett@example.com", "dana.ruiz@example.com"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

recipientListEmail length must equal quantity. A mismatch returns a validation error and creates no records — no partial batches.

Option 3 — Fluz texts the link

Same as Option 2, over SMS. You supply one phone number per card in E.164 format. Fluz sends the SMS; Fluz does not also send an email on this path.

SMS

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": ["+12125550101", "+12125550102"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

recipientListPhone length must equal quantity, and both lists are mutually exclusive — send the one that matches your shareMethod and leave the other empty.

Option 4 — Pre-filled enrollment

Some partners want a white-glove experience where the recipient enters nothing at all. In that model you pass Fluz the identity details the card enrollment needs, and the recipient’s only action is opening the link and claiming the card. This is a gated option and is not part of the standard generateVCShareLinks input. If your program needs it, talk to your Fluz account team — it carries additional data-handling and compliance obligations on your side, since you are supplying personal information on behalf of a person who has not interacted with Fluz yet.

Choose this only if you genuinely hold verified recipient identity data. If you are tempted toward Option 4 simply to avoid asking recipients for information, Option 1 is almost certainly what you want instead.

What the recipient does

Identical across Options 1–3. The link is the same hosted page no matter who delivered it:

Open the link

No app download, no Fluz account, no password.

Verify by phone

A one-time code confirms the person holding the link.

Enter their card details

The recipient supplies the details the card needs. No PIN prompt occurs at this stage.

Claim, reveal, and spend

The card is funded from your spend account at claim time, not when the link was generated. The recipient becomes an authorized user of that one card object — nothing else on your account. The card is not auto-revealed on claim: revealing it prompts the recipient to enter their PIN, or create one if they haven’t set one yet.

See Recipient Experience for the full walkthrough and the states a recipient sees when a link is expired, revoked, or already claimed.

Common points of confusion

Do we have to pre-populate recipient information?

No. That is a common misreading of the API reference. Recipient fields exist so that Fluz can deliver on your behalf — they are not inputs to card issuance. With GENERATE_URL you send no recipient data at all.

Does an email address have to be in every request?

No. recipientListEmail is required only when shareMethod = EMAIL. With GENERATE_URL and PHONE_NUMBER it must be empty.

We pass the link to our client, who passes it to their end user. Does that work?

Yes — that is exactly the GENERATE_URL pattern. The URL is bearer-style: whoever opens it first and completes verification claims the card. Treat links as sensitive and deliver them over a channel you trust.

Can I generate a test link from the portal?

Not today. Link generation is API-only. Test against the staging environment with a staging token carrying the CREATE_SHARE_LINK scope — see Staging vs. Live Environment.

Can I switch methods later?

Yes. shareMethod is set per call, not per account. Nothing stops you from generating URLs for one batch and having Fluz email the next.

Requirements common to all methods

Requirement	Detail
Auth	Bearer access token with the `CREATE_SHARE_LINK` scope. Basic auth is rejected.
Funding	`userCashBalanceId` — a spend account on your own account. Effectively required despite being marked optional in the schema.
Offer	`offerId` must be an active offer whose merchant is shareable.
Expiration	`daysUntilExpiration` defaults to 30. This date is also the card’s freeze date.

Features

Delivery Methods

Pick your method

The four options at a glance

Option 1 — Generate a link, you deliver it

Option 2 — Fluz emails the link

Option 3 — Fluz texts the link

Option 4 — Pre-filled enrollment

What the recipient does

Common points of confusion

Requirements common to all methods

Next steps

Open Loop Cards Overview

Recipient Experience

​Pick your method

​The four options at a glance

​Option 1 — Generate a link, you deliver it

​Option 2 — Fluz emails the link

​Option 3 — Fluz texts the link

​Option 4 — Pre-filled enrollment

​What the recipient does

​Common points of confusion

​Requirements common to all methods

​Next steps

Open Loop Cards Overview

Recipient Experience

Pick your method

The four options at a glance

Option 1 — Generate a link, you deliver it

Option 2 — Fluz emails the link

Option 3 — Fluz texts the link

Option 4 — Pre-filled enrollment

What the recipient does

Common points of confusion

Requirements common to all methods

Next steps