Doelstellingen

Twee endpoints om doelstellingen naar SalesDash te schrijven vanuit de plek waar je ze plant — een spreadsheet, een HR-systeem, je eigen planningstool.

• POST /goal maakt of werkt een doelstelling bij voor één of meer teams.
• POST /agent-goal zet de persoonlijke doelstelling van één agent voor een week, maand, kwartaal of jaar.

Allebei zijn het upserts: stuur dezelfde doelstelling nog eens en je werkt bij wat er al staat in plaats van er een tweede naast te zetten. Daardoor kun je ze veilig op een schema laten lopen.

Allebei weigeren ze met een 422 een metric die geen cijfer per agent heeft — dezelfde metrics die metric-scores weigert. Filter je metriclijst op can_rank: true en je loopt bijna geen enkele daarvan tegen het lijf. Een paar soorten metrics kunnen sowieso geen doelstelling dragen, hoe ze ook ranken — een getrapte metric bijvoorbeeld, waar een doelstelling tussen twee treden in valt en dus niets betekent — en die zeggen dat in de 422.

Eerst de eenheid

value is een kaal getal, en SalesDash neemt aan wat je stuurt. Stuur je de verkeerde eenheid, dan klaagt er niets — de doelstelling staat dan gewoon op een honderdste van wat je bedoelde, of duizend keer zo hoog, tot iemand ziet dat de voortgangsbalk nergens op slaat.

De twee endpoints zijn het onderling oneens over geld. Leg deze tabel naast de display_mode uit de metriclijst voordat je iets stuurt:

display_mode	POST /goal (team)	POST /agent-goal (persoonlijk)
currency	Euro's — 50000 is €50.000	Centen — 5000000 is €50.000
duration	Seconden — 7200 is twee uur	Seconden — 7200 is twee uur
percentage	Een fractie — 0.4 is 40%	Een fractie — 0.4 is 40%
number, score, ratio, raw	Het getal zoals de metric het meldt	Het getal zoals de metric het meldt

Tijd sluit overal op elkaar aan: een duur-doelstelling staat in seconden, dezelfde eenheid die metric-scores meldt, dus een cijfer gaat één-op-één van het een naar het ander. Geld niet — een bedrag staat in euro's bij een team en in centen bij een persoon.

Controleer een doelstelling nadat je hem voor het eerst wegschrijft

Open hem in de admin, of op het profiel van de agent, en kijk of het bedrag staat zoals je het bedoelde. Dit is de meest voorkomende manier waarop een doelstellingskoppeling stilletjes misgaat, en het verschil tussen €500 en €50.000 zie je niet aan het verzoek zelf.

Een doelstelling voor teams zetten

POST /integrations/api/v1/goal
Content-Type: application/json

{
  "name": "Q4 contractwaarde",       // Verplicht
  "metric_id": 2,                    // Verplicht
  "active_from": "2026-10-01",       // Verplicht
  "active_to": "2026-12-31",         // Verplicht, op of na active_from
  "team_goals": [                    // Verplicht, minstens één team
    { "team_id": 2, "value": 500000 },
    { "team_id": 3, "value": 350000 }
  ]
}

{
  "message": "Goal created successfully.",
  "goal_id": 3
}

Je krijgt 201 als de doelstelling is aangemaakt en 200 als een bestaande is bijgewerkt, en het bericht zegt welke van de twee.

De naam is de identiteit. SalesDash zoekt op name over al je doelstellingen, dus dezelfde naam opnieuw sturen werkt die doelstelling bij — de periode, de metric en de teamwaarden gaan allemaal mee naar wat je zojuist stuurde. Twee doelstellingen die uit elkaar moeten blijven hebben twee verschillende namen nodig, en een naam die je hergebruikt voor iets anders overschrijft de oude in plaats van er een toe te voegen.

De waarde 0 haalt de doelstelling van dat team weg, net als het veld leegmaken in de admin. Zo haal je een team van een doelstelling af zonder de doelstelling zelf te verwijderen.

Gemiddelden en ratio's kunnen maar één team dragen

Een metric die middelt of deelt — gemiddelde contractwaarde, conversiepercentage — kun je niet over teams verdelen, omdat de uitkomsten niet bij elkaar op te tellen zijn tot een geheel. Stuur je voor zo'n metric meer dan één team met een waarde boven nul, dan krijg je een 422. Geef hem één team, of maak een doelstelling per team.

De doelstelling verschijnt onder Doelstellingen in de admin, waar je de onderdelen kunt toevoegen die dit endpoint bewust laat liggen — muntbeloningen en opvolgende doelstellingen.

Een persoonlijke doelstelling zetten

POST /integrations/api/v1/agent-goal
Content-Type: application/json

{
  "agent_id": 7,       // Verplicht
  "metric_id": 2,      // Verplicht
  "value": 5000000,    // Verplicht — let op de eenhedentabel hierboven
  "month": "2026-09"   // Verplicht: precies één van week, month, quarter, year
}

Noem precies één periode. Er geen noemen, of er twee noemen, levert een 422 op — een doelstelling zonder periode is er een die niemand kan dateren en niemand ooit terugvindt.

Periode	Wat je stuurt	Wat je terugkrijgt
week	Een datum in die week — 2026-09-16	De maandag van die week — 2026-09-14
month	2026-09	2026-09
quarter	Een maand in dat kwartaal — 2026-09	De eerste maand van het kwartaal — 2026-07
year	2026	2026

Elke datum binnen de periode werkt: stuur 2026-09-14 als month en hij landt op september, precies alsof je 2026-09 had gestuurd. Je kunt dus een echte datum uit je eigen systeem doorgeven zonder eerst uit te rekenen bij welke week of welk kwartaal die hoort — maar lees de waarde terug, want het is niet de tekst die je stuurde.

Het antwoord is de opgeslagen doelstelling:

{
  "data": {
    "unit": "euro",
    "display_mode": "currency",
    "year": null,
    "quarter": null,
    "month": "2026-09",
    "week": null,
    "value": 5000000,
    "is_locked": false
  }
}

Lees month/quarter/week/year terug om te zien op welke periode je werkelijk uitkwam, en value om te zien of de eenheid is geworden wat je bedoelde.

Eén persoonlijke doelstelling per agent per periode

Een agent heeft één doelstelling per periode, niet één per metric. Een doelstelling voor september zetten vervangt wat er stond — ook een doelstelling op een andere metric. Lees het antwoord terug als dat voor jou uitmaakt.

Het slot van één uur geldt hier niet. In de app kan een agent zijn eigen doelstelling alleen binnen een uur na het zetten nog wijzigen, zodat resultaten niet achteraf passend gemaakt kunnen worden. Een API sleutel hoort bij een admin, dus dit endpoint schrijft sowieso — wat je wilt voor een geplande synchronisatie, en goed om te weten als agents daarnaast zelf doelstellingen zetten.

actual en is_locked komen mee als onderdeel van de doelstelling, maar zijn bedoeld voor de schermen van de app zelf; actual wordt hier niet ingevuld. Wil je zien hoe een agent ervoor staat, vraag dan metric-scores op voor dezelfde metric over dezelfde datums.