TalkIP
Account aanmaken
Alle onderwerpen

Resellers

Als reseller verkoop je TalkIP aan je eigen klanten. Je maakt en beheert hun organisaties zelf, vanuit je eigen systemen, via de API. Je klanten krijgen van ons geen facturen. Alles wat geld kost, zoals gebruikers, een abonnement, modules, nummers en AI-credits, komt op één maandfactuur aan jou, tegen de prijzen die we met je hebben afgesproken.

Hoe het werkt

  1. Wij maken je reseller-account aan, met je naam, het adres waar je klanten met vragen terechtkunnen en de gegevens waarop we je factureren. Vanaf die dag loopt je maand.
  2. We spreken je prijzen af en maken een API-sleutel voor je aan.
  3. Je maakt een organisatie voor een klant met POST /tenants, met een abonnement, het aantal gebruikers en het e-mailadres van de eigenaar. De organisatie werkt meteen en de eigenaar krijgt een uitnodiging.
  4. Je geeft de organisatie een nummer. De eigenaar nodigt in het dashboard de rest van het team uit en richt in wie er opneemt, net als elke andere klant.
  5. Wil de klant meer gebruikers, een ander abonnement, een module of AI-credits, dan regel je dat via de API. Het komt op je volgende factuur.

Wat je klanten zien

  • Onder het logo in het dashboard staat Beheerd door met jouw naam, en het adres voor vragen als je dat hebt opgegeven.
  • Ze zien Financieel niet en kunnen zelf geen gebruikers, abonnement, modules, nummers of AI-credits bijnemen. Daarvoor verwijst het dashboard ze naar jou. Hun saldo en verbruik van AI-credits zien ze wel.
  • Al het andere doen ze zelf: teamleden uitnodigen, toestellen, belgroepen, keuzemenu's, openingstijden en de rest van deze handleiding.
  • Is een organisatie opgeschort of beëindigd, dan zien haar mensen dat in het dashboard en kunnen ze niet meer bellen.

Je prijzen

Je betaalt een vaste prijs per onderdeel: per gebruiker per maand voor elk abonnement, per belminuut buiten de bundel, voor de module Workflows per maand, per nummer per maand en per AI-credit. Voor wat we niet hebben afgesproken geldt de gewone prijs. Een nieuwe prijs geldt vanaf de dag die we afspreken. Facturen die al zijn gemaakt, houden de prijs waarmee ze zijn gemaakt. Wat je nu betaalt, zie je met GET /me.

Hoe je wordt gefactureerd

  • Je krijgt één factuur per maand, per e-mail, met een regel per organisatie. Je maand begint op de dag dat je reseller werd, en de maanden van al je organisaties lopen daarmee gelijk.
  • Gebruikers, nummers en modules betaal je vooraf voor de hele maand. Belminuten buiten de bundel betaal je achteraf.
  • Wat je halverwege de maand bijneemt, zoals een nieuwe organisatie, meer gebruikers, een duurder abonnement, een module of een nummer, betaal je naar rato voor de rest van de maand, op de volgende factuur. Wat je afzegt telt vanaf de volgende maand niet meer mee. Voor de lopende maand krijg je niets terug.
  • AI-credits die je toevoegt, zijn meteen te gebruiken en komen in hun geheel op de volgende factuur.
  • Je betaalt per overboeking, onder vermelding van het factuurnummer. Na 7 en 14 dagen krijg je een herinnering. Blijft een factuur 21 dagen open, dan worden al je organisaties opgeschort tot hij betaald is.

De API

Alle aanroepen gaan naar https://api.talkip.nl/reseller/v1, met je sleutel als Bearer-token in de header Authorization. Wat je meestuurt en terugkrijgt is JSON, behalve de pdf van een factuur. Bedragen zijn in eurocent, exclusief btw. Tijden zijn ISO 8601 in UTC.

curl https://api.talkip.nl/reseller/v1/me \
  -H "Authorization: Bearer tk_..."
