Doel en gebruik van de COR API.md

Doel en gebruik van de COR API

De Centrale OIN Raadpleegvoorziening is te bevragen via een REST API. Met de API kunnen de OIN’s van geregistreerde organisaties worden opgevraagd en de organisatienamen bij bestaande OIN’s worden opgezocht.

De COR API biedt de volgende services aan:

  • Opvragen OIN en organisatienamen zonder parameters
  • Opvragen OIN en organisaties met parameters
  • Opvragen enkele organisatie
  • Opvragen laatste wijziging op de COR database

Voor het opvragen van organisaties kan gefilterd worden op: OIN, naam, status, organisatie code, organisatie Type en KvK nummer. Deze filters kunnen gecombineerd worden.

Vanaf versie 1.1 retourneert de COR API in HAL+JSON formaat.

Organisaties worden getoond met de volgende gegevens:

  1. oin: OIN van de organisatie
  2. naam: Naam van de organisatie
  3. status: Status van de organisatie (Actief of Ingetrokken)
  4. kvkNummer: KvK nummer van de organisatie
  5. organisatieCode: Organisatiecode van een organisatie. Alleen gevuld voor gemeenten (bron https://rvig.nl ), provincies en waterschappen/hoogheemraadschappen (bron https://cbs.nl).
  6. organisatieType – Type van de organisatie. Alleen als organisatie een gemeente (type=GM), provincie (type=PV) of waterschap of hoogheemraadschap is (type=WS)
  7. afgifteDatum – Afgiftedatum van het OIN van de organisatie
  8. laatstAangepastDatum – Laatst datum waarop het OIN van de organisatie is aangepast
  9. intrekdatum – Datum waarop het OIN van de organisatie is ingetrokken.
  10. hoofdOin – Details van de organisatie met het hoofdOIN (wanneer de organisatie een subOIN heeft)
  11. subOINs – Lijst met details van de organisaties met subOINs (wanneer de organisatie een hoofdOIN heeft)

Samen met de bovengenoemde informatie wordt ook de HAL informatie doorgegeven. Deze bestaat uit de onderstaande gegevens:

  1. _links: Dit is de parent tag voor HAL content. Het bevat de onderstaande details.
  2. self: Dit is de informatie over de resource die momenteel wordt benaderd. Het bevat de attributen ‘href’ en ‘type’.
  3. href: Dit bevat de URL waarmee de huidige resource kan worden benaderd. Het kan ook worden gebruikt als een referentie naar de parent tag waaronder deze wordt vermeld (ook wel ‘next’)
  4. type: Dit beschrijft het content type van de opgevraagde resources.

De HAL informatie bevat ook pagineringsinformatie zoals hieronder beschreven:

  1. first: Dit bevat informatie voor het verkrijgen van toegang tot de eerste pagina van de opgehaalde resultaten.
  2. prev: Dit bevat informatie voor het verkrijgen van toegang tot de vorige pagina van de opgehaalde resultaten.
  3. next: Dit bevat informatie voor het verkrijgen van toegang tot de volgende pagina van de opgehaalde resultaten.
  4. last: Dit bevat informatie voor het verkrijgen van toegang tot de laatste pagina van de opgehaalde resultaten.

Alle services maken gebruik van onderstaande statuscodes:

  1. 200: Wanneer een request succesvol is en een response beschikbaar is.
  2. 400: Wanneer een request fout is gegaan of ongeldige parameters zijn meegegeven.
  3. 404: Wanneer er geen resultaten voor een request zijn of een verkeerde URL is ingevoerd:
  4. 405: Wanneer een request niet via de methode GET wordt gedaan.
  5. 406: Wanneer de ‘Accept’ header in het request niet ‘application/json’ is terwijl dit wel : dt gevraagd.
  6. 500: Wanneer zich een interne server fout heeft voorgedaan.

Er zijn enkele custom response headers die met een response worden meegestuurd:

  1. X-API-Version: De huidige versie van de COR API die wordt ondervraagd
  2. X-Total-Count: Het totale aantal resultaten van de huidige zoekopdracht
  3. X-Pagination-Count: Het totale aantal pagina’s voor de huidige zoekopdracht
  4. X-Pagination-Page: De huidige pagina die opgevraagd is voor de zoekopdracht
  5. X-Pagination-Limit: Het maximale limiet van 30 per pagina zoals dat is bepaald door de applicatie.

Er zijn twee request headers die naar de server moeten worden gestuurd:

  1. Accept: Deze header specificeert het gewenste format van de response. De applicatie ondersteunt momenteel application/hal+json. Deze header is verplicht.
  2. Accept-Version: Deze header specificeert welke versie van de service de client wil benaderen. Op dit moment biedt de applicatie versie 1.0 en 1.1 aan. 1.1 is de default waarde. Deze header is optioneel.

Standaarden

Service beschrijving

Opvragen organisaties zonder parameters

Omschrijving Deze service geeft de gegevens van alle organisaties terug met de status “actief” of “ingetrokken”.
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s) https://portaal.digikoppeling.nl/registers/api/v1/organisaties

