Create your first credit claim

This guide creates a recipient-specific promotional credit offer and returns a link you can deliver to that recipient.

Prerequisites

A Sparkles account with API access enabled.
Permission to open the API access page.
A server-side environment where you can protect a long-lived API key.

Step 1: Create an API key

Open the API access page, create a named key, and copy it immediately. Sparkles does not display the secret again. Store it in your server-side secret manager:

export SPARKLES_API_KEY="<your-api-key>"

Never embed this key in frontend JavaScript, mobile applications, logs, or analytics events.

Step 2: Create a claim

Choose a stable, opaque lead identifier that contains no name, email address, or other personal data. The identifier is the idempotency key for this access grant.

curl https://sparkles.dev/api/public/v1/credit-claims \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "leadId": "lead_123",
    "email": "person@example.com",
    "variant": "call-offer",
    "creditAmount": 1000
  }'

creditAmount is a whole-credit integer. The first successful request returns HTTP 201:

{
	"id": "01890a5d-ac96-774b-bcce-b302099a8057",
	"leadId": "lead_123",
	"variant": "call-offer",
	"creditAmount": 1000,
	"status": "pending",
	"claimUrl": "https://sparkles.dev/claim/CLAIM_TOKEN",
	"statusUrl": "https://sparkles.dev/api/public/v1/credit-claims/01890a5d-ac96-774b-bcce-b302099a8057",
	"createdAt": "2026-08-03T09:30:00.000Z",
	"claimedAt": null
}

Save id for reconciliation, and send claimUrl only to the intended recipient.

Step 3: Make retries idempotent

Retry the same request with the same leadId, email, variant, and amount after a network failure. Sparkles returns the original claim with HTTP 200 and does not reserve credits twice. Reusing the same leadId with different claim details returns HTTP 409 with idempotency_conflict. Use the original details or create a new lead identifier.

Step 4: Check claim status

Use status lookup for manual recovery or to reconcile a missed webhook. Do not poll it as your primary event mechanism.

curl https://sparkles.dev/api/public/v1/credit-claims/01890a5d-ac96-774b-bcce-b302099a8057 \
  --header "Authorization: Bearer $SPARKLES_API_KEY"

The claim status is one of:

Status	Meaning
`pending`	The claim link is still available.
`claimed`	Credits were added once to the recipient’s selected organization.
`cancelled`	The claim is terminal and can no longer be redeemed.

Verification

Your integration is working when the create request returns 201, an identical retry returns 200 with the same id, and the returned statusUrl returns the same claim. Next, configure signed webhook delivery so you do not need to poll for changes.

Troubleshooting

HTTP 401: replace the bearer key with an active key from the API access page.
HTTP 409: preserve the original idempotent request or ask an administrator to increase the access budget.
HTTP 422: lower creditAmount to the per-claim limit shown on the API access page.
HTTP 429: wait for the Retry-After duration before retrying.

Get started

Integration guides

API reference

Create your first credit claim

Prerequisites

Step 1: Create an API key

Step 2: Create a claim

Step 3: Make retries idempotent

Step 4: Check claim status

Verification

Troubleshooting

​Prerequisites

​Step 1: Create an API key

​Step 2: Create a claim

​Step 3: Make retries idempotent

​Step 4: Check claim status

​Verification

​Troubleshooting

Prerequisites

Step 1: Create an API key

Step 2: Create a claim

Step 3: Make retries idempotent

Step 4: Check claim status

Verification

Troubleshooting