MAGDA Persoon | skryvdocs

Inleiding

Persoonsgebonden informatie ophalen uit het rijksregister en andere gerelateerde bronnen. Denk daarbij aan domicilie, gezinssamenstelling of afstammingsgegevens.

Use cases

Automatisch vooraf invullen van persoonsgegevens in een aanvraagformulier.
Controle op adreswijziging in functie van terugvordering premie.
Valideren of een aanvrager op een bepaald adres gedomicilieerd is (adrescheck).
Bepalen van gezinssamenstelling voor rechtentoekenning (bv. reductietarieven of toelagen).
Raadplegen van historische gegevens om wijzigingen doorheen de tijd te auditen (naam/adres/burgerlijke staat).
Opzoeken van bewoners op een adres voor plaatsgebonden communicatie of inspecties.

Setup

Idem als bij alle MAGDA-connectoren. Zie MAGDA algemene setup.

Specifieke applicatie eigenschappen

Specifieke applicatie eigenschappen, los van de eigenschappen die de toegang regelen.

GeefPersoon

Eigenschap	Default	Beschrijving
`skryv.connectors.magda.geef.persoon.bron`	-	Databron (bijvoorbeeld `rr` = rijksregister, `ksz` = kruispuntbank sociale zekerheid)
`skryv.connectors.magda.geef.persoon.taal`	`nl`	Taal

Eigenschap

Default

Beschrijving

skryv.connectors.magda.geef.persoon.bron

Databron (bijvoorbeeld rr = rijksregister, ksz = kruispuntbank sociale zekerheid)

skryv.connectors.magda.geef.persoon.taal

nl

Taal

GeefHistoriekPersoon

GHP heeft als enige SOAP-service ook een kong-api-key in de SSL-config.

Eigenschap	Default	Beschrijving
`skryv.connectors.magda.ghp.persoon.bron`	-	Databron (bijvoorbeeld `rr` = rijksregister, `ksz` = kruispuntbank sociale zekerheid)
`skryv.connectors.magda.ghp.persoon.taal`	`nl`	Taal

Eigenschap

Default

Beschrijving

skryv.connectors.magda.ghp.persoon.bron

Databron (bijvoorbeeld rr = rijksregister, ksz = kruispuntbank sociale zekerheid)

skryv.connectors.magda.ghp.persoon.taal

nl

Taal

GeefGezinssamenstelling

Eigenschap	Default	Beschrijving
`skryv.connectors.magda.gfc.taal`	`nl`	Taal

GeefHistoriekGezinssamenstelling

Eigenschap	Default	Beschrijving
`skryv.connectors.magda.ghfc.taal`	`nl`	Taal

Services en functies

Overzicht

Functie	Retourtype	Info
geefPersoon geefPersoonWithUri	`GeefPersoonResponse`	Basis persoonsgegevens
geefPersoonWithAfstammingWithUri	`GeefPersoonResponse`	Persoonsgegevens met info over ouders
geefPersoonWithUriAsHM	`HashMap`	Basis persoonsgegevens als HashMap
giveFamilyComposition	`GeefGezinssamenstellingResponse`	Persoonsgegevens met gezinssamenstelling
giveHistoryFamilyCompositionWithUri	`GeefGezinssamenstellingResponse`	Persoonsgegevens met historiek gezinssamenstelling
giveHistoryPerson	`GeefHistoriekPersoonResponse`	Persoonsgegevens met historiek
searchPersonByAddress	`ZoekPersoonOpAdresResponse`	Persoonsgegevens op basis van domicilie

Elke functie hieronder is, naast de workflow expressie, ook rechtstreeks aanroepbaar vanuit Java-code door MagdaCamundaConnector (bean magda) te injecteren in je klasse. Zie MAGDA gebruik voor een volledig voorbeeld met dependency injection. De "Java-code"-snippets per functie tonen enkel de effectieve aanroep zelf.

geefPersoon

Zoek persoonsgegevens op basis van een rijksregisternummer. Een eenvoudige toepassing van deze functie kan je configureren via een specifieke Skryv Studio workflow template.

Workflow expressie

${magda.geefPersoon(String identifier, String dossierId)}

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven:

${magda.geefPersoonWithUri(String identifier, String uri, String hoedanigheid, String dossierId)}

Java-code

