Ontwikkelaars

One API

Koppel uw CRM of bedrijfstoepassingen aan uw Interfone-telefonie: gebruikers, lopende oproepen, click-to-call, contacten en webhooks.

https://api.interfone.be/v1/{module}/{account_id}/{resource}

One openen Spreek met een expert

Toegangstokens maakt u aan in One, Instellingen › Ontwikkelaarstools.

Inleiding

Met de One API bestuurt u uw Interfone-account vanuit uw eigen toepassingen: centrales, gebruikers, toestellen, nummers, contacten, lopende oproepen, logboek en webhooks.

Elke route begint met een {module} gevolgd door de ID van uw klantaccount. De beschikbare module is magic-ip.

Een lijst geeft een omhulsel terug: het account, het aantal elementen en de tabel data. Een gepagineerde lijst voegt limit en offset toe. Een detail geeft enkel het object terug.

De teruggegeven ID's zijn die van het telefonieplatform: ze zijn stabiel en u mag ze bewaren.

Basis-URL

https://api.interfone.be/v1/{module}/{account_id}/{resource}

Omhulsel van een lijst

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 2,
  "data": [
    "…"
  ]
}

Omhulsel van een gepagineerde lijst

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 50,
  "limit": 50,
  "offset": 0,
  "data": [
    "…"
  ]
}

Authenticatie

Elke aanvraag draagt een Bearer-token in de Authorization-header. Tokens worden aangemaakt in het blok Authenticatie hierboven en worden slechts één keer getoond.

Een token is gekoppeld aan één account en heeft een bereik: de lijst van modules die het mag lezen. Een account of module buiten het bereik antwoordt 403.

Een ingetrokken token antwoordt 401 vanaf de volgende aanvraag.

Headers

Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Antwoord · 401

{
  "error": "unauthorized",
  "message": "Missing or malformed Bearer token"
}

Antwoord · 403

{
  "error": "forbidden",
  "message": "Token scope does not cover module \"sms\"",
  "scopes": [
    "magic-ip"
  ]
}

Limieten

60 aanvragen per 60 seconden en per token, over alle modules heen.

Daarboven is het antwoord een 429 met de header Retry-After en het veld retry_after : het aantal seconden te wachten voor de teller opnieuw start.

De teller is per token, niet per eindpunt. Pagina's bevatten standaard 50 elementen en maximaal 500.

Antwoord · 429

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "error": "rate_limited",
  "message": "Rate limit exceeded: 60 requests per 60 seconds per token",
  "retry_after": 37
}

Antwoordcodes

Een fout geeft een object terug met een stabiele code error en een message.

Code	error	Betekenis
200		Geslaagd
400	bad_request	Parameter ontbreekt of is ongeldig, het bericht zegt welke
401	unauthorized	Token ontbreekt, is ongeldig of ingetrokken
403	forbidden	Account of module buiten het bereik van het token
404	not_found	Bron niet gevonden
409	conflict	De aanvraag botst met de huidige toestand: contact van een andere bron, geen geregistreerd toestel, adres gedeeld door meerdere gebruikers
429	rate_limited	Debietlimiet bereikt
500	server_error	Serverfout
501	not_implemented	Eindpunt nog niet beschikbaar
502	central_error	Het telefonieplatform heeft de aanvraag geweigerd, zijn bericht wordt ongewijzigd teruggegeven
503	unavailable	Telefonieplatform onbereikbaar

Antwoord · 404

{
  "error": "not_found",
  "message": "User not found"
}

Magic IP

Centrales

Uw telefooncentrales: één per vestiging. Een account heeft er minstens één.

Centrales opsommen

GET/magic-ip/{account_id}/accounts

Het veld id van elke centrale is wat gebruikers en toestellen daarna dragen in account_id. is_primary duidt de hoofdcentrale van het account aan.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/accounts' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 2,
  "data": [
    {
      "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "name": "Siège",
      "realm": "siege.exemple.be",
      "enabled": true,
      "parent_id": null,
      "is_primary": true,
      "created_at": "2024-03-12T09:41:00Z"
    },
    {
      "id": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
      "name": "Atelier",
      "realm": "atelier.exemple.be",
      "enabled": true,
      "parent_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "is_primary": false,
      "created_at": "2025-01-20T14:05:00Z"
    }
  ]
}

