Metricscores

Twee endpoints, bedoeld om samen te gebruiken. Je vraagt de metrics in je omgeving op om de juiste te vinden en te weten wat de cijfers betekenen, en daarna vraag je wat elke agent tussen twee datums scoorde.

Dat is ook de bedoelde volgorde — de id's die je aan metric-scores meegeeft komen uit metrics, en daar staat ook het antwoord op "is dit bedrag in euro's of in centen".

Metrics opvragen

GET /integrations/api/v1/metrics

Geen parameters. Je krijgt elke metric in je omgeving terug, in dezelfde volgorde als de pagina Metrics in de admin.

{
  "metrics": [
    {
      "id": 1,
      "name": "Sales",
      "unit": null,
      "value_unit": "raw",
      "display_mode": "number",
      "lower_is_better": false,
      "can_rank": true
    },
    {
      "id": 2,
      "name": "Contractwaarde",
      "unit": "euro",
      "value_unit": "euros",
      "display_mode": "currency",
      "lower_is_better": false,
      "can_rank": true
    }
  ]
}

Veld	Betekenis
id	De metric_id die je meegeeft aan metric-scores en aan de doelstelling-endpoints.
name	De naam van de metric zoals hij overal in SalesDash staat.
unit	Het label waarmee een metric in de interface wordt getoond — uur, euro, sales. Vrije tekst, ingesteld in de admin, en null als niemand er een heeft gekozen. Reken hier niet mee.
value_unit	De eenheid waarin de value-getallen werkelijk staan. Dit is de betrouwbare — zie hieronder.
display_mode	Hoe SalesDash de metric opmaakt: number, percentage, currency, duration, score, ratio of raw. null betekent dat er nog geen gekozen is.
lower_is_better	true als een lager getal een beter resultaat is — gemiddelde gespreksduur, kosten per lead.
can_rank	Of de metric per agent te scoren is. false betekent dat hij alleen op organisatieniveau bestaat, en dan weigert metric-scores hem.

unit is een label, value_unit is de eenheid

Deze twee spreken elkaar vaker tegen dan je verwacht, en dat is met opzet. unit is het woord dat je collega's naast het cijfer willen zien; value_unit is waarin het ruwe getal in de API gemeten is.

value_unit	De value die je terugkrijgt
euros	Euro's, al omgerekend — 181942 is €181.942,00.
seconds	Seconden, ook als de metric het label uur draagt. Deel zelf door 3600 voor uren.
fraction	Een fractie, geen percentage — een conversie van 42% komt binnen als 0.42.
raw	Een gewoon aantal of een score, zonder eenheid.
null	SalesDash claimt geen eenheid. De meeste ratio-metrics staan op null, omdat de eenheid van een ratio voortkomt uit de twee metrics die hij deelt en niet uit iets op de metric zelf — een ratio die als duur wordt opgemaakt (gemiddelde gespreksduur bijvoorbeeld) is de uitzondering en meldt seconds. Lees bij een null value_formatted in plaats van te rekenen, of vraag het na bij degene die de ratio heeft ingericht.

Elk antwoord met een getal erin draagt ook zijn value_unit, dus je hoeft nooit te onthouden welke metric welke was.

Metrics die niet gelezen konden worden

Soms klopt de configuratie van een metric niet — een ratio waarvan de onderliggende metric is verwijderd, of een metric die nooit is afgemaakt. De rest tonen is nuttiger dan helemaal niets teruggeven, dus zo'n metric staat er wel bij, gemarkeerd:

{
  "id": 14,
  "name": "Kosten per geboekte demo",
  "unit": null,
  "value_unit": null,
  "display_mode": null,
  "lower_is_better": false,
  "can_rank": null,
  "unavailable": true
}

can_rank: null is iets anders dan false. false zegt deze metric is er één op organisatieniveau; null zegt niemand kon deze metric lezen, dus niemand weet het. Sla een metric met unavailable over en repareer hem in de admin — zijn scores opvragen levert een 422 op.