GeefPersoonResponse response = magda.geefPersoon(identifier, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`identifier`	String	‘85010212345’	Rijksregisternummer
`uri` (withUri variant)	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid` (withUri variant)	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefPersoon-02.02

Ouput

Gepseudonimiseerd voorbeeld geboortegegevens:

<Geboorte DatumBegin="1976-09-14">
    <Datum>1976-09-14</Datum>
    <Plaats>
        <Gemeente>
            <NISCode>44021</NISCode>
            <Naam>Gent</Naam>
        </Gemeente>
        <Land>
            <NISCode>150</NISCode>
            <ISOCode>BEL</ISOCode>
            <Naam>BELGIE</Naam>
        </Land>
    </Plaats>
    <Aktenummer>00142</Aktenummer>
    <Bewijsstuk>
        <Code>1</Code>
        <Omschrijving Taal="nl">Akte van de burgerlijke stand</Omschrijving>
    </Bewijsstuk>
</Geboorte>

Gepseudonimiseerd voorbeeld burgerlijke staat gegevens:

<BurgerlijkeStaten>
    <BurgerlijkeStaat DatumBegin="2005-06-18">
        <Code>20</Code>
        <Omschrijving Taal="nl">Gehuwd</Omschrijving>
        <Partner>
            <INSZ>77032544821</INSZ>
            <Naam DatumBegin="2005-06-18">
                <Achternamen>
                    <Achternaam>Pieters</Achternaam>
                </Achternamen>
                <Voornamen>
                    <Voornaam>An</Voornaam>
                </Voornamen>
            </Naam>
            <Geslacht>
                <Code>2</Code>
                <Omschrijving Taal="nl">Vrouwelijk</Omschrijving>
            </Geslacht>
            <Geboortedatum>1977-03-25</Geboortedatum>
        </Partner>
        <Plaats>
            <Gemeente>
                <NISCode>21004</NISCode>
                <Naam>Brussel</Naam>
            </Gemeente>
            <Land>
                <NISCode>150</NISCode>
                <ISOCode>BEL</ISOCode>
                <Naam>BELGIE</Naam>
            </Land>
        </Plaats>
        <Aktenummer>00587</Aktenummer>
    </BurgerlijkeStaat>
</BurgerlijkeStaten>

Gepseudonimiseerd voorbeeld domiciliegegevens:

<Hoofdverblijfplaats DatumBegin="2015-03-21">
    <NietGestandaardiseerdeStraatnaam>
        <String>Kerkstraat</String>
        <Taal>nl</Taal>
    </NietGestandaardiseerdeStraatnaam>
    <Huisnummer>12</Huisnummer>
    <Busnummer>3</Busnummer>
    <PostCode>9000</PostCode>
    <NietGestandaardiseerdeGemeentenaam>
        <String>Gent</String>
        <Taal>nl</Taal>
    </NietGestandaardiseerdeGemeentenaam>
    <NISCodeGemeente>44021</NISCodeGemeente>
    <Land>
        <String>BELGIE</String>
        <Taal>nl</Taal>
    </Land>
    <NISCodeLand>150</NISCodeLand>
    <ISOCodeLand>BEL</ISOCodeLand>
    <StraatCode>0145</StraatCode>
</Hoofdverblijfplaats>

Gepseudonimiseerd voorbeeld naamsgegevens:

<Naam DatumBegin="1976-09-14">
    <Achternamen>
        <Achternaam>De Smedt</Achternaam>
        <Achternaam>Van den Berghe</Achternaam>
    </Achternamen>
    <Voornamen>
        <Voornaam>Jean</Voornaam>
        <Voornaam>Pierre</Voornaam>
        <Voornaam GebruikelijkeVoornaam="1">Luc</Voornaam>
    </Voornamen>
</Naam>

Error-handling

Speficieke foutcodes:

Code	Toelichting
30003	Onbestaand INSZ
30001	Geen gegevens gevonden voor de vraag
20002	INSZ in de vraag heeft een ongeldige structuur
60009	Er heeft zich een technisch probleem voorgedaan

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30003".equals(code) || "30001".equals(code)) {
        throw new BpmnError("MAGDA_PERSOON_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("60009".equals(code)) {
        throw new BpmnError("MAGDA_TECHNISCHE_FOUT", u.getDiagnose());
    }
}

geefPersoonWithAfstammingWithUri

Zoek persoonsgegevens met afstammingsgegevens op basis van rijksregisternummer.

Workflow expressie

${magda.geefPersoonWithAfstammingWithUri(String identifier, String uri, String hoedanigheid, String dossierId)}

Java-code

GeefPersoonResponse response = magda.geefPersoonWithAfstammingWithUri(identifier, uri, hoedanigheid, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`identifier`	String	‘85010212345’	Rijksregisternummer (INSZ) van de persoon waarvan je de gegevens wil opvragen
`uri`	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid`	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefPersoon-02.02

Output

Je krijgt een getypeerd GeefPersoonResponse-object terug. Dit object bevat een Persoon-element met persoonsgegevens zoals aangeleverd door MAGDA vanuit het Rijksregister (RR) of de Kruispuntbank van de Sociale Zekerheid (KSZ), afhankelijk van de geconfigureerde bron en de machtigingen van je applicatie. Het Afstamming-element bevat nul, één of twee Ouder-elementen. Er wordt steeds slechts één afstamming teruggegeven: die met de recentste begindatum. Voor een volledig historisch overzicht van alle afstammingen raadpleeg je de giveHistoryPerson-service.

Gepseudonimiseerd voorbeeld afstammingsgegevens:

<Afstamming>
    <Type>
        <Code>00</Code>
        <Omschrijving Taal="nl">wettig kind</Omschrijving>
    </Type>
    <Ouders>
        <Ouder>
            <INSZ>01234567993</INSZ>
            <Naam>
                <Achternamen><Achternaam>De Bruyker</Achternaam></Achternamen>
                <Voornamen><Voornaam>Jean</Voornaam></Voornamen>
            </Naam>
            <Geslacht>
                <Code>1</Code>
                <Omschrijving Taal="nl">Mannelijk</Omschrijving>
            </Geslacht>
            <Geboortedatum>1931-08-22</Geboortedatum>
            <IsOverleden>false</IsOverleden>
        </Ouder>
        <Ouder>
            <INSZ IsFictief="1">34100300000</INSZ>
            <Naam>
                <Achternamen><Achternaam>Vandamme</Achternaam></Achternamen>
                <Voornamen>
                    <Voornaam>Maria</Voornaam>
                    <Voornaam>Ingrid</Voornaam>
                </Voornamen>
            </Naam>
            <Geslacht>
                <Code>2</Code>
                <Omschrijving Taal="nl">Vrouwelijk</Omschrijving>
            </Geslacht>
            <Geboortedatum>1934-10-03</Geboortedatum>
            <IsOverleden>false</IsOverleden>
        </Ouder>
    </Ouders>
</Afstamming>

Error-handling

Speficieke foutcodes:

Code	Toelichting
30003	Onbestaand INSZ
30001	Geen gegevens gevonden voor de vraag
20002	INSZ in de vraag heeft een ongeldige structuur
60009	Er heeft zich een technisch probleem voorgedaan

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30003".equals(code) || "30001".equals(code)) {
        throw new BpmnError("MAGDA_PERSOON_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("60009".equals(code)) {
        throw new BpmnError("MAGDA_TECHNISCHE_FOUT", u.getDiagnose());
    }
}