Parameters organisaties met parameters

Beschrijving Parameter Details
OIN nummer oin OIN nummer is 20 cijfers lang. Het betreft hier een ‘equals’ conditie, dus moet het complete OIN nummer van de organisatie worden meegegeven om een resultaat te krijgen
Organisatienaam naam Het betreft hier een ‘equals’ conditie, dus moet de complete organisatienaam van de organisatie worden meegegeven om een resultaat te krijgen.
Status van het OIN status Geaccepteerde waardes zijn ‘Actief’ en ‘Ingetrokken’
Organisatiecode organisatieCode De organisatiecode moet 4 karakters lang zijn. Het betreft hier een ‘equals’ conditie, dus moet de complete organisatiecode van de organisatie worden meegegeven om een resultaat te krijgen1.
Organisatie Type organisatieType Het organisatietype moet 2 karakters lang zijn. Het betreft hier een ‘equals’ conditie, dus moet het complete organisatietype van de organisatie worden meegegeven om een resultaat te krijgen1.
KVK-nummer van de organisatie kvkNummer KVKnummer van de organisatie moet 8 cijfers lang zijn. Het betreft hier een ‘equals’ conditie, dus moet het complete KVK-nummer van de organisatie worden meegegeven om een resultaat te krijgen.
Vrije-tekst zoeken zoek Er wordt gezocht op een match met organisatienaam, OIN of afkorting. Het betreft hier een ‘like’ conditie. Hier kunnen deze ook delen van nummers en woorden worden ingevoerd om zoekresultaten terug te krijgen
“lazy” en “eager” laden van relaties expand Deze parameter kan worden gebruikt om alle details van geassocieerde subOins of het hoofdOin van de Organisatie op te vragen. Als de waarde ‘false’ is worden alleen de OIN nummers voor de betreffende organisaties opgehaald. Als de waarde ‘true’ is worden alle details opgehaald. Default: ‘false’.
Paginering pagina Deze parameter wordt gebruikt om de betreffende pagina op te halen. Het maximale aantal resultaten per pagina is ingesteld op 30. De geldige waarden zijn 1 en waarden hoger dan 1.

1Alleen gemeentelijke organisaties (GM), provincies (PV) en waterschappen/hoogheemraadschappen (WS) kennen een organisatiecode en -type. Voor de overige organisaties in het OIN register zijn deze waarden niet ingevuld.

Opvragen enkele organisatie

Omschrijving Deze service geeft alle gegevens van een specifieke organisatie terug op basis van de meegegeven OIN
URL https://portaal.digikoppeling.nl/registers/api/v1/organisaties/<oin>
HTTP method GET
Headers Accept = application/HAL+json
Voorbeelden
Gebruik zonder parameter https://portaal.digikoppeling.nl/registers/api/v1/organisaties/12345678901234567890
Gebruik met parameter https://portaal.digikoppeling.nl/registers/api/v1/organisaties/12345678901234567890?expand=true

Parameters enkele organisatie

