API-documentatie

Zo begin je

• Basis-URL: https://api.fiig.io/v1. Alle verzoeken gaan via HTTPS.
• Je stuurt en krijgt JSON. Stuur bij een body de header Content-Type: application/json mee.
• Tijdens de beta is de API gratis.
• Foutmeldingen van de API zijn in het Engels; op deze pagina staat wat ze betekenen.

Er zijn vier widgettypes: countdown (aftelklok), poll, progress (voortgangsbalk) en stock (voorraadteller). Ze gebruiken dezelfde sleutels en endpoints, elk met eigen instellingen. Zonder type maak je een aftelklok, dus bestaande koppelingen blijven werken. Volgende widgets komen er op dezelfde manier bij.

Werk je niet zelf met code? Met Zapier of Make gebruik je de API zonder te programmeren. Zie Zapier en Make onderaan.

API-sleutel maken

1. Log in en ga naar Account → API.
2. Geef de sleutel een naam waaraan je hem herkent, bijvoorbeeld "Zapier" of "Webshop".
3. Klik op Sleutel maken en kopieer de sleutel direct. Je ziet hem maar één keer.

• Een sleutel hoort bij je werkruimte: hij werkt voor alle widgets daarin, ook die van collega's.
• Je kunt maximaal 10 sleutels hebben. Gebruik er één per systeem, dan kun je er één intrekken zonder de rest te raken.
• Bij elke sleutel zie je wanneer hij voor het laatst is gebruikt.

Behandel een sleutel als een wachtwoord. Gebruik hem alleen op een server of in een tool als Zapier, nooit in een website, app of e-mail. Uitgelekt? Trek hem in via Account → API en maak een nieuwe.

Authenticatie

Stuur je sleutel bij elk verzoek mee in de header Authorization:

Authorization: Bearer fiig_…

Zonder geldige sleutel krijg je 401 unauthorized. Een voorbeeld dat al je widgets ophaalt:

curl https://api.fiig.io/v1/widgets \
  -H "Authorization: Bearer $FIIG_API_KEY"

Widgets

Elke widget heeft een id: hetzelfde stuk als in de afbeeldings-URL, dus k7Qx2mPa9rTb in https://fiig.email/t/k7Qx2mPa9rTb.gif. Een widget ziet er zo uit:

{
  "data": {
    "id": "k7Qx2mPa9rTb",
    "type": "countdown",
    "name": "Kerstactie",
    "altText": "Nog 3 dagen tot Kerst",
    "config": {
      "targetAt": "2026-12-24T18:00",
      "timezone": "Europe/Amsterdam",
      "width": 600,
      "height": 200,
      "...": "..."
    },
    "imageUrl": "https://fiig.email/t/k7Qx2mPa9rTb.gif",
    "embedHtml": "<img src=\"https://fiig.email/t/k7Qx2mPa9rTb.gif\" width=\"600\" height=\"200\" alt=\"Nog 3 dagen tot Kerst\" style=\"display:block;border:0;\">",
    "dashboardUrl": "https://fiig.io/dashboard/widgets/42",
    "createdAt": "2026-10-05T14:02:11.000Z",
    "updatedAt": "2026-10-05T14:02:11.000Z"
  }
}

config bevat altijd alle instellingen, ook de standaardwaarden. embedHtml is de code die je in je e-mail plakt: bij een aftelklok, voortgangsbalk en voorraadteller één <img>-tag, bij een poll de vraag, de antwoordknoppen en de live uitslag. Bij een poll is imageUrl de afbeelding met de uitslag.

Widgets ophalen

GET/v1/widgets

Geeft je widgets terug, de laatst gewijzigde eerst, in pagina's. Met limit (1 tot 100, standaard 50) en page (vanaf 1) blader je. Het antwoord bevat data, page, totalPages en totalCount.

GET/v1/widgets/{id}

Geeft één widget terug.

Widget maken

POST/v1/widgets

Verplicht zijn name en in config de einddatum (targetAt) en tijdzone (timezone). Wat je niet meestuurt, komt uit de huisstijl van je werkruimte en anders uit de standaardwaarden, net als in het dashboard. Je krijgt 201 met de nieuwe widget, inclusief embedHtml.

curl https://api.fiig.io/v1/widgets \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kerstactie",
    "altText": "Nog even tot Kerst",
    "config": {
      "targetAt": "2026-12-24T18:00",
      "timezone": "Europe/Amsterdam"
    }
  }'