Een centrale lezen

GET/magic-ip/{account_id}/accounts/{id}

Parameters

idpad · stringverplicht: ID van de centrale.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/accounts/a1b2c3d4e5f60718293a4b5c6d7e8f90' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Siège",
  "realm": "siege.exemple.be",
  "enabled": true,
  "parent_id": null,
  "is_primary": true,
  "created_at": "2024-03-12T09:41:00Z"
}

Gebruikers

De gebruikers van uw centrales, met hun extensie en rol.

Gebruikers opsommen

GET/magic-ip/{account_id}/users

Alle gebruikers van het account, gesorteerd op naam. De rol is admin of user.

Parameters

account_idquery · string: Beperkt de lijst tot één centrale, aangeduid met de id uit de lijst van centrales.
emailquery · string: Exact e-mailadres, hoofdletterongevoelig.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/users?email=camille@exemple.be' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 1,
  "data": [
    {
      "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "first_name": "Camille",
      "last_name": "Dupont",
      "email": "camille@exemple.be",
      "extension": "201",
      "role": "admin",
      "enabled": true
    }
  ]
}

Een gebruiker lezen

GET/magic-ip/{account_id}/users/{id}

Parameters

idpad · stringverplicht: ID van de gebruiker.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/users/5c6d7e8f90a1b2c3d4e5f60718293a4b' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "first_name": "Camille",
  "last_name": "Dupont",
  "email": "camille@exemple.be",
  "extension": "201",
  "role": "admin",
  "enabled": true
}

Toestellen

De toestellen die op uw centrales geregistreerd zijn, met hun live registratiestatus.

Toestellen opsommen

GET/magic-ip/{account_id}/devices

owner_id draagt de id van de gebruiker aan wie het toestel is toegewezen, of null als het vrij is. registered zegt of het toestel op dit moment geregistreerd is op de centrale. Een DECT-handset heeft geen mac_address.

Deze gegevens worden live op het telefonieplatform gelezen: reken op enkele honderden milliseconden meer, en een 503 als het onbereikbaar is.

Parameters

account_idquery · string: Beperkt de lijst tot één centrale, aangeduid met de id uit de lijst van centrales.
user_idquery · string: Houdt enkel de toestellen van deze gebruiker.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/devices' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 1,
  "data": [
    {
      "id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "name": "SIP-T54W | AABBCCDDEEFF",
      "type": "sip_device",
      "model": "SIP-T54W",
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "owner_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "enabled": true,
      "registered": true
    }
  ]
}

Een toestel lezen

GET/magic-ip/{account_id}/devices/{id}

Parameters

idpad · stringverplicht: ID van het toestel.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/devices/d4e5f60718293a4b5c6d7e8f90a1b2c3' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "SIP-T54W | AABBCCDDEEFF",
  "type": "sip_device",
  "model": "SIP-T54W",
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "owner_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "enabled": true,
  "registered": true
}

Lopende oproepen

De oproepen die op dit moment door uw centrales gaan, live gelezen. Een oproep groepeert zijn takken: die welke de centrale binnenkomt en die welke op uw toestellen rinkelen of spreken.

Lopende oproepen opsommen

GET/magic-ip/{account_id}/live-calls

state is ringing zolang niemand heeft opgenomen, daarna answered. user_id, device_id en extension duiden het toestel van het account aan dat in de oproep zit.

Parameters

account_idquery · string: Beperkt de lijst tot één centrale, aangeduid met de id uit de lijst van centrales.
user_idquery · string: Houdt enkel de oproepen waarin deze gebruiker betrokken is.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/live-calls' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 1,
  "data": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "direction": "inbound",
      "state": "answered",
      "from": "32470123456",
      "to": "3221234567",
      "started_at": "2026-09-13T09:41:12Z",
      "duration_sec": 84,
      "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
      "extension": "201",
      "legs": [
        {
          "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
          "call_id": "7a1c2e3f-sip-0001",
          "direction": "inbound",
          "from": "32470123456",
          "to": "3221234567",
          "answered": true,
          "user_id": null,
          "device_id": null,
          "extension": null
        },
        {
          "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
          "call_id": null,
          "direction": "outbound",
          "from": "32470123456",
          "to": "201",
          "answered": true,
          "user_id": null,
          "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
          "extension": "201"
        }
      ]
    }
  ]
}

