Generate Share Links

Generate hosted virtual card links (“open-loop” Send Cards) from your platform. You call one API to create one or more links, then deliver those links to recipients by email, by SMS, or through your own distribution flow. When a recipient opens the link, they land on a Fluz-hosted activation page, verify themselves, and claim a single-load virtual card funded from your account.

Prerequisites: a Bearer access token carrying the CREATE_SHARE_LINK scope, and an account with hosted virtual card sending enabled. If your account isn’t enabled, the API returns a permissions error directing you to your Fluz representative.

What “hosted” / “open-loop” means. A hosted link points to a Fluz-hosted activation page. Open-loop means the recipient claims a network virtual card that can be used at eligible merchants, subject to your program rules.

Looking for the full feature narrative — recipient walkthrough, program rules, and the complete status/error reference? See the Send Cards overview. This page is the focused API reference for the three share-link operations.

How it works

Your platform calls generateVCShareLinks with the offer, card limit, quantity, funding source, and delivery method.
Fluz creates one share request and one hosted URL for each requested link.
Delivery depends on shareMethod:
- GENERATE_URL: Fluz returns the hosted URLs in the API response, and you distribute them yourself.
- EMAIL: Fluz emails each recipient their link.
- PHONE_NUMBER: Fluz texts each recipient their link.
The recipient opens the hosted link, signs in, completes verification, and claims the card.
Fluz issues a single-load virtual card to the recipient, funded from the sender’s account.

Authentication

All Send Cards share-link operations use the Fluz GraphQL API.

POST https://<your-fluz-api-host>/api/v1/graphql
Authorization: Bearer <access_token>
Content-Type: application/json

Your access token must include the CREATE_SHARE_LINK scope.

{
  "scopes": ["CREATE_SHARE_LINK"]
}

Your account must also have hosted virtual card sending enabled. If your account is not enabled, the API returns a permissions error instructing you to contact your Fluz representative.

Operations

Operation	Type	Purpose
`generateVCShareLinks`	Mutation	Create one or more hosted virtual card links.
`getVCShareLinks`	Query	List and inspect previously generated links.
`deactivateVCShareLinks`	Mutation	Deactivate generated links.

generateVCShareLinks

Creates quantity hosted share links.

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

Input fields

Field	Type	Required	Description
`cardLimit`	`Int!`	Yes	Spend limit and load amount for each card. Must be a whole number and meet the program minimum.
`offerId`	`String!`	Yes	UUID v4 of the virtual card offer. The offer must be active and its merchant must be shareable.
`quantity`	`Int!`	Yes	Number of links to generate. Fluz creates one distinct hosted URL per unit.
`shareMethod`	`ShareMethodType!`	Yes	Delivery method: `GENERATE_URL`, `EMAIL`, or `PHONE_NUMBER`.
`userCashBalanceId`	`UUID`	Yes	Spend account used to fund the cards. This field is required even though the GraphQL schema may show it as optional.
`daysUntilExpiration`	`Int`	No	Number of days the link is valid. Minimum is 1. If omitted, the program default is used. The resulting expiration date also becomes the card lock/freeze date after issuance.
`recipientListEmail`	`[String]`	Conditional	Required when `shareMethod` is `EMAIL`. Length must equal `quantity`. Must be omitted or empty for other delivery methods.
`recipientListPhone`	`[String]`	Conditional	Required when `shareMethod` is `PHONE_NUMBER`. Length must equal `quantity`. Must be omitted or empty for other delivery methods.

Delivery methods

`shareMethod`	Behavior	Recipient list rule
`GENERATE_URL`	Returns hosted URLs for you to distribute.	Do not send `recipientListEmail` or `recipientListPhone`.
`EMAIL`	Sends one email per recipient.	Send `recipientListEmail`; length must equal `quantity`.
`PHONE_NUMBER`	Sends one SMS per recipient.	Send `recipientListPhone`; length must equal `quantity`.

Validation rules

cardLimit must be a whole number and meet the program minimum.
offerId must be a valid UUID v4 for an active shareable offer.
quantity must be a whole number.
When using EMAIL or PHONE_NUMBER, the recipient list length must equal quantity.
userCashBalanceId must be a valid spend account owned by the sender’s account.
Do not include multiple funding sources.
Invalid or malformed requests fail validation and create no share links.

Example: generate URLs for your own delivery

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 3,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Example: email links to recipients

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": [
      "recipient1@example.com",
      "recipient2@example.com"
    ],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Example: text links to recipients

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 2,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": [
      "+12125550101",
      "+12125550102"
    ],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Response

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}

Each value in shareLinks is a hosted URL for one share request.

https://fluz.app/virtual-prepaid-card/{share_request_id}

The API returns the hosted destination URL. If Fluz also creates a short-link wrapper internally, that short URL is not returned by this API.

getVCShareLinks

Use getVCShareLinks to list generated links, retrieve batch and display IDs, inspect delivery targets, and check status.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    senderAppId
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    recipientPhone
    recipientEmail
    linkExpirationDate
    virtualCardId
    linkUrl
    shareRequestDetails {
      cardLimit
      offerId
      daysUntilExpiration
      quantity
      shareMethod
      recipientListEmail
      recipientListPhone
      userCashBalanceId
    }
  }
}

Input fields

Field	Type	Description
`shareObjectStatuses`	`[ShareObjectStatus]`	Filter by status: `PENDING`, `ISSUED`, `USED`, or `EXPIRED`.
`shareRequestBatchIds`	`[String]`	Return only links in these batches.
`shareRequestDisplayIds`	`[String]`	Return only links with these display IDs.