Er moeten twee dingen kloppen voordat een metric te scoren is

can_rank moet true zijn én display_mode mag niet null zijn. Ze staan los van elkaar omdat het losse problemen zijn: het eerste is een metric die nooit bedoeld was om per persoon te ranken, het tweede een metric waar alleen nog een weergave voor ingesteld moet worden. Controleer beide voordat je metric-scores aanroept.

De scores lezen

GET /integrations/api/v1/metric-scores?metric_id=2&start_date=2026-08-01&end_date=2026-08-25

Parameter	Verplicht	Toelichting
metric_id	ja	Uit de lijst hierboven.
start_date	ja	JJJJ-MM-DD.
end_date	ja	JJJJ-MM-DD, op of na start_date.

Beide datums tellen mee — het voorbeeld hierboven bevat 25 augustus helemaal. Het formaat is met opzet streng: een losse 2026 zou anders gelezen worden als een tijdstip op de dag van vandaag, en dan kreeg je een venster van één minuut terug zonder dat iemand het zei.

{
  "metric": {
    "id": 2,
    "name": "Contractwaarde",
    "unit": "euro",
    "value_unit": "euros",
    "display_mode": "currency",
    "lower_is_better": false
  },
  "date_range": {
    "start": "2026-08-01",
    "end": "2026-08-25"
  },
  "scores": [
    {
      "rank": 1,
      "agent_id": 22,
      "name": "Tamara Wilson",
      "team_id": 2,
      "value": 181942,
      "value_formatted": "€181.942,00"
    },
    {
      "rank": 2,
      "agent_id": 7,
      "name": "Lily Davis",
      "team_id": 2,
      "value": 104930,
      "value_formatted": "€104.930,00"
    }
  ]
}

value is het getal om mee te rekenen, in value_unit. value_formatted is hetzelfde getal zoals SalesDash het op een dashboard schrijft — gebruik dat als je het cijfer rechtstreeks aan iemand laat zien, dan komt het overeen met wat diegene elders in SalesDash ziet.

Wat er wel en niet in staat

Elke op dit moment actieve agent, en alleen die. Iemand die vertrokken is staat er niet bij, ook niet als hij binnen de periode iets verkocht. Iedereen die nog actief is staat er wel bij, ook wie niets scoorde — die komt terug op 0. Er is geen paginagrootte en geen top-X: je vroeg om de scores van de metric, dus je krijgt het hele team.

Rangen lopen door. Twee agents met dezelfde waarde krijgen twee verschillende rangen, in willekeurige volgorde ten opzichte van elkaar. Als gelijke standen voor jou uitmaken, groepeer dan zelf op value.

Een nul kan "er is niets gebeurd" betekenen, en bij lager-is-beter wint die

Een actieve agent zonder activiteit in de periode scoort 0. Bij een metric waar lager beter is — gemiddelde gespreksduur, kosten per lead — pakt die 0 rang 1, vóór iedereen die wél gewerkt heeft.

Zo werkt ranken overal in SalesDash, dashboards inbegrepen, dus de API doet hier niets bijzonders. Maar publiceer je een lager-is-beter-ranglijst ergens waar mensen hem lezen, haal de rijen met waarde nul er dan eerst zelf uit of markeer ze.

Weigeringen

Een 422 op dit endpoint gaat vrijwel altijd over de metric en niet over het verzoek:

• De metric is er één op organisatieniveau (can_rank: false) — er is geen cijfer per agent om te geven.
• De metric heeft geen weergave — SalesDash kan de scores dan niet opmaken. Stel er een in op de metric in de admin.
• De configuratie van de metric is niet te lezen — dezelfde rijen die de lijst markeert met unavailable.

Filter je lijst op can_rank: true en een display_mode die niet null is, dan loop je geen van de drie tegen het lijf.