const response = await fetch("https://api.fiig.io/v1/widgets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FIIG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Kerstactie",
    config: { targetAt: "2026-12-24T18:00", timezone: "Europe/Amsterdam" },
  }),
});
const { data: widget } = await response.json();
console.log(widget.embedHtml);

Poll maken

Stuur "type": "poll" mee. Verplicht zijn name en in config de vraag (question) en 2 tot 5 antwoorden (options). Een antwoord zonder id krijgt er automatisch een. Alle velden staan bij Instellingen van een poll.

curl https://api.fiig.io/v1/widgets \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "poll",
    "name": "Taart van de week",
    "config": {
      "question": "Welke taart bakken we zaterdag?",
      "options": [
        { "label": "Appeltaart" },
        { "label": "Chocoladetaart" },
        { "label": "Citroentaart" }
      ],
      "closesAt": "2026-12-20T18:00",
      "timezone": "Europe/Amsterdam"
    }
  }'

Voortgangsbalk maken

Stuur "type": "progress" mee. Verplicht zijn name en in config het doel (goal). De huidige stand (current) begint op 0 als je hem weglaat. Alle velden staan bij Instellingen van een voortgangsbalk.

curl https://api.fiig.io/v1/widgets \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "progress",
    "name": "Nieuwe oven",
    "config": {
      "current": 7200,
      "goal": 10000,
      "title": "Help ons aan een nieuwe oven",
      "prefix": "€ "
    }
  }'

Voorraadteller maken

Stuur "type": "stock" mee. Verplicht is alleen name; het aantal (count) begint op 0 als je het weglaat. Zonder textBefore en textAfter krijg je "Nog 25 op voorraad" (of "Only 25 left in stock" met "locale": "en"). Alle velden staan bij Instellingen van een voorraadteller.

curl https://api.fiig.io/v1/widgets \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stock",
    "name": "Kersttaarten",
    "config": {
      "count": 25,
      "textBefore": "Nog",
      "textAfter": "kersttaarten te bestellen",
      "lowStock": 5
    }
  }'

Widget wijzigen

PATCH/v1/widgets/{id}

Stuur alleen wat verandert: name, altText en/of velden in config. De afbeelding in al verstuurde e-mails verandert binnen twee minuten mee.

• Een veld in config vervangt de oude waarde.
• units en labels worden per sleutel samengevoegd: { "labels": { "days": "dg" } } verandert alleen het label voor dagen.
• null zet een veld terug naar de standaardwaarde, bijvoorbeeld { "cornerRadius": null }.
• Bij een poll vervang je options altijd in zijn geheel. Stuur de bestaande id's mee als je een antwoord anders formuleert: die staan in de stemlinks van verstuurde e-mails en in de tellingen.
• Het type van een widget kan niet veranderen.

Een aftelklok een week later laten aflopen:

curl -X PATCH https://api.fiig.io/v1/widgets/k7Qx2mPa9rTb \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "targetAt": "2026-12-31T23:59" } }'

De stand van een voortgangsbalk bijwerken, bijvoorbeeld vanuit je webshop, Zapier of Make. Stuur de nieuwe totale stand, niet het verschil:

curl -X PATCH https://api.fiig.io/v1/widgets/Rt5mW8cQz2Lp \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "current": 8350 } }'

Zo werk je ook het aantal van een voorraadteller bij. Bij 0 toont hij de tekst voor uitverkocht:

curl -X PATCH https://api.fiig.io/v1/widgets/Wq3nB7xKd9Fs \
  -H "Authorization: Bearer $FIIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "count": 12 } }'

Widget verwijderen

DELETE/v1/widgets/{id}

Geeft 204 zonder inhoud. Let op: de afbeelding verdwijnt dan ook uit e-mails die al verstuurd zijn.

curl -X DELETE https://api.fiig.io/v1/widgets/k7Qx2mPa9rTb \
  -H "Authorization: Bearer $FIIG_API_KEY"

Instellingen van een aftelklok

Dit zijn de velden in config. Kleuren zijn altijd #rrggbb.

Instellingen van een poll

De velden in config van een poll. Kleuren zijn altijd #rrggbb. Wat je niet meestuurt, komt uit je huisstijl of de standaardwaarden.

Instellingen van een voortgangsbalk