Beschrijving Parameter Details
“lazy” en “eager” laden van relaties expand Deze parameter kan worden gebruikt om alle details van geassocieerde subOINs of het hoofdOin van de organisatie op te vragen. Als de waarde ‘false’ is worden alleen de OIN nummers voor de betreffende organisaties opgehaald. Als de waarde ‘true’ is worden alle details opgehaald. Default: ‘false’.

Opvragen organisaties met parameters

Omschrijving Deze service geeft de gegevens van alle organisaties terug met de status “actief” of “ingetrokken”.
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s) https://portaal.digikoppeling.nl/registers/api/v1/organisaties

Opvragen organisaties veld(en) selectie

Omschrijving Deze service retourneert een specifieke selectie aan velden van de geselecteerde organisatie(s).
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties?fields=<veld1>,<veld2>,...
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s)
Eén veld https://portaal.digikoppeling.nl/registers/api/v1/organisaties?fields=naam
Eén veld met paginering https://portaal.digikoppeling.nl/registers/api/v1/organisaties?fields=naam&pagina=5
Meerdere velden https://portaal.digikoppeling.nl/registers/api/v1/organisaties?fields=naam,oin,kvkNummer
Merk op dat de gespecifieerde velden case sensitive zijn en exact moeten matchen met (parameter)velden uit onderstaande lijst. Verder worden lege (afwezige) velden niet getoond. Bij een enkel leeg veld wordt dus alleen de hoofdlink getoond.

Parameters (fields) organisaties veld(en) selectie

Beschrijving Parameter Details
OIN nummer oin Het volledige OIN nummer van 20 cijfers lang wordt weergegeven in het antwoord.
Organisatienaam naam Het antwoord bevat de volledige naam van de organisatie.
OIN nummer oin Het volledige OIN nummer van 20 cijfers lang wordt weergegeven in het antwoord.
Status van OIN status Weergegeven waarden zijn ‘Actief’ en ‘Ingetrokken’.
Organisatiecode organisatieCode De organisatiecode van 4 karakters die wordt weergegeven in het antwoord van de query.
Organisatietype organisatieType Het organisatietype van 2 karakters wordt weergegeven in het antwoord in de query.
KVK-nummer van de organisatie kvkNummer Het KVKnummer van de organisatie (8 cijfers lang) wordt weergegeven in het antwoord van de query.
Afgiftedatum afgifteDatum Datum van wijziging die door het systeem is vastgesteld.
Laatste wijziging organisatie gegevens laatstAangepastDatum Datum van invoering of wijziging die door het systeem is vastgesteld.
Organisatie OIN referentie hoofdOIN Overzichtslijst met URL’s van alle (hoofd)OIN’s uit het OIN register.
Organisatie subOIN referenties subOINs Overzichtslijst met URL’s van (hoofd)OIN’s uit het OIN register met onderliggende suboins indien aanwezig.
Geldigheid intrekdatum intrekDatum Datum van plaatsing van de organisatie in status "Ingetrokken"
1Alleen gemeentelijke organisaties (GM), provincies (PV), waterschappen/hoogheemraadschappen (WS) en ministeries(MNRE) kennen op dit moment een organisatiecode en -type. Voor de overige organisaties in het OIN register zijn deze waarden niet ingevuld.

Organisaties vrije tekst zoeken

Omschrijving Er kan worden gezocht op een match met organisatienaam, OIN of afkorting.
Hiervoor kunnen ook delen van nummers en woorden worden ingevoerd.
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties?zoek=<zoektekst>
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s)
Specifieke tekst https://portaal.digikoppeling.nl/registers/api/v1/organisaties?zoek=ministerie van algemene zaken
Partiële tekst OIN nummer/td> https://portaal.digikoppeling.nl/registers/api/v1/organisaties?zoek=03214394
Merk op dat te specificeren tekst niet omgeven hoeft te worden met enkele of dubbele quotes.

Parameters organisaties Vrije-tekst zoeken

Beschrijving Parameter Details
Zoek functie van het OIN register zoek Hiermee wordt het zoek endpoint van de COR geselecteerd.

Opvragen laatste wijziging op de COR database