geefPersoonWithUriAsHM

Zoek persoonsgegevens op basis van rijksregisternummer en krijg deze binnen als Java hashmap.

Workflow expressie (Camunda connector)

${magda.geefPersoonWithUriAsHM(String identifier, String uri, String hoedanigheid, String dossierId)}

Java-code

HashMap response = magda.geefPersoonWithUriAsHM(identifier, uri, hoedanigheid, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`identifier`	String	‘85010212345’	Rijksregisternummer
`uri`	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid`	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefPersoon-02.02

Output

Je krijgt de persoonsgegevens terug als een HashMap<String, Object> in plaats van als een getypeerd GeefPersoonResponse-object. Dit maakt het eenvoudiger om individuele velden rechtstreeks aan te spreken in een BPMN-expressie of workflow-variabele, zonder dat je afhankelijk bent van de Java-typestructuur.

De hashmap weerspiegelt de structuur van het Persoon-object zoals gedefinieerd door MAGDA. Afhankelijk van de geconfigureerde bron (RR of KSZ) en de specifieke machtigingen van je applicatie kunnen de beschikbare velden variëren. De sleutels in de hashmap komen overeen met de elementnamen uit de MAGDA-respons, bijvoorbeeld:

// Naam opvragen
String achternaam = (String) response.get("Naam");

// Geboortedatum opvragen
Map<String, Object> geboorte = (Map<String, Object>) response.get("Geboorte");

// Hoofdverblijfplaats opvragen
Map<String, Object> adressen = (Map<String, Object>) response.get("Adressen");
Map<String, Object> hoofdverblijfplaats = (Map<String, Object>) adressen.get("Hoofdverblijfplaats");

Error-handling

Speficieke foutcodes:

Code	Toelichting
30003	Onbestaand INSZ
30001	Geen gegevens gevonden voor de vraag
20002	INSZ in de vraag heeft een ongeldige structuur
60009	Er heeft zich een technisch probleem voorgedaan

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30003".equals(code) || "30001".equals(code)) {
        throw new BpmnError("MAGDA_PERSOON_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("60009".equals(code)) {
        throw new BpmnError("MAGDA_TECHNISCHE_FOUT", u.getDiagnose());
    }
}

giveFamilyComposition

Zoek gegevens over gezinssamenstelling op basis van een rijksregisternummer.

Workflow expressie

${magda.giveFamilyComposition(String ssin, String dossierId)}

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven:

${magda.giveFamilyCompositionWithUri(String ssin, String uri, String hoedanigheid, String dossierId)}

Java-code

GeefGezinssamenstellingResponse response = magda.giveFamilyCompositionWithUri(ssin, uri, hoedanigheid, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`ssin`	String	‘85010212345’	Rijksregisternummer
`uri` (withUri variant)	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid` (withUri variant)	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefGezinssamenstelling-02.02

Output

Je krijgt een object GeefGezinssamenstellingResponse terug met info over de gezinssamenstelling.

Gepseudonimiseerd voorbeeld gezinssamenstelling:

<Gezinsleden>
<!-- Echtgenote / partner -->
<Gezinslid DatumBegin="2005-06-18">
    <INSZ>77032544821</INSZ>
    <Naam DatumBegin="2005-06-18">
        <Achternamen>
            <Achternaam>Pieters</Achternaam>
        </Achternamen>
        <Voornamen>
            <Voornaam>An</Voornaam>
        </Voornamen>
    </Naam>
    <Geslacht DatumBegin="1977-03-25">
        <Code>2</Code>
        <Omschrijving Taal="nl">Vrouwelijk</Omschrijving>
    </Geslacht>
    <Geboortedatum>1977-03-25</Geboortedatum>
    <Positie>
        <Code>02</Code>
        <Omschrijving Taal="nl">echtgenoot, echtgenote</Omschrijving>
    </Positie>
    <Woonvorm>
        <Code>01</Code>
        <Omschrijving Taal="nl">kerngezin</Omschrijving>
    </Woonvorm>
</Gezinslid>

<!-- Kind -->
<Gezinslid DatumBegin="2007-03-14">
    <INSZ>07031455832</INSZ>
    <Naam DatumBegin="2007-03-14">
        <Achternamen>
            <Achternaam>Janssen</Achternaam>
        </Achternamen>
        <Voornamen>
            <Voornaam>Emma</Voornaam>
        </Voornamen>
    </Naam>
    <Geslacht DatumBegin="2007-03-14">
        <Code>2</Code>
        <Omschrijving Taal="nl">Vrouwelijk</Omschrijving>
    </Geslacht>
    <Geboortedatum>2007-03-14</Geboortedatum>
    <Positie>
        <Code>03</Code>
        <Omschrijving Taal="nl">zoon, dochter</Omschrijving>
    </Positie>
    <Woonvorm>
        <Code>01</Code>
        <Omschrijving Taal="nl">kerngezin</Omschrijving>
    </Woonvorm>
</Gezinslid>

<!-- Kind dat het gezin verlaten heeft (DatumEinde aanwezig) -->
<Gezinslid DatumBegin="2009-11-02" DatumEinde="2031-09-01">
    <INSZ>09110266543</INSZ>
    <Naam DatumBegin="2009-11-02">
        <Achternamen>
            <Achternaam>Janssen</Achternaam>
        </Achternamen>
        <Voornamen>
            <Voornaam>Luca</Voornaam>
        </Voornamen>
    </Naam>
    <Geslacht DatumBegin="2009-11-02">
        <Code>1</Code>
        <Omschrijving Taal="nl">Mannelijk</Omschrijving>
    </Geslacht>
    <Geboortedatum>2009-11-02</Geboortedatum>
    <Positie>
        <Code>03</Code>
        <Omschrijving Taal="nl">zoon, dochter</Omschrijving>
    </Positie>
    <Woonvorm>
        <Code>01</Code>
        <Omschrijving Taal="nl">kerngezin</Omschrijving>
    </Woonvorm>
</Gezinslid>
</Gezinsleden>

Error-handling

Specifieke foutcodes:

Code	Toelichting
30003	Onbestaand INSZ
30001	Geen gegevens gevonden voor de vraag
20002	INSZ in de vraag heeft een ongeldige structuur
40005	De toegang tot de gegevens is geweigerd
16018	Gegevens uit externe bron zijn niet beschikbaar

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30003".equals(code) || "30001".equals(code)) {
        throw new BpmnError("MAGDA_GEZIN_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("40005".equals(code) || "16018".equals(code)) {
        throw new BpmnError("MAGDA_BRON_NIET_BESCHIKBAAR", u.getDiagnose());
    }
}