Een lopende oproep lezen

GET/magic-ip/{account_id}/live-calls/{id}

Parameters

idpad · stringverplicht: ID van de lopende oproep, of van een van zijn takken.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/live-calls/c0ffee00-1111-4222-8333-444455556666' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "c0ffee00-1111-4222-8333-444455556666",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "direction": "inbound",
  "state": "answered",
  "from": "32470123456",
  "to": "3221234567",
  "started_at": "2026-09-13T09:41:12Z",
  "duration_sec": 84,
  "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
  "extension": "201",
  "legs": [
    {
      "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "call_id": "7a1c2e3f-sip-0001",
      "direction": "inbound",
      "from": "32470123456",
      "to": "3221234567",
      "answered": true,
      "user_id": null,
      "device_id": null,
      "extension": null
    },
    {
      "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
      "call_id": null,
      "direction": "outbound",
      "from": "32470123456",
      "to": "201",
      "answered": true,
      "user_id": null,
      "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
      "extension": "201"
    }
  ]
}

Beschikbaarheid

De status van elke gebruiker op dit moment, afgeleid van zijn geregistreerde toestellen en de lopende oproepen.

Beschikbaarheid opsommen

GET/magic-ip/{account_id}/availability

status is available (een geregistreerd toestel, geen oproep), ringing (een oproep rinkelt op zijn toestel), busy (in gesprek) of offline (geen geregistreerd toestel, of gebruiker uitgeschakeld). Een gsm telt als geregistreerd.

Parameters

account_idquery · string: Beperkt de lijst tot één centrale, aangeduid met de id uit de lijst van centrales.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/availability' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 2,
  "data": [
    {
      "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "extension": "201",
      "status": "busy",
      "registered_devices": 1,
      "call": {
        "id": "c0ffee00-1111-4222-8333-444455556666",
        "direction": "inbound",
        "from": "32470123456",
        "to": "3221234567",
        "since": "2026-09-13T09:41:12Z"
      }
    },
    {
      "user_id": "7e8f90a1b2c3d4e5f60718293a4b5c6d",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "extension": "202",
      "status": "available",
      "registered_devices": 2,
      "call": null
    }
  ]
}

Beschikbaarheid van een gebruiker lezen

GET/magic-ip/{account_id}/users/{id}/availability

Parameters

idpad · stringverplicht: ID van de gebruiker, of zijn e-mailadres. 409 als meerdere gebruikers van het account het adres delen.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/users/5c6d7e8f90a1b2c3d4e5f60718293a4b/availability' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "extension": "201",
  "status": "busy",
  "registered_devices": 1,
  "call": {
    "id": "c0ffee00-1111-4222-8333-444455556666",
    "direction": "inbound",
    "from": "32470123456",
    "to": "3221234567",
    "since": "2026-09-13T09:41:12Z"
  }
}

Click-to-call

Een oproep starten vanaf het vaste toestel van een gebruiker: zijn telefoon rinkelt eerst, daarna kiest de centrale het nummer zodra hij opneemt. Nooit de gsm.

Bellen vanaf het toestel van een gebruiker

POST/magic-ip/{account_id}/users/{id}/dial

number is een extensie of een internationaal nummer zonder +. Zonder device_id neemt de API het enige geregistreerde vaste toestel van de gebruiker, een bureautoestel vóór een applicatie; heeft hij er meerdere, dan antwoordt ze 400 met de kandidaten; heeft hij er geen, 409.

Heeft de gebruiker meerdere toestellen, geef dan device_id mee: antwoord 400 somt de kandidaten op met hun type, en GET /devices?user_id= geeft ze ook. Antwoord 202 bevestigt dat het toestel is aangesproken; de oproep verschijnt daarna in de lopende oproepen met de teruggegeven call_id.

Parameters

idpad · stringverplicht: ID van de gebruiker, of zijn e-mailadres. 409 als meerdere gebruikers van het account het adres delen.
numberbody · stringverplicht: Extensie of internationaal nummer zonder +, bijvoorbeeld 32470123456.
device_idbody · string: Specifiek vast toestel van de gebruiker. 403 als het niet van hem is, 400 als het een gsm is, 409 als het niet geregistreerd is.
auto_answerbody · boolean: true om het toestel zelf te laten opnemen, als de telefoon dat toelaat.

