Skip to main content
Nederlands
Nederlands

Retrieving data via API user

Through a Polaris API connection, various data can be retrieved from Polaris. By means of API calls, data can be retrieved from Polaris via a number of standard views or custom connectors, for example for use in a Data Warehouse environment. This article describes the options for how the data can be retrieved.

OAuth

To use this functionality, it is necessary for BCS to create a (system) user based on OAuth2 authentication. In Polaris, the linked user can subsequently be found as an API-user type under Beheer|Gebruiker.

A role and a population can then be linked to the Polaris API user to grant access to the standard views/custom connectors. These views and custom connectors all have a "connector name" which can then be used in the API call.

To perform a data call, an authorization token must first be retrieved. Once an OAuth 2 user has been created, a BCS employee will provide the credentials in the form of a Client_ID and Client_Secret. With those credentials, you can retrieve an authorization token via the following URL: https://login.bcs.nl/inloggen/api/authenticate/token An example call in PowerShell can be found at the end of this article.

Once you have received a valid token, you can use it together with the Client_ID to perform a data API call. For this, you can use the following base URL: https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis

In this article, the standard view qvBasis is used as the connector name. This connector returns a number of person-related data items. At the end of this article, you will find an example script with which you can retrieve the data from the standard qvBasis view from Polaris using PowerShell.

Connectors

The following standard views/connectors are available:

In addition to the standard views, it is also possible to have custom views developed by Polaris. All export reports can also be set up as a connector. These can be enabled separately for the role via the API tab under Beheer |Rol. On this tab, a number of standard signals can also be enabled as connectors. Note! For signal connectors, a number of parameters are mandatory (see example later in this article).

By using "info" as the ConnectorName in the API call, you can request an overview of all connectors available to the API user. This overview also provides a list of all available fields and data types.

For filtering and/or limiting the dataset to be retrieved, the API connection supports the following parameters/options:

Parameter Description
limit For pagination purposes, this allows you to specify a maximum number of rows to be returned. e.g.: limit=100
offset For pagination purposes, this allows you to specify the starting position which, in combination with the quantity (limit), determines from which row data should be retrieved. e.g.: limit=100&offset=50
order This can be used in combination with a field name to enforce sorting. e.g.: order=fieldname asc
info This option can be used instead of the connector name. If you use info=1 in combination with a connector name, then all fields and data types of that specific connector will be returned. If you use info=2, then in addition to a list of fields and data types, the dataset of that connector will also be returned.

Note! All parameters/options are separated by an ampersand (&).

In addition to limiting the dataset via pagination, it is also possible to use any field from the dataset in a filter by means of operators.

Operator Description
wildcard/like To be used for alphanumeric fields. Use a combination with the percent sign (%) to limit the dataset. e.g.: fieldname=%L
greater than To be used for dates and numeric values. e.g.: fieldname=>10
less than To be used for dates and numeric values. e.g.: fieldname=<10
equal to To be used for all data types. e.g.: fieldname=10
greater than or equal to To be used for dates and numeric values. e.g.: fieldname=>=10
less than or equal to To be used for dates and numeric values. e.g.: fieldname=<=10

Note! A combination of operators is possible. After the field name, you always start with an = sign. Dates are enclosed in ".

Note! Nested data structures cannot be filtered on field names. If you request the "Info" of a connector, you will receive a message that column information is not available.

Examples

This section provides a number of example calls.

Operators

Sorting

Pagination

Signals

Example PowerShell Call

It is recommended not to use this example script in production and only to use it for testing and development purposes, since this script contains the Client_ID and Client_Secret in plain text!

#First retrieve the token

$token         = Invoke-RestMethod -Uri "https://login.bcs.nl/inloggen/api/authenticate/token" -Method Post -Body
@{client_id         = ""
  client_secret     = ""
         grant_type        = "client_credentials"
         audience          = "APPLICATION.DYNAMICAPI"
        } | Select-Object -ExpandProperty access_token

# Retrieve the data using the token

$api_response = Invoke-WebRequest  -UseBasicParsing -Uri $api_url -Method Get -
Headers @{"x-BCS-Client_Id" = ""
          "x-Api_Request_Available_Time_Ms"   = 60000
           Authorization = "Bearer $token"
           Accept = "application/xml"
        }