Sleutel
Begint met tk_ en is 43 tekens lang. Je ziet hem alleen als hij wordt aangemaakt. Bewaar hem zoals je een wachtwoord bewaart.
Limiet
600 aanroepen per minuut per sleutel. Voor organisaties maken, credits toevoegen en nummers kopen geldt daarnaast elk een limiet van 100 per uur.
Fouten
Een foutcode met een JSON-body, zoals { "error": "conflict", "message": "SEATS_BELOW_USAGE_ERROR" }. Klopt de body, een parameter of de query niet, dan is error validation en staat in issues wat er mis is.
400
De body of de parameters kloppen niet.
401
Geen, een onbekende of een ingetrokken sleutel.
403
Niet toegestaan, bijvoorbeeld meer nummers dan het abonnement toestaat of een ander abonnement voor een organisatie op Enterprise.
404
Bestaat niet, is niet van jou of is beëindigd.
409
Kan nu niet, bijvoorbeeld minder gebruikers dan er in gebruik zijn.
429
Te veel aanroepen. Wacht het aantal seconden uit Retry-After (ook in retryAfterSeconds) en probeer het dan opnieuw.

Je account

GET /me

Wie je bent en wat je nu betaalt, per onderdeel, in eurocent exclusief btw.

{
  "id": "01a1...",
  "name": "Acme Telecom",
  "supportEmail": "support@acme.nl",
  "pricesCents": {
    "seat:start": 400, "seat:pro": 800, "seat:business": 1600, "seat:enterprise": 2000,
    "minute": 2, "module:workflows": 2000, "number": 150, "credit": 0.8
  }
}

De prijs van een gebruiker en een nummer is per maand, die van een belminuut en een AI-credit per stuk. Heb je met ons geen vaste prijs per nummer afgesproken, dan is number null en heeft elk nummer zijn eigen prijs. Die zie je bij /numbers/available.

Organisaties

GET /tenants

Al je organisaties die je niet hebt beëindigd, op naam.

{
  "tenants": [
    {
      "id": "01a1...",
      "name": "Bakkerij Jansen",
      "slug": "bakkerij-jansen",
      "sipDomain": "bakkerij-jansen.<sip-domein>",
      "status": "active",
      "suspensionReason": null,
      "plan": "pro",
      "features": { "recording": true, "transcription": true, ... },
      "seats": 3,
      "modules": { "workflows": false },
      "createdAt": "2026-10-17T10:00:00.000Z"
    }
  ]
}

status is active of suspended. Bij suspended is suspensionReason unpaid als een factuur van jou te lang open staat, of admin als wij de organisatie hebben opgeschort. In features staat wat het abonnement toestaat.

POST /tenants

Maakt een organisatie die meteen werkt. Haar gebruikers worden naar rato voor de rest van je maand gerekend.

{
  "name": "Bakkerij Jansen",
  "plan": "pro",
  "seats": 3,
  "ownerEmail": "eigenaar@bakkerijjansen.nl",
  "modules": { "workflows": true }
}
name
De naam, hoogstens 100 tekens. Het kenmerk en het SIP-domein worden daaruit gemaakt.
plan
start, pro of business. Enterprise spreek je met ons af.
seats
Het aantal gebruikers, 1 t/m 10.000. Elk lid en elke openstaande uitnodiging neemt er een in.
ownerEmail
Optioneel. Krijgt een uitnodiging namens jou om de organisatie te beheren, en neemt een plek in.
modules
Optioneel. Met workflows op true staat de module Workflows meteen aan.

Je krijgt 201 met de organisatie zoals bij GET /tenants/:id.

GET /tenants/:tenantId

Eén organisatie, met de plekken die in gebruik zijn, haar nummers en haar AI-credits.

{
  "id": "01a1...",
  "name": "Bakkerij Jansen",
  ...,
  "usedSeats": 2,
  "numbers": [{ "id": "01a1...", "e164": "+31104528311", "purchasedAt": "2026-10-17T10:05:00.000Z" }],
  "credits": { "monthly": 750, "monthlyLeft": 610, "resetsAt": "2026-11-16T23:00:00.000Z", "added": 2500, "total": 3110 }
}

monthly zijn de credits die het abonnement elke maand per gebruiker meebrengt, en monthlyLeft is wat daar nog van over is. Bij resetsAt begint dat opnieuw. added zijn de credits die jij hebt toegevoegd. Die blijven staan tot ze op zijn. total is wat er in totaal te gebruiken is.