giveHistoryFamilyComposition

Zoek gegevens over historiek van gezinssamenstelling op basis van een rijksregisternummer.

Workflow expressie

${magda.giveHistoryFamilyComposition(String ssin, String date, String on, String dossierId)}

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven:

${magda.giveHistoryFamilyCompositionWithUri(String ssin, String date, String on, String uri, String hoedanigheid, String dossierId)}

Java-code

GeefGezinssamenstellingResponse response = magda.giveHistoryFamilyCompositionWithUri(ssin, date, on, uri, hoedanigheid, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`ssin`	String	‘85010212345’	Rijksregisternummer
`date`	String	‘2010-06-30’	Startdatum referteperiode, geef alle gezinssamenstellingen sinds dat moment
`on`	String	‘2020-01-01’	Refertedatum, geef de gezinssamenstelling zoals die op dat moment was
`uri` (withUri-variant)	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid` (withUri-variant)	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefHistoriekGezinssamenstelling-02.02

Output

Je krijgt een getypeerd GeefHistoriekGezinssamenstellingResponse object met de historiek van de gezinssamenstelling. Het kan ofwel gaan om een snapshot (input parameter on) of een tijdlijn (input parameter date).

Gepseudonimiseerd voorbeeld (tijdslijn).

<ns2:GeefHistoriekGezinssamenstellingResponse xmlns:ns2="http://www.vlaanderen.be/MAGDA">

    <!-- Context -->
    <Context>
        <Tijdstip>2026-05-21T14:00:00Z</Tijdstip>
        <CorrelatieID>2f0c5df2-5562-4fd9-bb88-abc987654321</CorrelatieID>
        <Bron>GHG</Bron>
    </Context>

    <!-- Referte -->
    <Referte>
        <UwReferte>550e8400-e29b-41d4-a716-446655440000</UwReferte>
        <Applicatie>SkryvApp</Applicatie>
    </Referte>

    <!-- Antwoord -->
    <Antwoord>

        <Inhoud>

            <!-- Gezinssamenstelling 1 (historiek) -->
            <Gezinssamenstellingen>

                <Gezinssamenstelling DatumBegin="2010-06-30" DatumEinde="2015-12-31">

                    <Gezinsleden>

                        <Gezinslid>
                            <INSZ>850102XXX45</INSZ>
                            <Naam>DEMO JAN</Naam>
                            <GeboorteDatum>1985-01-02</GeboorteDatum>
                            <Geslacht>1</Geslacht>
                            <RelatieTotReferentie>PERSOON</RelatieTotReferentie>
                        </Gezinslid>

                        <Gezinslid>
                            <INSZ>870505XXX12</INSZ>
                            <Naam>DEMO ANNA</Naam>
                            <GeboorteDatum>1987-05-05</GeboorteDatum>
                            <Geslacht>2</Geslacht>
                            <RelatieTotReferentie>PARTNER</RelatieTotReferentie>
                        </Gezinslid>

                    </Gezinsleden>

                </Gezinssamenstelling>

            </Gezinssamenstellingen>

            <!-- Gezinssamenstelling 2 -->
            <Gezinssamenstellingen>

                <Gezinssamenstelling DatumBegin="2016-01-01">

                    <Gezinsleden>

                        <Gezinslid>
                            <INSZ>850102XXX45</INSZ>
                            <Naam>DEMO JAN</Naam>
                            <GeboorteDatum>1985-01-02</GeboorteDatum>
                            <Geslacht>1</Geslacht>
                            <RelatieTotReferentie>PERSOON</RelatieTotReferentie>
                        </Gezinslid>

                        <Gezinslid>
                            <INSZ>870505XXX12</INSZ>
                            <Naam>DEMO ANNA</Naam>
                            <GeboorteDatum>1987-05-05</GeboorteDatum>
                            <Geslacht>2</Geslacht>
                            <RelatieTotReferentie>PARTNER</RelatieTotReferentie>
                        </Gezinslid>

                        <Gezinslid>
                            <INSZ>160303XXX77</INSZ>
                            <Naam>DEMO LISA</Naam>
                            <GeboorteDatum>2016-03-03</GeboorteDatum>
                            <Geslacht>2</Geslacht>
                            <RelatieTotReferentie>KIND</RelatieTotReferentie>
                        </Gezinslid>

                    </Gezinsleden>

                </Gezinssamenstelling>

            </Gezinssamenstellingen>

        </Inhoud>

        <!-- Optioneel -->
        <Uitzonderingen>
            <Uitzondering>
                <Code>INFO_PARTIAL_HISTORY</Code>
                <Omschrijving>Historiek beperkt tot beschikbare gegevens</Omschrijving>
            </Uitzondering>
        </Uitzonderingen>

    </Antwoord>

</ns2:GeefHistoriekGezinssamenstellingResponse>

Error-handling

Specifieke foutcodes:

Code	Oorsprong	Toelichting
30003	KSZ	Onbestaand INSZ
30001	MAGDA/KSZ	Geen gegevens gevonden voor de vraag
30002	KSZ	INSZ geannuleerd
20002	MAGDA	INSZ in de vraag heeft een ongeldige structuur
40005	KSZ	De toegang tot de gegevens is geweigerd
30004	MAGDA	Persoon heeft een nieuw INSZ verkregen (WAARSCHUWING, met annotaties Oud/Nieuw INSZ)

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30003".equals(code) || "30001".equals(code) || "30002".equals(code)) {
        throw new BpmnError("MAGDA_HISTORIEK_GEZIN_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("30004".equals(code)) {
        // WAARSCHUWING, geen blokkerende fout - annotaties bevatten Oud/Nieuw INSZ
        LOGGER.warn("Persoon heeft nieuw INSZ verkregen: {}", u.getDiagnose());
    }
}

giveHistoryPerson

Geef historische persoonsgegevens op basis van een rijksregisternummer.

Workflow expressie

${magda.giveHistoryPerson(String identifier, String date, String oneDay, String dossierId)}

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven:

${magda.giveHistoryPersonWithUri(String identifier, String date, String oneDay, String uri, String hoedanigheid, String dossierId)}

Java-code

GeefHistoriekPersoonResponse response = magda.giveHistoryPersonWithUri(identifier, date, oneDay, uri, hoedanigheid, dossierId);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`identifier`	String	‘85010212345’	Rijksregisternummer
`date`	String	‘2010-06-30’	Indien oneDay ‘true’ is, dan is dit de refertedatum; indien oneDay ‘false', dan is dit de startdatum van de referteperiode
`oneDay`	String	‘true' of ‘false’	‘true’ betekent de historische persoonsgegevens op die exacte dag (zie date); ‘false’ betekent historische persoonsgegevens vanaf die dag (zie date)
`uri` (withUri-variant)	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid` (withUri-variant)	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.
`dossierId`	String (GUID)	'550e8400-e29b-41d4-a716-446655440000'	Unieke id van het dossier binnen de Skryv-applicatie. Wordt gebruikt voor logging van de MAGDA-call.

MAGDA-documentatie

Technische documentatie voor Persoon.GeefHistoriekPersoon-02.02

Output

Je krijgt een getypeerd GeefHistoriekPersoonResponse object met historische persoonsgegevens. Het kan gaan om een snapshot (oneDay = true), ofwel om een tijdslijn (oneDay = false). Zo krijg je zicht op de sleutelmomenten en -gebeurtenissen in iemands leven (bijvoorbeeld geboorte, huwelijk, verhuis). De aard van informatie is afhankelijk van de geconfigureerde bron en de machtigingen van je applicatie.

Gepseudonimiseerd voorbeeld (tijdslijn):

<ns2:GeefHistoriekPersoonResponse xmlns:ns2="http://www.vlaanderen.be/MAGDA">

    <!-- Context -->
    <Context>
        <Tijdstip>2026-05-21T13:45:00Z</Tijdstip>
        <CorrelatieID>9c31d7ea-bd88-4a9a-a111-abc123456789</CorrelatieID>
        <Bron>GHP</Bron>
    </Context>

    <!-- Referte -->
    <Referte>
        <UwReferte>550e8400-e29b-41d4-a716-446655440000</UwReferte>
        <Applicatie>SkryvApp</Applicatie>
    </Referte>

    <!-- Antwoord -->
    <Antwoord>

        <Inhoud>

            <HistoriekPersoon Bron="RR">

                <INSZ>850102XXX45</INSZ>

                <!-- Historiek Naam -->
                <HistoriekNaam>
                    <Naam DatumBegin="1985-01-02">
                        <Achternamen>
                            <Achternaam>DEMO</Achternaam>
                        </Achternamen>
                        <Voornamen>
                            <Voornaam>JAN</Voornaam>
                        </Voornamen>
                    </Naam>

                    <Naam DatumBegin="2015-06-01">
                        <Achternamen>
                            <Achternaam>DEMO-VERANDERD</Achternaam>
                        </Achternamen>
                        <Voornamen>
                            <Voornaam>JAN</Voornaam>
                        </Voornamen>
                    </Naam>
                </HistoriekNaam>

                <!-- Historiek Geslacht -->
                <HistoriekGeslacht>
                    <Geslacht DatumBegin="1985-01-02">
                        <Code>1</Code>
                        <Omschrijving>Mannelijk</Omschrijving>
                    </Geslacht>
                </HistoriekGeslacht>

                <!-- Historiek Geboorte -->
                <HistoriekGeboorte>
                    <Geboorte>
                        <Datum>1985-01-02</Datum>
                        <Plaats>
                            <Gemeente>
                                <Naam>BRUGGE</Naam>
                                <NISCode>31005</NISCode>
                            </Gemeente>
                            <Land>
                                <ISOCode>BEL</ISOCode>
                                <Naam>België</Naam>
                            </Land>
                        </Plaats>
                    </Geboorte>
                </HistoriekGeboorte>

                <!-- Historiek Nationaliteit -->
                <HistoriekNationaliteit>
                    <Nationaliteit DatumBegin="1985-01-02">
                        <Code>150</Code>
                        <Omschrijving>België</Omschrijving>
                    </Nationaliteit>
                </HistoriekNationaliteit>

                <!-- Historiek Adressen -->
                <HistoriekAdressen>
                    <HistoriekHoofdverblijfplaats>
                        <Hoofdverblijfplaats DatumBegin="2000-01-01" DatumEinde="2010-05-31">
                            <Straatcode>1234</Straatcode>
                            <Huisnummer>5</Huisnummer>
                            <Postcode>9000</Postcode>
                            <Gemeente>GENT</Gemeente>
                        </Hoofdverblijfplaats>

                        <Hoofdverblijfplaats DatumBegin="2010-06-01">
                            <Straatcode>5678</Straatcode>
                            <Huisnummer>10</Huisnummer>
                            <Busnummer>1</Busnummer>
                            <Postcode>8000</Postcode>
                            <Gemeente>BRUGGE</Gemeente>
                        </Hoofdverblijfplaats>
                    </HistoriekHoofdverblijfplaats>
                </HistoriekAdressen>

                <!-- Historiek Burgerlijke Staat -->
                <HistoriekBurgerlijkeStaat>
                    <BurgerlijkeStaat DatumBegin="2008-09-20">
                        <Code>20</Code>
                        <Omschrijving>Gehuwd</Omschrijving>
                    </BurgerlijkeStaat>
                </HistoriekBurgerlijkeStaat>

            </HistoriekPersoon>

        </Inhoud>

        <!-- Optioneel -->
        <Uitzonderingen>
            <Uitzondering>
                <Code>INFO_PARTIAL_DATA</Code>

Error-handling

Specifieke foutcodes:

Code	Oorsprong	Toelichting
12506	MAGDA	INSZ van de gebruiker beantwoordt niet aan de vormvereisten
20002	MAGDA/KSZ/RR	INSZ in de vraag heeft een ongeldige structuur
30001	KSZ/RR	Geen gegevens gevonden voor de vraag
30003	KSZ	Onbestaand INSZ
30002	KSZ	INSZ geannuleerd
30004	MAGDA	Persoon heeft een nieuw INSZ verkregen
40005	KSZ/RR	De toegang tot de gegevens is geweigerd
40006	KSZ/RR	Fout in autorisatie
60009	MAGDA/RR	Er heeft zich een technisch probleem voorgedaan

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30001".equals(code) || "30003".equals(code)) {
        throw new BpmnError("MAGDA_HISTORIEK_NIET_GEVONDEN", u.getDiagnose());
    }
    if ("30002".equals(code)) {
        throw new BpmnError("MAGDA_INSZ_GEANNULEERD", u.getDiagnose());
    }
    if ("12506".equals(code) || "20002".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIG_INSZ", u.getDiagnose());
    }
    if ("60009".equals(code)) {
        throw new BpmnError("MAGDA_TECHNISCHE_FOUT", u.getDiagnose());
    }
}