Aanvraag

curl --request POST \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/users/camille@exemple.be/dial' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"number":"32470123456"}'

Antwoord · 202

{
  "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
  "number": "32470123456",
  "call_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "ringing"
}

Oproeplogboek

De beëindigde oproepen, één per gesprek ongeacht het aantal toestellen dat rinkelde, met hun werkelijke richting.

Oproepen opsommen

GET/magic-ip/{account_id}/calls

Standaard de laatste 24 uur, maximaal 31 dagen per aanvraag. direction is de zakelijke richting: een toestel dat een nummer kiest is een uitgaande oproep, ook al ziet de centrale hem binnenkomen. answered zegt of iemand heeft opgenomen.

Parameters

fromquery · date: Begin van het venster, ISO 8601 of JJJJ-MM-DD (volledige dag, UTC).
toquery · date: Einde van het venster, ISO 8601 of JJJJ-MM-DD. Standaard nu.
directionquery · string: inbound of outbound.
numberquery · string: Nummer of extensie aan één kant van de oproep, vergeleken op de cijfers.
account_idquery · string: Beperkt de lijst tot één centrale, aangeduid met de id uit de lijst van centrales.
limitquery · integer: Aantal elementen per pagina, standaard 50, maximaal 500.
offsetquery · integer: Aantal over te slaan elementen, standaard 0.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/calls?from=2026-09-13&to=2026-09-13&direction=inbound' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 2,
  "limit": 50,
  "offset": 0,
  "from": "2026-09-13T00:00:00.000Z",
  "to": "2026-09-13T23:59:59.000Z",
  "data": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "direction": "inbound",
      "from": "32470123456",
      "to": "3221234567",
      "started_at": "2026-09-13T09:41:12Z",
      "duration_sec": 143,
      "answered": true,
      "hangup_cause": "NORMAL_CLEARING",
      "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "extension": "201",
      "legs": 3
    },
    {
      "id": "deadbeef-2222-4333-8444-555566667777",
      "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "direction": "outbound",
      "from": "202",
      "to": "32470999999",
      "started_at": "2026-09-13T08:15:03Z",
      "duration_sec": 31,
      "answered": true,
      "hangup_cause": "NORMAL_CLEARING",
      "user_id": "7e8f90a1b2c3d4e5f60718293a4b5c6d",
      "extension": "202",
      "legs": 2
    }
  ]
}

Een oproep lezen

GET/magic-ip/{account_id}/calls/{id}

De oproep moet binnen het venster from / to vallen, standaard de laatste 24 uur.

Parameters

idpad · stringverplicht: ID van de oproep.
fromquery · date: Begin van het venster, ISO 8601 of JJJJ-MM-DD (volledige dag, UTC).
toquery · date: Einde van het venster, ISO 8601 of JJJJ-MM-DD. Standaard nu.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/calls/c0ffee00-1111-4222-8333-444455556666?from=2026-09-13' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "c0ffee00-1111-4222-8333-444455556666",
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "direction": "inbound",
  "from": "32470123456",
  "to": "3221234567",
  "started_at": "2026-09-13T09:41:12Z",
  "duration_sec": 143,
  "answered": true,
  "hangup_cause": "NORMAL_CLEARING",
  "user_id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
  "extension": "201",
  "legs": 3
}

Sluitingsknop

De uitzonderlijke sluiting van de centrale, die de codes *561 en *562 vanaf een toestel activeren.

De status lezen

GET/magic-ip/{account_id}/closure

installed zegt of de knop op dit account is geplaatst, closed of hij actief is. Zolang hij actief is, volgen de oproepen de tak « gesloten » van het hoofdscenario.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/closure' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "installed": true,
  "closed": false,
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "close_code": "*561",
  "open_code": "*562"
}

Sluiten of heropenen

PUT/magic-ip/{account_id}/closure

closed op true sluit, op false heropent. Het antwoord geeft de nieuwe status zoals gelezen op de centrale. 404 als de knop niet geïnstalleerd is.