For the first lookup, filter by shareObjectStatuses. The response includes shareRequestBatchId and shareRequestDisplayId, which you can use for later lookups or deactivation.

Examples

{
  "input": {
    "shareObjectStatuses": ["PENDING", "ISSUED"]
  }
}

{
  "input": {
    "shareRequestBatchIds": ["ABC123", "XYZ789"]
  }
}

{
  "input": {
    "shareRequestDisplayIds": ["SR-000001", "SR-000002"]
  }
}

Response fields

Field	Type	Description
`senderAppId`	`String`	Application that generated the link.
`shareRequestBatchId`	`String`	Batch ID shared by links created in the same generation request.
`shareRequestDisplayId`	`String`	Human-friendly ID for the individual share request.
`shareObjectStatus`	`ShareObjectStatus`	Current status of the share request.
`recipientEmail`	`String`	Recipient email, when delivered by email.
`recipientPhone`	`String`	Recipient phone number, when delivered by SMS.
`linkExpirationDate`	`DateTime`	Link expiration date and card lock/freeze date.
`virtualCardId`	`String`	Issued virtual card ID after the link is claimed.
`linkUrl`	`String`	Hosted URL for the share request.
`shareRequestDetails`	`ShareRequestDetails`	Original generation settings.

deactivateVCShareLinks

Use deactivateVCShareLinks to expire generated links, for example if a batch was sent in error or an unclaimed link needs to be revoked.

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

Input fields

Field	Type	Description
`shareRequestBatchIds`	`[String]`	Deactivate every link in these batches.
`shareRequestDisplayIds`	`[String]`	Deactivate only links with these display IDs.

Example

{
  "input": {
    "shareRequestBatchIds": ["ABC123"]
  }
}

Response

Returns a confirmation string, for example:

3 share requests successfully deactivated!

Deactivating a link prevents an unclaimed link from being claimed. If a card has already been issued, use the appropriate card lifecycle controls to manage that card.

Recipient activation experience

When a recipient opens a hosted link, they are taken to a Fluz-hosted activation page.

The recipient opens the hosted virtual card link.
The recipient signs in or creates an account through the Fluz auth flow.
Existing users complete 2FA before viewing or claiming the card.
If the recipient does not have a billing address on file, they are prompted to add one. A billing address is required for online purchases.
If the card has not been issued yet, the recipient sets a PIN.
Fluz issues the virtual card to the recipient.
Once issued, the recipient can view card details and activity.

If the same user opens a link they already claimed, they can view their card details. If a different user opens a link already claimed by someone else, they are shown an access-denied state after authentication.

Expiration and card freeze

daysUntilExpiration determines the hosted link’s validity window. The resulting expiration date is used for two related behaviors:

Before claim: after the expiration date, the link can no longer be claimed.
After claim: the expiration date becomes the card lock/freeze date. After that date, the issued card is frozen and can no longer be spent.

If daysUntilExpiration is omitted, the program default is used.

Program rules

Program rules can vary by partner. Confirm the final values for your program with your Fluz representative.

Rule	Default / behavior
Funding source	Sender’s spend account.
Daily account spend limit	$250,000/day unless your program has a custom limit.
Restaurant transaction buffer	25% buffer applies to restaurant transactions.
Restricted merchants/categories	Program-specific restrictions may apply.
Recipient support	1-888-360-6660 or humans@fluz.app.

Status reference

Status	Meaning
`PENDING`	Link generated and not yet claimed.
`ISSUED`	Recipient claimed the link and a virtual card was issued.
`USED`	Issued card has been used.
`EXPIRED`	Link expired or was deactivated.

Common errors

Cause	Result
Missing or invalid Bearer token	Request is rejected.
Missing `CREATE_SHARE_LINK` scope	Request is rejected.
Account does not have hosted card sending enabled	Permissions error.
Recipient list length does not equal `quantity`	Validation error; no links are created.
Inactive or non-shareable offer	Validation error; no links are created.
Missing or invalid `userCashBalanceId`	Validation error; no links are created.
Multiple funding sources supplied	Validation error; no links are created.

Notes and limitations

This API is for hosted virtual cards only. Hosted gift-card links are not supported.
The API returns hosted destination URLs, not short URLs.
userCashBalanceId is required in practice.
Object type and card type are fixed for this phase and should not be supplied in public API requests.

Before you send:

If your funding source does not have enough funds at the time the recipient claims the card, issuance will fail. Ensure you have sufficient balance.
Phone numbers in recipientListPhone must be a string with no spaces, and must include the country code at the beginning — e.g. +18883606660, where +1 is the country code.

Next steps

Send Cards overview

The full feature narrative — recipient walkthrough, program rules, and complete error reference.

Create a bulk order

Issue many cards at once for programmatic distribution.

​How it works

​Authentication

​Operations

​generateVCShareLinks

​Input fields

​Delivery methods

​Validation rules

​Example: generate URLs for your own delivery

​Example: email links to recipients

​Example: text links to recipients

​Response

​getVCShareLinks

​Input fields

​Examples

​Response fields

​deactivateVCShareLinks

​Input fields

​Example

​Response

​Recipient activation experience

​Expiration and card freeze

​Program rules

​Status reference

​Common errors

​Notes and limitations

​Next steps

Send Cards overview

Create a bulk order

How it works

Authentication

Operations

generateVCShareLinks

Input fields

Delivery methods

Validation rules

Example: generate URLs for your own delivery

Example: email links to recipients

Example: text links to recipients

Response

getVCShareLinks

Input fields

Examples

Response fields

deactivateVCShareLinks

Input fields

Example

Response

Recipient activation experience

Expiration and card freeze

Program rules

Status reference

Common errors

Notes and limitations

Next steps