searchPersonByAddress

Zoek persoonsgegevens op basis van een adres.

Workflow expressie

Variant waarbij de magda aansluitingsgegevens expliciet worden meegegeven.

${magda.searchPersonByAddress(String postCode, String streetCode, String houseNumber, String busNumber, String uri, String hoedanigheid)}

Java-code

ZoekPersoonOpAdresResponse response = magda.searchPersonByAddress(postCode, streetCode, houseNumber, busNumber, uri, hoedanigheid);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`postCode`	String	‘8000’	Postcode adres
`streetCode`	String	‘67890’	Straatcode (CRAB Stratenlijst)
`houseNumber`	String	'1'	Huisnummer
`busNumber`	String	'5'	Eventueel busnummer
`uri`	String	'https://authenticatie.vlaanderen.be/op/v1/afnemers/mijnOrganisatie'	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`hoedanigheid`	String	‘12345’	IPDC-code die je aansluitingsrechten identificeert.

MAGDA-documentatie

Technische documentatie voor Persoon.ZoekPersoonOpAdres-02.02

Output

Je krijgt een getypeerd object ZoekPersoonOpAdresResponseobject terug met persoonsgegevens voor het opgegeven adres (domicilie). Voor elke persoon ingeschreven op het adres, krijg je specifieke informatie terug, afhankelijk van de geconfigureerde bron en de machtigingen van je applicatie.