Parameters

closedbody · booleanverplicht: true om te sluiten, false om te heropenen.

Aanvraag

curl --request PUT \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/closure' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"closed":true}'

Antwoord · 200

{
  "installed": true,
  "closed": true,
  "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "close_code": "*561",
  "open_code": "*562"
}

Contacten

Het adresboek van het account, dat de toestellen tonen wanneer een bekend nummer belt. Een contact dat via de API wordt gepusht, verschijnt op de telefoons bij hun volgende lezing van het adresboek.

Contacten opsommen

GET/magic-ip/{account_id}/contacts

Alle contacten van het account, ongeacht hun oorsprong, gesorteerd op naam. total is het totale aantal, count dat van de pagina.

Parameters

searchquery · string: Tekst gezocht in de naam, het bedrijf of het e-mailadres.
numberquery · string: Nummer aanwezig op het contact, vergeleken op de cijfers.
external_idquery · string: Uw ID, zoals opgegeven bij het aanmaken.
sourcequery · string: api voor contacten van de API, local voor die ingevoerd in One.
limitquery · integer: Aantal elementen per pagina, standaard 50, maximaal 500.
offsetquery · integer: Aantal over te slaan elementen, standaard 0.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts?search=dupont' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 2,
  "total": 2,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "external_id": "crm-10421",
      "name": "Camille Dupont",
      "first_name": "Camille",
      "last_name": "Dupont",
      "company": "Exemple SRL",
      "type": "individual",
      "email": "camille@exemple.be",
      "phone": "3221234567",
      "mobile": "32470123456",
      "language": "fr",
      "street": "Rue de l'Exemple 12",
      "zip_code": "1000",
      "city": "Bruxelles",
      "country": "BE",
      "source": "api",
      "created_at": "2026-09-01T10:00:00Z",
      "updated_at": "2026-09-14T08:12:00Z"
    },
    {
      "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "external_id": null,
      "name": "Sam Peeters",
      "first_name": "Sam",
      "last_name": "Peeters",
      "company": null,
      "type": "individual",
      "email": null,
      "phone": null,
      "mobile": "32470999999",
      "language": null,
      "street": null,
      "zip_code": null,
      "city": null,
      "country": null,
      "source": "local",
      "created_at": "2026-06-20T09:00:00Z",
      "updated_at": "2026-06-20T09:00:00Z"
    }
  ]
}

Een contact lezen

GET/magic-ip/{account_id}/contacts/{id}

Parameters

idpad · stringverplicht: ID van het contact.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "external_id": "crm-10421",
  "name": "Camille Dupont",
  "first_name": "Camille",
  "last_name": "Dupont",
  "company": "Exemple SRL",
  "type": "individual",
  "email": "camille@exemple.be",
  "phone": "3221234567",
  "mobile": "32470123456",
  "language": "fr",
  "street": "Rue de l'Exemple 12",
  "zip_code": "1000",
  "city": "Bruxelles",
  "country": "BE",
  "source": "api",
  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-09-14T08:12:00Z"
}

Een contact aanmaken

POST/magic-ip/{account_id}/contacts

Vereist een naam, een voor- en achternaam, of een bedrijf, en minstens één nummer. Nummers worden in de gangbare vormen aanvaard en internationaal zonder + teruggegeven.

Met een reeds gekende external_id wordt het contact vervangen in plaats van gedupliceerd, antwoord 200 met created op false. Dat is de sleutel van een synchronisatie vanuit uw CRM.

Parameters

external_idbody · string: Uw ID van het contact in uw CRM. Laat toe het terug te vinden en te vervangen zonder duplicaat.
first_namebody · string: Voornaam.
last_namebody · string: Achternaam.
companybody · string: Bedrijf. Alleen, maakt het een contact van het type business.
phonebody · string: Vast nummer, bijvoorbeeld 02 123 45 67 of 3221234567.
mobilebody · string: Mobiel nummer, bijvoorbeeld 0470 12 34 56.
emailbody · string: E-mailadres.
typebody · string: individual of business. Afgeleid indien afwezig.
languagebody · string: Taalcode van twee letters, fr of nl.
street, zip_code, city, countrybody · string: Postadres, facultatief.

Aanvraag