PATCH /tenants/:tenantId

Wijzigt de naam, het abonnement of het aantal gebruikers, met dezelfde grenzen als bij POST /tenants. Geef alleen mee wat verandert.

{ "plan": "business", "seats": 5 }

Het aantal gebruikers en de grenzen van het abonnement worden eerst gecontroleerd. Wordt een van beide geweigerd, dan verandert er niets. Je krijgt 409 met SEATS_BELOW_USAGE_ERROR als er meer plekken in gebruik zijn, en met PLAN_LIMITS_EXCEEDED_ERROR als de organisatie meer keuzemenu's, belgroepen of nummers heeft dan het nieuwe abonnement toestaat. Staat de organisatie op Enterprise, dan geeft een ander abonnement 403 met PLAN_MANAGED_ERROR. Lukt het, dan krijg je de organisatie terug zoals ze nu is.

DELETE /tenants/:tenantId

Beëindigt de organisatie. De telefoons bellen meteen niet meer, haar nummers gaan terug, haar modules gaan uit en ze komt niet meer op je facturen. Voor de lopende maand krijg je niets terug, en de belminuten van die maand komen nog op de volgende factuur. Haar gegevens blijven bewaard en haar mensen houden hun account, maar je kunt haar niet meer terughalen. Daarna geeft de API voor deze organisatie 404.

{ "id": "01a1...", "endedAt": "2026-10-17T12:00:00.000Z", "releasedNumbers": ["+31104528311"] }

PUT /tenants/:tenantId/modules/workflows

Zet de module Workflows aan of uit met { "active": true }. Aanzetten wordt naar rato gerekend. Uitzetten gaat meteen in, en je krijgt voor de lopende maand niets terug. Je krijgt { "module": "workflows", "active": true } terug.

POST /tenants/:tenantId/owners

Nodigt nog iemand uit als eigenaar, met { "email": "..." }. Een eigenaar nodigt de rest van de organisatie uit vanuit het dashboard. De uitnodiging neemt een plek in en is 7 dagen geldig. Je krijgt 201 met id, email en expiresAt. Je krijgt 409 met ALREADY_A_MEMBER_ERROR als het adres al lid is, met INVITE_ALREADY_SENT_ERROR als het al een openstaande uitnodiging heeft en met SEATS_EXHAUSTED_ERROR als alle plekken bezet zijn.

AI-credits

POST /tenants/:tenantId/credits

Voegt credits toe, 1 t/m 100.000 per keer, met { "credits": 2500 }. Ze zijn meteen te gebruiken en komen op je volgende factuur. Je krijgt 201 met het saldo, zoals bij credits hierboven.

Nummers

GET /numbers/available

Nummers die je aan een organisatie kunt geven, met wat ze jou per maand kosten. Zoek met ?search=010 op cijfers. Een 0 vooraan staat voor +31. ?limit= is 1 t/m 100, standaard 50.

{ "numbers": [{ "id": "01a1...", "e164": "+31104528311", "monthlyPriceCents": 150 }] }

POST /tenants/:tenantId/numbers

Geeft de organisatie een nummer, met { "numberId": "..." }, naar rato gerekend. Je krijgt 201 met id en e164. Het nummer gaat nog nergens naartoe. De organisatie stelt in haar dashboard in wie er opneemt. Je krijgt 409 met NUMBER_UNAVAILABLE_ERROR als iemand anders het net nam, en 403 met PLAN_LIMIT_REACHED_ERROR als het abonnement geen nummers meer toestaat.

DELETE /tenants/:tenantId/numbers/:numberId

Zegt het nummer op. Het werkt meteen niet meer en komt vanaf de volgende maand niet meer op je factuur. Je krijgt id en e164 van het nummer terug.

Facturen

GET /invoices

Je facturen en creditnota's in invoices, nieuwste eerst. Bij elke factuur staat onder meer number, status, totalCents en in outstandingCents wat er nog open staat.

GET /invoices/:invoiceId

Eén factuur met haar regels in lines. Elke regel noemt in tenantId de organisatie waarvoor hij is, zodat je door kunt factureren.

GET /invoices/:invoiceId/pdf

De pdf zoals hij is gemaild.