Gepseudonimiseerd voorbeeld van de response:

<ns2:ZoekPersoonOpAdresResponse xmlns:ns2="http://www.vlaanderen.be/MAGDA">
    
    <!-- Context -->
    <Context>
        <Tijdstip>2026-05-21T13:30:15Z</Tijdstip>
        <CorrelatieID>c84f9c2e-8b8b-4f7e-9a21-123456789abc</CorrelatieID>
        <Bron>SPOA</Bron>
    </Context>

    <!-- Referte -->
    <Referte>
        <UwReferte>REQ-20260521-0001</UwReferte>
        <Applicatie>TestClient</Applicatie>
    </Referte>

    <!-- Antwoord -->
    <Antwoord>

        <Personen>

            <Persoon Bron="RR">
                <INSZ>850101XXX01</INSZ>

                <Naam>
                    <Achternaam>DEMO</Achternaam>
                    <Voornaam>JAN</Voornaam>
                </Naam>

                <Geslacht>1</Geslacht>

                <GeboorteDatum>1985-01-01</GeboorteDatum>

                <Register>Bevolkingsregister</Register>

                <Adressen>
                    <Hoofdverblijfplaats>
                        <Straatcode>1234</Straatcode>
                        <Huisnummer>10</Huisnummer>
                        <Busnummer>1</Busnummer>
                        <Postcode>8000</Postcode>
                        <Gemeente>BRUGGE</Gemeente>
                    </Hoofdverblijfplaats>
                </Adressen>

            </Persoon>

            <Persoon Bron="KSZ">
                <INSZ>920305XXX44</INSZ>

                <Naam>
                    <Achternaam>VOORBEELD</Achternaam>
                    <Voornaam>ANNA</Voornaam>
                </Naam>

                <Geslacht>2</Geslacht>

                <GeboorteDatum>1992-03-05</GeboorteDatum>

                <IsOverleden>false</IsOverleden>

                <Beheerder>
                    <Code>11002</Code>
                    <Omschrijving>Stad Brugge</Omschrijving>
                </Beheerder>

                <Status>
                    <Code>ACTIEF</Code>
                </Status>

                <Register>Bevolkingsregister</Register>

                <Adressen>
                    <Hoofdverblijfplaats>
                        <Straatcode>1234</Straatcode>
                        <Huisnummer>10</Huisnummer>
                        <Busnummer>1</Busnummer>
                        <Postcode>8000</Postcode>
                        <Gemeente>BRUGGE</Gemeente>
                    </Hoofdverblijfplaats>
                </Adressen>

            </Persoon>

        </Personen>

        <!-- Optioneel: uitzonderingen -->
        <Uitzonderingen>
            <Uitzondering>
                <Code>WAARSCHUWING_MAX_RESULTATEN</Code>
                <Omschrijving>Niet alle resultaten worden weergegeven</Omschrijving>
            </Uitzondering>
        </Uitzonderingen>

    </Antwoord>