curl --request POST \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"external_id":"crm-10421","first_name":"Camille","last_name":"Dupont","company":"Exemple SRL","phone":"02 123 45 67","mobile":"+32 470 12 34 56","email":"camille@exemple.be","language":"fr"}'

Antwoord · 201

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "external_id": "crm-10421",
  "name": "Camille Dupont",
  "first_name": "Camille",
  "last_name": "Dupont",
  "company": "Exemple SRL",
  "type": "individual",
  "email": "camille@exemple.be",
  "phone": "3221234567",
  "mobile": "32470123456",
  "language": "fr",
  "street": "Rue de l'Exemple 12",
  "zip_code": "1000",
  "city": "Bruxelles",
  "country": "BE",
  "source": "api",
  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-09-14T08:12:00Z",
  "created": true
}

Een contact wijzigen

PATCH/magic-ip/{account_id}/contacts/{id}

Enkel de verzonden velden veranderen; null wist. Een contact dat niet via de API is aangemaakt, antwoordt 409: het behoort tot zijn bron.

Parameters

idpad · stringverplicht: ID van het contact.

Aanvraag

curl --request PATCH \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"mobile":"0470 99 99 99","city":"Namur"}'

Antwoord · 200

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "external_id": "crm-10421",
  "name": "Camille Dupont",
  "first_name": "Camille",
  "last_name": "Dupont",
  "company": "Exemple SRL",
  "type": "individual",
  "email": "camille@exemple.be",
  "phone": "3221234567",
  "mobile": "32470999999",
  "language": "fr",
  "street": "Rue de l'Exemple 12",
  "zip_code": "1000",
  "city": "Namur",
  "country": "BE",
  "source": "api",
  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-09-14T09:30:00Z"
}

Een contact verwijderen

DELETE/magic-ip/{account_id}/contacts/{id}

Enkel een contact dat via de API is aangemaakt; anders 409.

Parameters

idpad · stringverplicht: ID van het contact.

Aanvraag

curl --request DELETE \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "deleted": true
}

Een reeks importeren

POST/magic-ip/{account_id}/contacts/batch

Tot 1 000 contacten per aanroep, elk met een external_id: aangemaakt als ze nieuw zijn, anders vervangen. Het antwoord detailleert wat mislukt is, regel per regel, zonder de rest te blokkeren.

Het adresboek van de toestellen wordt één keer aan het einde van de reeks opnieuw gegenereerd. Voor een eerste volledige synchronisatie: reeksen van 1 000 na elkaar.

Parameters

contactsbody · arrayverplicht: Lijst van contacten, dezelfde velden als bij het aanmaken, external_id verplicht.

Aanvraag

curl --request POST \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/contacts/batch' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"contacts":[{"external_id":"crm-10421","first_name":"Camille","last_name":"Dupont","phone":"3221234567"},{"external_id":"crm-10422","company":"Atelier Exemple","phone":"3281234567"}]}'

Antwoord · 200

{
  "received": 2,
  "created": 1,
  "updated": 1,
  "failed": []
}

Webhooks

One verwittigt uw server op de seconde dat een oproep rinkelt, wordt opgenomen of eindigt, om een pop-up in uw CRM te tonen of de oproep er te loggen. Eén abonnement per account: elke gebeurtenis draagt de betrokken gebruiker, met e-mail en extensie, en uw CRM stuurt de pop-up naar de juiste agent. call_id is dezelfde op alle gebeurtenissen van een oproep; het is de ID van zijn oorspronkelijke tak, die deze tak ook draagt in de lopende oproepen. Nummers zijn internationaal zonder +.

Gebeurtenis call.ringing

{
  "id": "c8f1e2d3-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.ringing",
  "created_at": "2026-09-14T09:41:12Z",
  "account_id": "{account_id}",
  "data": {
    "call_id": "2a9455565c7627856719a8f0530a0101",
    "direction": "inbound",
    "from": "32470123456",
    "to": "3221234567",
    "user": {
      "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "email": "camille@exemple.be",
      "first_name": "Camille",
      "last_name": "Dupont",
      "extension": "201"
    },
    "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
    "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "timestamp": "2026-09-14T09:41:12Z"
  }
}

Gebeurtenis call.ended