Note! The operation with JSON output is not always reliable (sorting and order of fields).

In response to the above calls, the standard HTTP response codes are used. 200 is successful. And in many cases 401 and 403 in case there is no authentication or in case a connector is requested for which you have no rights, respectively.

Standard Views

qvAdressen (Addresses)

Column Type Description
Persoon_ID Int32 The person ID in the database, not to be confused with the person number!
AdresVanaf DateTime Address from
AdresTotmet DateTime Address until
Adres String Address
Straat String Street
Huisnummer Int32 House number
Toevoeging String Suffix
Postcode String Postal code
Plaats String City
Land String Country
Reisafstand Decimal Travel distance
Toelichting String Notes
Correspondentie Boolean Correspondence
IsPostbus Boolean Is PO Box

qvBasis (Basic data)

Column Type Description
Persoon_ID Int32 Person ID
PersoonAdministratie_ID Int32 Person-Administration ID
Administratie_ID Int32 Administration ID
Administratie Int32 Administration
AdministratieNaam String Administration name
Persoonsnummer Int32 Person number
VolledigeNaam String Full name
VoorlettersNaam String Initials + name
VoorAchterNaam String First and last name
AanhefNaam String Salutation name
SortNaam String Sort name
Vanaf DateTime From
Totmet DateTime Until
Jubileumdatum DateTime Anniversary date
Sofinummer Int32 Social security number (BSN)
Naam String Last name
Voorvoegsels String Name prefixes (e.g. "van der")
Voorletters String Initials
Voornamen String First names
Roepnaam String Preferred first name
Geslacht_Code String Gender code
Geboortedatum DateTime Date of birth
Geboorteplaats String Place of birth
Land_Geboorte_Code String Country of birth code
Overlijdensdatum DateTime Date of death
TitelVoor String Title (prefix)
TitelNa String Title (suffix)
Naamsconventie_Code Byte Name convention code
Nationaliteit_Code Int16 Nationality code
BurgelijkeStaat_Code Byte Marital status code
Initialen String Initials
Adres_Correspondentie_Code Byte Correspondence address code
Adres_Loonstrook_Code Byte Payslip address code
Telefoon String Phone
Mobiel String Mobile
Email String Email
PriveTelefoon String Private phone
PriveMobiel String Private mobile
PriveEmail String Private email
Doorkiesnummer String Direct dial number
DoorkiesnummerMobiel String Direct dial mobile
Toelichting String Notes
LoonstrookPost Boolean Payslip by post
Extern_Code Byte External code
StartRelatie DateTime Start of relationship
EindeRelatie DateTime End of relationship
PartnerNaam String Partner last name
PartnerVoorvoegsels String Partner name prefixes
PartnerVoorletters String Partner initials
PartnerVoornamen String Partner first names
PartnerRoepnaam String Partner preferred first name
PartnerGeboortedatum DateTime Partner date of birth
Proforma Boolean Pro forma

qvBedrijfsauto (Company Car)

Column Type Description
Leasecontract_ID Int32 Lease contract ID
PersoonAdministratie_ID Int32 Person-Administration ID
LeasecontractVanaf DateTime Lease contract from
LeasecontractTotmet DateTime Lease contract until
Kenteken String License plate
PercentageBijtelling Decimal Addition percentage (tax)
WaardePriveGebruik Decimal Value of private use
BijdragePriveGebruik Decimal Contribution for private use
GebruikAuto String Car usage
GebruikVanaf DateTime Usage from
GebruikTotmet DateTime Usage until

qvCompetenties (Competencies)

Column Type Description
Persoon_ID Int32 Person ID
CompetentieSoort String Competency type
CompetentieCode String Competency code
CompetentieOmschrijving String Competency description
InstellingCode String Institution code
InstellingNaam String Institution name
ResultaatCode String Result code
ResultaatOmschrijving String Result description
DatumVanaf DateTime Date from
DatumTotmet DateTime Date until
DatumGeldig DateTime Valid date
DatumVolgende DateTime Next date
Diploma Boolean Diploma
Intern Boolean Internal
Kosten Decimal Costs
StatusCompetentie_Code Byte Competency status code
Subsidieregeling_Code Byte Subsidy scheme code
Subsidie Decimal Subsidy
Betalingsregeling_Code Byte Payment scheme code
BetalingsEinddatum DateTime Payment end date
Omschrijving String Description
Toelichting String Notes