</ns2:ZoekPersoonOpAdresResponse>

Error-handling

Specifieke foutcodes:

Code	Type	Toelichting
30001	FOUT	Geen gegevens gevonden voor de vraag
40006	FOUT	Fout in autorisatie
40012	FOUT	Fout in opgegeven zoekcriteria: ongekende postcode
40013	FOUT	Fout in opgegeven zoekcriteria: straatcode en huisnummer moeten verschillend van nul zijn
40014	WAARSCHUWING	Er zijn bijkomende resultaten beschikbaar voor de opgegeven zoekcriteria (met annotatie "Huidige pagina")

Voor een compleet overzicht, kan je terecht op de MAGDA-foutcodepagina.

Bij sommige errors wil je het proces niet laten vastlopen. In dat geval vorm je de technische error (foutcode) om naar een BPMN-error en vang je deze op via een error boundary event.

List<UitzonderingType> uitzonderingen = response.getRepliek()
    .getAntwoorden().getAntwoord().getUitzonderingen().getUitzondering();

for (UitzonderingType u : uitzonderingen) {
    String code = u.getIdentificatie();
    if ("30001".equals(code)) {
        throw new BpmnError("MAGDA_GEEN_PERSONEN_GEVONDEN", u.getDiagnose());
    }
    if ("40012".equals(code) || "40013".equals(code)) {
        throw new BpmnError("MAGDA_ONGELDIGE_ZOEKCRITERIA", u.getDiagnose());
    }
    if ("40006".equals(code)) {
        throw new BpmnError("MAGDA_AUTORISATIE_FOUT", u.getDiagnose());
    }
}