De velden in config van een voortgangsbalk. Kleuren zijn altijd #rrggbb. Wat je niet meestuurt, komt uit je huisstijl of de standaardwaarden.

Instellingen van een voorraadteller

De velden in config van een voorraadteller. Kleuren zijn altijd #rrggbb. Wat je niet meestuurt, komt uit je huisstijl of de standaardwaarden.

Statistieken

GET/v1/widgets/{id}/stats

Het totaal aantal opens en de opens per dag, in de tijdzone van de widget. Met days (1 tot 366, standaard 30) kies je hoeveel dagen terug, vandaag meegerekend. Testmails en voorbeelden in de builder tellen niet mee.

curl "https://api.fiig.io/v1/widgets/k7Qx2mPa9rTb/stats?days=7" \
  -H "Authorization: Bearer $FIIG_API_KEY"

{
  "data": {
    "id": "k7Qx2mPa9rTb",
    "timezone": "Europe/Amsterdam",
    "totalOpens": 18452,
    "days": [
      { "date": "2026-12-18", "opens": 0 },
      { "date": "2026-12-19", "opens": 9210 },
      { "date": "2026-12-20", "opens": 4022 }
    ]
  }
}

Bij een poll staat er ook votes in: het totaal, de uitslag per antwoord (in de volgorde van de poll, met hele percentages) en de stemmen per dag. Bij een poll telt totalOpens hoe vaak de afbeelding met de uitslag is geladen. Stemmen vanuit testmails en het voorbeeld in de builder tellen niet mee.

{
  "data": {
    "id": "Pq8sV2nLx4Ke",
    "timezone": "Europe/Amsterdam",
    "totalOpens": 6120,
    "days": [ … ],
    "votes": {
      "total": 412,
      "results": [
        { "id": "a", "label": "Appeltaart", "votes": 231, "percent": 56 },
        { "id": "b", "label": "Chocoladetaart", "votes": 124, "percent": 30 },
        { "id": "c", "label": "Citroentaart", "votes": 57, "percent": 14 }
      ],
      "days": [
        { "date": "2026-12-18", "votes": 0 },
        { "date": "2026-12-19", "votes": 301 },
        { "date": "2026-12-20", "votes": 111 }
      ]
    }
  }
}

Fouten

Bij een fout krijg je altijd hetzelfde formaat:

{
  "error": {
    "code": "invalid_request",
    "message": "Some fields are invalid. See details.",
    "details": [
      { "path": "config.width", "message": "Too big: expected number to be <=600" }
    ]
  }
}

Limieten

• Maximaal 120 verzoeken per minuut per sleutel. Daarboven krijg je 429 met een Retry-After-header.
• Maximaal 10 sleutels per werkruimte.
• De API is bedoeld voor servers en tools. Verzoeken vanuit een browser worden niet ondersteund, zodat je sleutel niet uitlekt.

Zapier en Make

Zonder te programmeren koppel je Fiig aan andere apps. Een voorbeeld: verschuif de einddatum van je aftelklok als de deadline in je planning verandert.

Zapier

1. Kies een trigger, bijvoorbeeld een nieuwe of gewijzigde rij in Google Sheets.
2. Voeg als actie Webhooks by Zapier toe, met de gebeurtenis Custom Request.
3. Method: PATCH. URL: https://api.fiig.io/v1/widgets/ gevolgd door het id van je widget.
4. Data: de JSON hieronder, met het veld uit je trigger op de plek van {{deadline}}.
5. Headers: Authorization met de waarde Bearer en je sleutel, en Content-Type met application/json.
6. Test de stap. Bij succes krijg je de widget terug met de nieuwe einddatum.

{ "config": { "targetAt": "{{deadline}}" } }

Make

1. Voeg de module HTTP → Make a request toe.
2. URL en method zoals hierboven, body type Raw, content type JSON (application/json).
3. Voeg de header Authorization toe met Bearer en je sleutel, en zet de JSON in Request content.

Zet de einddatum als 2026-12-24T18:00 (zonder seconden en zonder tijdzone): de tijdzone van de widget bepaalt dan wanneer hij afloopt.

OpenAPI

Een volledige, machine-leesbare beschrijving van de API staat op https://api.fiig.io/v1/openapi.json. Importeer hem in bijvoorbeeld Postman of Insomnia om alle verzoeken direct uit te proberen.