account/monitors

Een monitor aanmaken en de eerste nulmeting zijn gratis. Een cyclus van 30 dagen wordt berekend zodra de monitor actief wordt. De prijs hangt af van het controle-interval en dekt alle controles die het interval binnen één cyclus inplant.

Een interval tussen twee niveaus kost evenveel als het eerstvolgende frequentere niveau: elke vier dagen kost evenveel als elke drie dagen.

Extra controles ontstaan vooral als je het interval midden in een cyclus verkort. Elke geslaagde extra controle kost het bedrag uit de tabel.

Na 30 dagen wordt de cyclus automatisch verlengd tegen de dan geldende prijs. Mislukte controles kosten niets. Bij pauzeren, archiveren of een wijziging van het interval betalen we niets terug.

Elk account kan tot 50 monitors tegelijk hebben, één per bedrijf. Binnen 24 uur kun je tot 50 monitors aanmaken; gearchiveerde tellen mee.

De prijs van een interval krijg je gratis met GET /v1/account/monitoring/pricing, hier voor een controle elke zeven dagen:

1. Aanmaken. Je noemt het bedrijf, het controle-interval en minstens één geverifieerd webhook-endpoint. De monitor start met de status initializing.
2. Nulmeting. We markeren de signalen van de laatste paar dagen als bekend. Die worden niet geleverd, dus je krijgt alleen wat daarna nieuw is.
3. Activeren. We berekenen de cyclus, de monitor wordt active en controleert meteen voor het eerst.
4. Controleren. Daarna controleert hij met het gekozen interval. Elk nieuw signaal levert per monitor één bericht aan je webhook-endpoints op.
5. Verlengen. Na elke cyclus wordt de volgende automatisch berekend, zolang je saldo die dekt.

Het controle-interval ligt tussen 1 en 30 dagen. Het precieze tijdstip van een controle kan binnen een uur variëren. Elke controle kijkt een paar dagen terug, zodat ook laat gepubliceerde inschrijvingen binnenkomen.

Een monitor levert de Signals-onderwerpen van je plan: vijf in elk account, Insolventies met Pro, Omzettingen & M&A met Max. Een webhook bevat in het veld data.signal hetzelfde signaal als signals.

Bij gepauzeerde monitors en fouten legt status_reason uit waarom, bijvoorbeeld no_verified_endpoint of insufficient_cycle_floor.

Alle paden staan onder /v1/account. Je leest en schrijft met je API-sleutel in de header x-api-key.

Elke schrijfaanvraag vraagt de header Idempotency-Key, een unieke waarde per bewerking, bij voorkeur een UUID. Zonder die header antwoordt de API met 428.

Herhaal je een aanvraag binnen 24 uur met dezelfde sleutel en dezelfde gegevens, dan krijg je het opgeslagen antwoord terug. Dat heeft de header Idempotency-Status: replayed. Zo maakt een netwerkfout geen tweede monitor aan.

Dat geldt ook voor foutantwoorden. Gebruik dus voor een nieuwe poging na een correctie een nieuwe sleutel. Dezelfde sleutel met andere gegevens levert 409.

Tot 128 tekens zijn toegestaan: letters, cijfers en . _ : -. Het eerste teken is een letter of een cijfer. Een sleutel in een ander formaat levert 400.

Je hebt de entity_id van het bedrijf nodig en minstens één geverifieerd webhook-endpoint, zie account/webhook-endpoints.

De API antwoordt met 202: de monitor is aangemaakt, en nulmeting en activering lopen op de achtergrond. meta.billing.charged_credits laat zien dat hiervoor niets is berekend.

GET /v1/account/monitors levert tot 100 monitors onder monitors, met total. Gearchiveerde staan niet in de lijst.

GET /v1/account/monitors/{id} toont ook de huidige cyclus in billing_cycle en de laatste controles in recent_runs.

PATCH /v1/account/monitors/{id} wijzigt het controle-interval. De volgende controle volgt dan met het nieuwe interval, gerekend vanaf de wijziging.

De huidige cyclus houdt zijn prijs en inbegrepen controles. De nieuwe prijs geldt vanaf de volgende cyclus. Een korter interval kan in de huidige cyclus extra controles opleveren.

POST …/{id}/pause stopt een actieve monitor. De betaalde cyclus loopt gewoon af, en er wordt niets terugbetaald.

POST …/{id}/resume hervat een gepauzeerde monitor of een monitor met een fout. We controleren webhook-endpoints, saldo en prijs opnieuw.

Binnen de huidige betaalde cyclus kost hervatten niets. Is de cyclus afgelopen, dan start er nu een nieuwe cyclus tegen de huidige prijs. meta.request_credit_cost toont het bedrag.

Ontbreekt bijvoorbeeld een geverifieerd webhook-endpoint, dan antwoordt de API toch met 200, maar met meta.activated: false. De status van de monitor en status_reason geven de reden.

Is de prijs gewijzigd, dan stopt een actieve monitor aan het einde van de cyclus met pricing_consent_required. Met resume ga je akkoord met de nieuwe prijs.

DELETE …/{id} archiveert de monitor definitief. Dat is onomkeerbaar en er wordt niets terugbetaald.

Fouten hebben de opbouw {"error": "…", "meta": {"message": "…"}}. Controleer in je programma de waarde van error. De tekst in meta.message is in het Engels en kan veranderen. Fouten kosten niets.