{
  "id": "d9a2f3e4-5b6c-4d7e-9f0a-1b2c3d4e5f6a",
  "type": "call.ended",
  "created_at": "2026-09-14T09:43:40Z",
  "account_id": "{account_id}",
  "data": {
    "call_id": "2a9455565c7627856719a8f0530a0101",
    "direction": "inbound",
    "from": "32470123456",
    "to": "3221234567",
    "user": {
      "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
      "email": "camille@exemple.be",
      "first_name": "Camille",
      "last_name": "Dupont",
      "extension": "201"
    },
    "device_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
    "account_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "timestamp": "2026-09-14T09:43:40Z",
    "answered": true,
    "duration_sec": 148,
    "hangup_cause": "NORMAL_CLEARING"
  }
}

Headers van elke levering

X-One-Event: call.ringing
X-One-Delivery: c8f1e2d3-4a5b-4c6d-8e9f-0a1b2c3d4e5f
X-One-Timestamp: 1789378872
X-One-Signature: sha256=<HMAC-SHA256(secret, timestamp + "." + body)>

Abonnementen opsommen

GET/magic-ip/{account_id}/webhooks

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 1,
  "data": [
    {
      "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "name": "CRM Exemple",
      "url": "https://crm.exemple.be/hooks/one",
      "events": [
        "call.ringing",
        "call.answered",
        "call.ended"
      ],
      "enabled": true,
      "secret_prefix": "whsec_3f9a1c",
      "failure_count": 0,
      "last_delivery_at": "2026-09-14T09:41:14Z",
      "last_status_code": 200,
      "created_at": "2026-09-14T08:00:00Z",
      "updated_at": "2026-09-14T08:00:00Z"
    }
  ]
}

Een abonnement aanmaken

POST/magic-ip/{account_id}/webhooks

Vier gebeurtenissen: call.ringing (een inkomende oproep rinkelt op het toestel van een gebruiker, één gebeurtenis per rinkelend toestel), call.started (een gebruiker kiest een nummer), call.answered (iemand heeft opgenomen), call.ended (de oproep is beëindigd, met duur en resultaat). Standaard allemaal.

Het geheim wordt enkel bij het aanmaken getoond. Elke levering is ondertekend: X-One-Signature is sha256= gevolgd door de HMAC-SHA256 van het geheim over timestamp.body. Uw server moet binnen 10 seconden 2xx antwoorden; anders probeert One nog twee keer, na 3 en 10 seconden. Maximaal 5 abonnementen per account.

Parameters

urlbody · stringverplicht: Publieke https-URL van uw server.
eventsbody · array: Lijst uit call.ringing, call.started, call.answered, call.ended. Allemaal indien afwezig.
namebody · string: Vrije naam, om ze uit elkaar te houden.

Aanvraag

curl --request POST \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://crm.exemple.be/hooks/one","events":["call.ringing","call.answered","call.ended"],"name":"CRM Exemple"}'

Antwoord · 201

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "CRM Exemple",
  "url": "https://crm.exemple.be/hooks/one",
  "events": [
    "call.ringing",
    "call.answered",
    "call.ended"
  ],
  "enabled": true,
  "secret_prefix": "whsec_3f9a1c",
  "failure_count": 0,
  "last_delivery_at": null,
  "last_status_code": null,
  "created_at": "2026-09-14T08:00:00Z",
  "updated_at": "2026-09-14T08:00:00Z",
  "secret": "whsec_3f9a1c…"
}

Een abonnement lezen

GET/magic-ip/{account_id}/webhooks/{id}

Parameters

idpad · stringverplicht: ID van het abonnement.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks/5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "CRM Exemple",
  "url": "https://crm.exemple.be/hooks/one",
  "events": [
    "call.ringing",
    "call.answered",
    "call.ended"
  ],
  "enabled": true,
  "secret_prefix": "whsec_3f9a1c",
  "failure_count": 0,
  "last_delivery_at": "2026-09-14T09:41:14Z",
  "last_status_code": 200,
  "created_at": "2026-09-14T08:00:00Z",
  "updated_at": "2026-09-14T08:00:00Z"
}

Een abonnement wijzigen

PATCH/magic-ip/{account_id}/webhooks/{id}