Omschrijving Deze service toont de datum-tijd van de laatste wijziging in de database van de COR applicatie.
De gebuiker kan zo zien of er sinds de laatste synchronisatieslag nog gegevens zijn gewijzigd in de COR.
URL https://portaal.digikoppeling.nl/registers/api/v1/laatsteWijziging
HTTP method GET
Headers Accept = application/HAL+json
Voorbeeld https://portaal.digikoppeling.nl/registers/api/v1/laatsteWijziging

voorbeelden response berichten

Voorbeeld response bericht bevragen van organisaties

{
  "_links": {
    "self": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=10",
      "type": "application/hal+json"
    },
    "first": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=1",
      "type": "application/hal+json"
    },
    "prev": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=9",
      "type": "application/hal+json"
    },
    "next": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=11",
      "type": "application/hal+json"
    },
    "last": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=31",
      "type": "application/hal+json"
    }
  },
  "organisaties": [
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001234567891000",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001234567891000",
      "naam": "Gemeente Test",
      "status": "Actief",
      "kvkNummer": "12345678",
      "organisatieCode": "0163",
      "organisatieType": "GM",
      "afgifteDatum": "2009-12-10T23:00:00Z",
      "laatstAangepastDatum": "2016-05-26T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001234561259000",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001234561259000",
      "naam": "Gemeente Sluis",
      "status": "Actief",
      "kvkNummer": null,
      "organisatieCode": "1234",
      "organisatieType": "GM",
      "afgifteDatum": "2014-06-04T22:00:00Z",
      "laatstAangepastDatum": "2014-08-25T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001001600123456",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001001600123456",
      "naam": "Gemeente Test A",
      "status": "Actief",
      "kvkNummer": null,
      "organisatieCode": "9999",
      "organisatieType": "GM",
      "afgifteDatum": "2010-03-07T23:00:00Z",
      "laatstAangepastDatum": "2014-07-02T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
  ]
}

Voorbeeld response bericht voor bevragen van een organisatie met parameter expand=true

{
    "_links": {
        "self": {
            "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002811223344007?expand=true",
            "type": "application/hal+json"
        }
    },
    "organisaties": [
        {
            "_links": {
                "self": {
                    "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002811223344007",
                    "type": "application/hal+json"
                }
            },
            "oin": "00000002811223344007",
            "naam": "Midden Test",
            "status": "Actief",
            "kvkNummer": "17155555",
            "organisatieCode": null,
            "organisatieType": null,
            "afgifteDatum": "2014-10-29T23:00:00Z",
            "laatstAangepastDatum": "2014-12-29T23:00:00Z",
            "intrekDatum": null,
            "hoofdOIN": {
                "_links": {
                    "self": {
                        "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001111111111000",
                        "type": "application/hal+json"
                    }
                },
                "oin": "00000001111111111000",
                "naam": "Noordoost-Test",
                "status": "Actief",
                "kvkNummer": "10000000",
                "organisatieCode": null,
                "organisatieType": null,
                "afgifteDatum": "2014-10-29T23:00:00Z",
                "laatstAangepastDatum": "2014-12-28T23:00:00Z",
                "intrekDatum": null,
                "hoofdOIN": null,
                "subOINs": null
            },
            "subOINs": null
        }
    ]
}

Voorbeeld response bericht voor bevragen van een organisatie met parameter expand=false

{
    "_links": {
        "self": {
            "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002222222222222",
            "type": "application/hal+json"
        }
    },
    "organisaties": [
        {
            "_links": {
                "self": {
                    "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002222222222222",
                    "type": "application/hal+json"
                }
            },
            "oin": "00000002811415454007",
            "naam": "Midden Test",
            "status": "Actief",
            "kvkNummer": "17888888",
            "organisatieCode": null,
            "organisatieType": null,
            "afgifteDatum": "2014-10-29T23:00:00Z",
            "laatstAangepastDatum": "2014-12-29T23:00:00Z",
            "intrekDatum": null,
            "hoofdOIN": {
                "_links": {
                    "self": {
                        "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001111111111000",
                        "type": "application/hal+json"
                    }
                }
            },
            "subOINs": null
        }
    ]
}