API

Quick start

Create a key, confirm access, and give a creator a link to an active campaign.

Use the Viffy address provided to your team, followed by /api/partner/v1. Replace YOUR-VIFFY-ADDRESS and the example key before running a command.

Use your team’s agreed testing address; contact Viffy if you need it. These calls create or update real data on that address.

Steps

Create a key
Go to Settings → API access → Create key. Name it and clear the Read only checkbox so it can complete this guide.

Check it works

Copy the key when it is created and keep it on your server; it is shown once. After this call, check the organization name and confirm key.canWrite is true.

Request

curl https://YOUR-VIFFY-ADDRESS/api/partner/v1/me \
  -H "Authorization: Bearer vfy_..."

Response

{
  "key": { "name": "Reporting sync", "canWrite": true },
  "organization": {
    "id": "2f6d1c2e-9c3a-4b7e-8f21-0a1b2c3d4e5f",
    "name": "Hummingbird Collective",
    "reportingTimeZone": "America/Chicago"
  }
}

Choose an active campaign
Read GET /campaigns?status=active and keep the campaign’s id. Check its dates and offer; if none is ready, follow Create a campaign, then activate it. A share link on a draft does not hand out codes.

Add a creator

Use your own creator ID in the path. The same call updates the creator later.

Request

curl -X PUT https://YOUR-VIFFY-ADDRESS/api/partner/v1/creators/hb-1042 \
  -H "Authorization: Bearer vfy_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "email": "[email protected]", "handle": "@janedoe" }'

Give them a link

Use the active campaign’s id. Your server makes this call; the answer contains the share link to give the creator and their separate private stats link.

Request

curl -X POST https://YOUR-VIFFY-ADDRESS/api/partner/v1/campaigns/CAMPAIGN-ID/creators/hb-1042 \
  -H "Authorization: Bearer vfy_..."

Response

{
  "creator": { "externalId": "hb-1042", "name": "Jane Doe" },
  "campaignId": "CAMPAIGN-ID",
  "shareUrl": "https://YOUR-VIFFY-ADDRESS/c/2lK9vNzQ8mT5xR7sB4cD6A",
  "shortCode": "ABCD-2345",
  "statsUrl": "https://YOUR-VIFFY-ADDRESS/s/Y3f9aQ6mR8sT2vW5xZ7bCA",
  "active": true,
  "activeOnRoster": true,
  "assignedAt": "2026-08-28T15:04:05Z",
  "deactivatedAt": null
}

Hear about redemptions
Follow Set up webhooks to receive new redemptions and corrections. Compare your totals with creator counts before crediting creators.

Showing the link in your app

Open shareUrl in the system browser, a Safari view controller, or a Chrome custom tab. Wallet passes and text-message autofill are unreliable inside one.

AuthenticationKeys, organizations, limits and request ids.ConventionsErrors, pages, cursors, dates, ranges and versioning.Full referenceEvery endpoint, field and response, generated from the API.

Quick start

Steps

Showing the link in your app

Next