Enkel de verzonden velden veranderen. enabled op false schort de leveringen op zonder iets te verliezen.

Parameters

idpad · stringverplicht: ID van het abonnement.
enabledbody · boolean: false schort de leveringen op.

Aanvraag

curl --request PATCH \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks/5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{"events":["call.ringing"],"enabled":true}'

Antwoord · 200

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "CRM Exemple",
  "url": "https://crm.exemple.be/hooks/one",
  "events": [
    "call.ringing"
  ],
  "enabled": true,
  "secret_prefix": "whsec_3f9a1c",
  "failure_count": 0,
  "last_delivery_at": "2026-09-14T09:41:14Z",
  "last_status_code": 200,
  "created_at": "2026-09-14T08:00:00Z",
  "updated_at": "2026-09-14T08:00:00Z"
}

Een abonnement verwijderen

DELETE/magic-ip/{account_id}/webhooks/{id}

Parameters

idpad · stringverplicht: ID van het abonnement.

Aanvraag

curl --request DELETE \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks/5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "deleted": true
}

Een testgebeurtenis sturen

POST/magic-ip/{account_id}/webhooks/{id}/test

Levert een ondertekende ping-gebeurtenis aan de URL van het abonnement en geeft het resultaat: 200 als uw server 2xx antwoordde, anders 502.

Parameters

idpad · stringverplicht: ID van het abonnement.

Aanvraag

curl --request POST \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks/5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a/test' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{}'

Antwoord · 200

{
  "subscription_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "delivery_id": "e0b3a4f5-6c7d-4e8f-a0b1-2c3d4e5f6a7b",
  "status": "delivered",
  "attempts": 1,
  "status_code": 200,
  "error": null
}

Leveringen opsommen

GET/magic-ip/{account_id}/webhooks/{id}/deliveries

De laatste leveringen, van recent naar oud, met hun status, het aantal pogingen en de laatst ontvangen code.

Parameters

idpad · stringverplicht: ID van het abonnement.
limitquery · integer: Aantal leveringen, standaard 50, maximaal 100.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/webhooks/5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a/deliveries?limit=20' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "subscription_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "count": 2,
  "data": [
    {
      "id": "d9a2f3e4-5b6c-4d7e-9f0a-1b2c3d4e5f6a",
      "event_type": "call.ended",
      "call_id": "2a9455565c7627856719a8f0530a0101",
      "status": "delivered",
      "attempts": 1,
      "last_status_code": 200,
      "last_error": null,
      "created_at": "2026-09-14T09:43:40Z",
      "delivered_at": "2026-09-14T09:43:41Z"
    },
    {
      "id": "c8f1e2d3-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "event_type": "call.ringing",
      "call_id": "2a9455565c7627856719a8f0530a0101",
      "status": "failed",
      "attempts": 3,
      "last_status_code": 503,
      "last_error": "HTTP 503",
      "created_at": "2026-09-14T09:41:12Z",
      "delivered_at": null
    }
  ]
}

Nummers

De vaste nummers die aan uw centrales zijn toegewezen.

Nummers opsommen

GET/magic-ip/{account_id}/numbers

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/numbers' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "account": {
    "id": "{account_id}",
    "name": "Exemple SRL"
  },
  "count": 1,
  "data": [
    {
      "did_e164": "3221234567",
      "did_national": "021234567",
      "name": "Accueil",
      "status": "assigned",
      "assigned_to_ip_line_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "assigned_at": "2024-03-12T10:02:00Z"
    }
  ]
}

Een nummer lezen

GET/magic-ip/{account_id}/numbers/{e164}

Parameters

e164pad · stringverplicht: Nummer in internationaal formaat zonder +, bijvoorbeeld 3221234567.

Aanvraag

curl --request GET \
  --url 'https://api.interfone.be/v1/magic-ip/{account_id}/numbers/3221234567' \
  --header 'Authorization: Bearer one_xxxxxxxxxxxxxxxxxxxxxxxx'

Antwoord · 200

{
  "did_e164": "3221234567",
  "did_national": "021234567",
  "name": "Accueil",
  "status": "assigned",
  "assigned_to_ip_line_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "assigned_at": "2024-03-12T10:02:00Z",
  "is_private": false
}