qvDienstverband (Employment)

Column Type Description
Dienstverband_ID Int32 Employment ID
DienstverbandContract_ID Int32 Employment contract ID
PersoonAdministratie_ID Int32 Person-Administration ID
Proforma Boolean Pro forma
Persoon_ID Int32 Person ID
DienstverbandVanaf DateTime Employment from
DienstverbandTotmet DateTime Employment until
RedenIndienst String Reason for hire
RedenUitdienst String Reason for leaving
ContractVanaf DateTime Contract from
ContractWijziging DateTime Contract change
ContractTotmet DateTime Contract until
ParttimePercentage Single Part-time percentage
CAO_Code Int16 Collective Labour Agreement (CAO) code
CAO_ID Int32 CAO ID
CAO_Inlener_Code Int16 Hirer CAO code
Uurloner Boolean Hourly paid worker
Uren Single Hours
UrenMax Single Maximum hours
Schriftelijk Boolean Written
Oproep Boolean On-call
Jaarurennorm Boolean Annual hours standard
BBL Boolean BBL (vocational learning pathway)
Contractsoort String Contract type
Contractsoort_Code Int16 Contract type code
Contractduur String Contract duration
Contractduur_Code Int16 Contract duration code
Contracttijd_Code String Contract time code
FunctieCode String Job code
FunctieOmschrijving String Job description
OEN1 – OEN8 String Organizational unit levels 1–8
ManagementEigenaar String Management owner

qvKind (Child)

Column Type Description
Persoon_ID Int32 Person ID
Sofinummer Int32 Social security number (BSN)
Naam String Last name
Voorvoegsels String Name prefixes
Voorletters String Initials
Voornamen String First names
Roepnaam String Preferred first name
Geslacht_Code String Gender code
Geboortedatum DateTime Date of birth
Geboorteplaats String Place of birth
Overlijdensdatum DateTime Date of death
Geboorteland String Country of birth
Nationaliteit String Nationality

qvRegistraties (Registrations)

Column Type Description
PersoonAdministratie_ID Int32 Person-Administration ID
RegistratieCode String Registration code
Registratie String Registration
RegistratieSoort String Registration type
RegistratieInvoer String Registration entry
RegistratieVanaf DateTime Registration from
RegistratieTotmet DateTime Registration until
Registratienummer String Registration number
Bedrag Decimal Amount
BedragCum Decimal Cumulative amount
BedragToets Decimal Check amount
BedragAfgelost Decimal Amount repaid
Toelichting String Notes

qvVerstrekkingen (Issued Items)

Column Type Description
Verstrekking_ID Int32 Issued item ID
Persoon_ID Int32 Person ID
VerstrekkingCode String Issued item code
Verstrekking String Issued item
Merk String Brand
Code String Code
Omschrijving String Description
DatumUitgifte DateTime Date of issue
DatumInname DateTime Date of return/collection
DatumRetour DateTime Return date
Toelichting String Notes

qvNaam (Name)

Column Type Description
Persoon_ID Int32 Person ID
Persoonsnummer Int32 Person number
VolledigeNaam String Full name
VoorlettersNaam String Initials + name
VoorAchterNaam String First and last name
VoornamenAchterNaam String First names + last name
AanhefNaam String Salutation name
AanhefNaamInformeel String Informal salutation name
SortNaam String Sort name
SortNaamRoepNaam String Sort name with preferred first name
SortNaamNr String Sort name + number
SortNrNaam String Sort number + name
SortNaamExclVoorletter String Sort name excluding initial

qvSalaris (Salary)

Column Type Description
Persoon_ID Int32 Person ID
Dienstverband_ID Int32 Employment ID
DatumVanaf DateTime Date from
DatumTotmet DateTime Date until
Beloningsvorm String Form of remuneration
Omschrijving String Description
Schaalbedrag Decimal Scale amount
Afwijkendbedrag Decimal Deviating amount
Bedrag Decimal Amount
Toeslag Decimal Allowance
Berekend Decimal Calculated
Periodiekdatum DateTime Periodic increment date
SalarisWijziging_Code Int16 Salary change code