REST API documentation

See below for English

Dit is de documentatie voor de RESTful 'API Contenttools' van de Nederlandse Rijksoverheid, onderdeel van het Platform Rijksoverheid Online. Hierin vindt je richtlijnen en voorbeelden voor gebruik van de API. Doel is het faciliteren van een consistent en eenvoudig gebruik van de API. Omdat de meeste ontwikkelaars gewend zijn om documentatie in de Engelse taal te lezen en we niet direct een deel van de ontwikkelaars willen buitensluiten schrijven we de documentatie in het Engels.

Vragen en opmerkingen graag via applicatiebeheer@beheerrijksoverheid.nl

English

This is the documentation for the RESTful 'API Content Tools' of the Dutch central government. On this page you will find information about how to use the API and of course what to find in the API. Our goal is a consistent and user-friendly API. As most developers understand the English language, we will write the remainder of the documentation in English.

Questions and remarks can be sent to applicatiebeheer@beheerrijksoverheid.nl

Current version

The current version of the API is v1 and the version is used explicitly in the url.

API requests

All API access is over HTTPS, and accessed from https://api.contenttoolsrijksoverheid.nl/v1. All request and response bodies are formatted as JSON.

The API will include blank fields as null instead of being omitted.

Timestamps within API response bodies are always returned in ISO 8601 format.

To perform a request to get a list of Filter Tools you can make use of an http client like curl.

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools' -i -X GET \
    -H 'Accept: application/hal+json'

Query parameters

You can specify one or more optional query parameters on the request URI to filter and sort the items that are returned in an API response and limit the size of the data returned in that response.

Pagination

Requests that return multiple items will be paginated to 20 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size with the ?size parameter.

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools?size=1' -i -X GET \
    -H 'Accept: application/hal+json'

Note that page numbering is 0-based and that omitting the ?page parameter will return the first page.

Requests that support paging will respond with link relations that allow the client to perform paging.

Relation Description

Relation	Description
`next`	The link relation for the immediate next page of results.
`prev`	The link relation for the immediate previous page of results.
`first`	The link relation for the first page of results.
`last`	The link relation for the last page of results.

next

The link relation for the immediate next page of results.

prev

The link relation for the immediate previous page of results.

first

The link relation for the first page of results.

last

The link relation for the last page of results.

Sorting

Request that return multiple items can be sorted on a particular property by adding a sort URL parameter with the name of the property you want to sort the results on.

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools?sort=title' -i -X GET \
    -H 'Accept: application/hal+json'

You can control the direction of the sort by appending a ',' to the the property name plus either asc or desc.

To sort the results by more than one property, keep adding as many sort=PROPERTY parameters as you need.

Results can be sorted by top-level and nested properties. Use property path notation to express a nested sort property.

Projections

Summary representations within the API are sometimes handled by projections.

A projection is a reduced view of the data. For certain resources within the API we have different projections available.

You can read about the available projections from the profile relation for any given resource.

If there is a projection available for a given resource you can request them by using the projection URL parameter.

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48?projection=filterToolSummary' -i -X GET \
    -H 'Accept: application/hal+json'

API responses

HATEOAS links

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.

Each API call response includes an array of contextual HATEOAS links, if available.

In your client you can use these links to request more information about and construct an API flow that is relative to a specific request.

The following excerpt is from a sample response and shows an array of HATEOAS links:

{
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools{?page,size,sort,projection}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/profile/filtertools"
    }
  }
}

Links are named and describe the relationship to the current resource, but can contain additional information that describes more about the link relation.

Element	Required	Description
href	Required	The target URL.
templated	Optional	If the link is templated (e.g. is contains templated parameters).

Element

Required

Description

href

Required

The target URL.

templated

Optional

If the link is templated (e.g. is contains templated parameters).

Templated links are links with certain request parameters that can be appended to the link to.

Summary representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource.

Example: When you get a list of Filter Tools, you get the summary representation of each Filter Tool. Here, we fetch the list of Filter Tools:

GET /v1/filtertools

Detailed representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource.

Example: When you get an individual filter tool, you get the detailed representation of the filter tool. Here, we fetch the filtertools/599200eb28cf5b4208f53d49:

GET /v1/filtertools/599200eb28cf5b4208f53d49

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

Resources

Root endpoint

You can issue a GET request to the root endpoint to get all the endpoint categories that the REST API v1 supports.

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK

{
  "_links" : {
    "filtertools" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools{?page,size,sort,projection}",
      "templated" : true
    },
    "municipalservices" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/municipalservices?municipality=&uniformProducts=&language="
    },
    "residences" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/residences?query="
    },
    "profile" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/profile"
    }
  }
}

Listing Filter Tools

A GET request will list all the Filter Tools.

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK

{
  "_embedded" : {
    "filtertools" : [ {
      "title" : "Werkloos worden",
      "description" : "Als u werkloos wordt verandert uw financiële situatie, en ook uw rechten en plichten naar de overheid. Zo kunt u soms een uitkering of aanvulling krijgen, maar wordt daarvoor ook een tegenprestatie verwacht.",
      "language" : "nl-NL",
      "creator" : "Maker van de filtertool",
      "organisation" : "Ministerie van Algemene Zaken",
      "publicationDate" : "2017-08-14T08:30:00.101",
      "_links" : {
        "self" : {
          "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48"
        },
        "filterTool" : {
          "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48{?projection}",
          "templated" : true
        }
      }
    }, {
      "title" : "Checklist bij scheiden of uit elkaar gaan",
      "description" : "Wilt u weten wat u moet regelen als u gaat scheiden of uit elkaar gaat? En wat uw rechten zijn? Vul dan uw situatie in en maak een persoonlijke checklist.",
      "language" : "nl-NL",
      "creator" : "Ministerie van Algemene Zaken",
      "organisation" : "Ministerie van Algemene Zaken",
      "publicationDate" : "2018-01-26T12:03:22.562",
      "_links" : {
        "self" : {
          "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d49"
        },
        "filterTool" : {
          "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d49{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools"
    },
    "profile" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/profile/filtertools"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Response structure

Path Type Description

Path	Type	Description
`_embedded.filtertools`	`Array`	An array of Filter Tool resources
`_embedded.filtertools[].title`	`String`	Filter Tool’s title
`_embedded.filtertools[].description`	`String`	Filter Tool’s description
`_embedded.filtertools[].language`	`String`	Filter Tool’s language
`_embedded.filtertools[].creator`	`String`	Filter Tool’s creator
`_embedded.filtertools[].organisation`	`String`	Filter Tool’s organisation
`_embedded.filtertools[].publicationDate`	`String`	Date the filter tool was published (formatted according to ISO-8601)
`_links`	`Object`	Links to other resources

_embedded.filtertools

Array

An array of Filter Tool resources

_embedded.filtertools[].title

String

Filter Tool’s title

_embedded.filtertools[].description

String

Filter Tool’s description

_embedded.filtertools[].language

String

Filter Tool’s language

_embedded.filtertools[].creator

String

Filter Tool’s creator

_embedded.filtertools[].organisation

String

Filter Tool’s organisation

_embedded.filtertools[].publicationDate

String

Date the filter tool was published (formatted according to ISO-8601)

_links

Object

Links to other resources

Links

Relation Description

Relation	Description
`self`	Link to the Filter Tools resources
`profile`	The ALPS profile for this resource

self

Link to the Filter Tools resources

profile

The ALPS profile for this resource

Get a Filter Tool

A GET request is used to get a Filter Tool.

Path parameters

Table 1. /v1/filtertools/{id}
Parameter	Description
`id`	Identifier of the Filter Tool

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK

{
  "title" : "Werkloos worden",
  "description" : "Als u werkloos wordt verandert uw financiële situatie, en ook uw rechten en plichten naar de overheid. Zo kunt u soms een uitkering of aanvulling krijgen, maar wordt daarvoor ook een tegenprestatie verwacht.",
  "language" : "nl-NL",
  "creator" : "Maker van de filtertool",
  "organisation" : "Ministerie van Algemene Zaken",
  "publicationDate" : "2017-08-14T08:30:00.101",
  "questionsDisplayType" : "ONE_BY_ONE",
  "questions" : [ {
    "id" : "idQuestions1_1",
    "type" : "SINGLE_SELECT",
    "text" : "Text questions1_1",
    "helpText" : "help text questions1_1",
    "order" : 1,
    "maxNumberOfRemainingQuestions" : 2,
    "answerOptions" : [ {
      "id" : "q1a1",
      "text" : "Answer 1",
      "feedback" : "Feedback for answer 1",
      "helpText" : "Help text for answer 1"
    }, {
      "id" : "q1a2",
      "text" : "Answer 2",
      "feedback" : "Feedback for answer 2",
      "helpText" : "Help text for answer 2"
    } ],
    "relevantFor" : [ ]
  }, {
    "id" : "idQuestions1_2",
    "type" : "MULTIPLE_SELECT",
    "text" : "Text questions1_2",
    "helpText" : "help text questions1_2",
    "order" : 2,
    "maxNumberOfRemainingQuestions" : 1,
    "answerOptions" : [ {
      "id" : "q2a1",
      "text" : "Answer 1",
      "feedback" : "Feedback for answer 1",
      "helpText" : "Help text for answer 1"
    }, {
      "id" : "q2a2",
      "text" : "Answer 2",
      "feedback" : "Feedback for answer 2",
      "helpText" : "Help text for answer 2"
    }, {
      "id" : "q2a3",
      "text" : "Answer 3",
      "feedback" : "Feedback for answer 3",
      "helpText" : "Help text for answer 3"
    }, {
      "id" : "q2a4",
      "text" : "Answer 4",
      "feedback" : "Feedback for answer 4",
      "helpText" : "Help text for answer 4"
    } ],
    "relevantFor" : [ {
      "questionId" : "idQuestions1_1",
      "answerOptionIds" : [ "q1a1", "q1a2" ]
    } ]
  } ],
  "feedbackHeader" : "Mijn situatie",
  "resultHeader" : null,
  "resultBodyText" : "Bekijk uw persoonlijke checklist. U kunt sorteren op onderwerp en op organisatie.",
  "resultDisplayType" : "FULL",
  "maxOpenContentBlocks" : 3,
  "grouping1" : "Organisaties",
  "groupsOfGrouping1" : [ "Rijksoverheid", "AZ", "DPC", "EP", "EC" ],
  "grouping2" : "Op tijd",
  "groupsOfGrouping2" : [ "Vandaag", "Gisteren", "Morgen", "Ooit", "Nooit" ],
  "grouping3" : "Instanties",
  "groupsOfGrouping3" : [ "Belastingdienst", "UWV", "SVB", "DUO" ],
  "locationQuestion" : {
    "title" : "Resultaten aanvullen met informatie van uw gemeente?",
    "subTitle" : "Wat is uw woonplaats?",
    "helpText" : "Als u uw woonplaats opgeeft, vullen we uw overzicht aan met informatie van uw gemeente. Vult u de vragen in voor een ander? Geef dan de woonplaats van die persoon. De overheid slaat geen gegevens op. U krijgt alleen extra informatie te zien.",
    "feedbackNoResult" : "Helaas, er is geen specifieke informatie voor de gemeente [gemeente].",
    "feedbackResult" : "Er is specifieke informatie voor de gemeente [gemeente]."
  },
  "exportFormat" : "BASIC",
  "exportIntroductionText" : "Dit is de tekst voor in de PDF.",
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48"
    },
    "filterTool" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48{?projection}",
      "templated" : true
    },
    "contentBlocks" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48/contentblocks"
    },
    "pdfExport" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48/_pdf"
    }
  }
}

Response structure

Path Type Description

Path	Type	Description
`title`	`String`	Filter Tool’s title
`description`	`String`	Filter Tool’s description
`language`	`String`	Filter Tool’s language
`creator`	`String`	Filter Tool’s creator
`organisation`	`String`	Filter Tool’s organisation
`publicationDate`	`String`	Date the filter tool was published (formatted according to ISO-8601)
`questionsDisplayType`	`String`	Filter Tool’s questions display type. Possible values: `ONE_BY_ONE, ALL_AT_ONCE`
`questions`	`Array`	The questions belonging to this filter tool
`feedbackHeader`	`String`	The header of the feedback
`resultHeader`	`Null`	The header of the result
`resultBodyText`	`String`	The subtext of the result
`resultDisplayType`	`String`	The result display type. Possible values: `COMPACT, FULL`
`maxOpenContentBlocks`	`Number`	Filter Tool’s maximum number of content blocks that should be unfolded on load of the results
`grouping1`	`String`	Filter Tool’s grouping 1
`groupsOfGrouping1`	`Array`	The groups of grouping 1 in order
`grouping2`	`String`	Filter Tool’s grouping 2
`groupsOfGrouping2`	`Array`	The groups of grouping 2 in order
`grouping3`	`String`	Filter Tool’s grouping 3
`groupsOfGrouping3`	`Array`	The groups of grouping 3 in order
`locationQuestion`	`Object`	The location question
`locationQuestion.title`	`String`	The location question title
`locationQuestion.subTitle`	`String`	The location question subtitle
`locationQuestion.helpText`	`String`	The location question help text
`locationQuestion.feedbackNoResult`	`String`	The location question feedback if no results were found
`locationQuestion.feedbackResult`	`String`	The location question feedback if results were found
`exportFormat`	`String`	The format for the PDF export. Possible values: `BASIC, CHECKLIST`
`exportIntroductionText`	`String`	The introduction text for the PDF export
`questions[].id`	`String`	The ID of the question
`questions[].type`	`String`	The type of the question. Possible values: `SINGLE_SELECT, SINGLE_SELECT_DROPDOWN, MULTIPLE_SELECT, TOGGLE`
`questions[].text`	`String`	The actual question
`questions[].order`	`Number`	The order of the question in the total list of questions
`questions[].helpText`	`String`	The help text of the question
`questions[].maxNumberOfRemainingQuestions`	`Number`	The maximum number of possible remaining questions
`questions[].defaultAnswerOptionId`	`String`	The default answer option ID, only applicable if `type` is `TOGGLE`
`questions[].feedback`	`String`	The feedback for the question, only applicable if `type` is `SINGLE_SELECT_DROPDOWN`
`questions[].answerOptions`	`Array`	The answer options for this question
`questions[].answerOptions[].id`	`String`	The ID of the answer option
`questions[].answerOptions[].text`	`String`	The answer option text
`questions[].answerOptions[].feedback`	`String`	The answer option feedback
`questions[].answerOptions[].helpText`	`String`	The answer option help text
`questions[].relevantFor`	`Array`	The question and answer option combinations for which this question is relevant. If a question of this set is answered, then this question should only be shown if at least one answer matches the answer options of the appropriate question.
`questions[].relevantFor[].questionId`	`String`	The ID of a relevant question for which answer options are relevant
`questions[].relevantFor[].answerOptionIds`	`Array`	The IDs of relevant answer options of the relevant question
`_links`	`Object`	Links to this resource

title

String

Filter Tool’s title

description

String

Filter Tool’s description

language

String

Filter Tool’s language

creator

String

Filter Tool’s creator

organisation

String

Filter Tool’s organisation

publicationDate

String

Date the filter tool was published (formatted according to ISO-8601)

questionsDisplayType

String

Filter Tool’s questions display type. Possible values: ONE_BY_ONE, ALL_AT_ONCE

questions

Array

The questions belonging to this filter tool

feedbackHeader

String

The header of the feedback

resultHeader

Null

The header of the result

resultBodyText

String

The subtext of the result

resultDisplayType

String

The result display type. Possible values: COMPACT, FULL

maxOpenContentBlocks

Number

Filter Tool’s maximum number of content blocks that should be unfolded on load of the results

grouping1

String

Filter Tool’s grouping 1

groupsOfGrouping1

Array

The groups of grouping 1 in order

grouping2

String

Filter Tool’s grouping 2

groupsOfGrouping2

Array

The groups of grouping 2 in order

grouping3

String

Filter Tool’s grouping 3

groupsOfGrouping3

Array

The groups of grouping 3 in order

locationQuestion

Object

The location question

locationQuestion.title

String

The location question title

locationQuestion.subTitle

String

The location question subtitle

locationQuestion.helpText

String

The location question help text

locationQuestion.feedbackNoResult

String

The location question feedback if no results were found

locationQuestion.feedbackResult

String

The location question feedback if results were found

exportFormat

String

The format for the PDF export. Possible values: BASIC, CHECKLIST

exportIntroductionText

String

The introduction text for the PDF export

questions[].id

String

The ID of the question

questions[].type

String

The type of the question. Possible values: SINGLE_SELECT, SINGLE_SELECT_DROPDOWN, MULTIPLE_SELECT, TOGGLE

questions[].text

String

The actual question

questions[].order

Number

The order of the question in the total list of questions

questions[].helpText

String

The help text of the question

questions[].maxNumberOfRemainingQuestions

Number

The maximum number of possible remaining questions

questions[].defaultAnswerOptionId

String

The default answer option ID, only applicable if type is TOGGLE

questions[].feedback

String

The feedback for the question, only applicable if type is SINGLE_SELECT_DROPDOWN

questions[].answerOptions

Array

The answer options for this question

questions[].answerOptions[].id

String

The ID of the answer option

questions[].answerOptions[].text

String

The answer option text

questions[].answerOptions[].feedback

String

The answer option feedback

questions[].answerOptions[].helpText

String

The answer option help text

questions[].relevantFor

Array

The question and answer option combinations for which this question is relevant. If a question of this set is answered, then this question should only be shown if at least one answer matches the answer options of the appropriate question.

questions[].relevantFor[].questionId

String

The ID of a relevant question for which answer options are relevant

questions[].relevantFor[].answerOptionIds

Array

The IDs of relevant answer options of the relevant question

_links

Object

Links to this resource

Links

Relation Description

Relation	Description
`self`	Link to the Filter Tool resource
`filterTool`	Link to the Filter Tool resource
`contentBlocks`	Link to the (filtered) Content Blocks resources
`pdfExport`	Link to export the Filter Tool as PDF with (filtered) Content Blocks

self

Link to the Filter Tool resource

filterTool

Link to the Filter Tool resource

contentBlocks

Link to the (filtered) Content Blocks resources

pdfExport

Link to export the Filter Tool as PDF with (filtered) Content Blocks

Listing Content Blocks

A GET or POST request will list the Content Blocks. The request body is optional. If it isn’t supplied, then all Content Blocks belonging to this Filter Tool are returned. If it is supplied, then the returned Content Blocks are filtered for it.

Path parameters

Table 2. /v1/filtertools/{id}/contentblocks
Parameter	Description
`id`	Identifier of the Filter Tool

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48/contentblocks' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
    "answers":
        [
            {
                "questionId": "idQuestions1_1",
                "answerOptionId": "q1a2"
            }
        ]
}'

Request body structure

Path Type Description

Path	Type	Description
`answers[].questionId`	`String`	The ID of the question which is answered
`answers[].answerOptionId`	`String`	A String with the ID of the answered answer, used in a single select or toggle question
`answers[].answerOptionIds`	`Array`	An array with the ID(s) of the answered answers, used in multi select questions

answers[].questionId

String

The ID of the question which is answered

answers[].answerOptionId

String

A String with the ID of the answered answer, used in a single select or toggle question

answers[].answerOptionIds

Array

An array with the ID(s) of the answered answers, used in multi select questions

Example response

HTTP/1.1 200 OK

{
  "_embedded" : {
    "contentBlocks" : [ {
      "title" : "Content Block 2",
      "subTitle" : "Content Block SubTitle 2",
      "bodyText" : "Some other content",
      "group1" : "Rijksoverheid",
      "group2" : "Gisteren",
      "group3" : "SVB",
      "relevantFor" : [ {
        "questionId" : "idQuestions1_1",
        "answerOptionIds" : [ "q1a1", "q1a2" ]
      } ],
      "orderNoGroup" : 1,
      "orderGroup1" : 2,
      "orderGroup2" : 3,
      "orderGroup3" : 4,
      "uniformProductContents" : [ {
        "uniformProduct" : "opleidingsvergoeding werklozen",
        "text" : "U kunt bij gemeente [gemeente] meer vinden over hoe u een vergoeding kunt krijgen voor een opleiding."
      } ]
    }, {
      "title" : "Content Block 3",
      "subTitle" : "Content Block SubTitle 3",
      "bodyText" : "Some more content<br>",
      "group1" : "AZ",
      "group2" : "Gisteren",
      "group3" : "SVB",
      "relevantFor" : [ ],
      "orderNoGroup" : 1,
      "orderGroup1" : 2,
      "orderGroup2" : 3,
      "orderGroup3" : 4,
      "uniformProductContents" : [ {
        "uniformProduct" : "opleidingsvergoeding werklozen",
        "text" : "U kunt bij gemeente [gemeente] meer vinden over hoe u een vergoeding kunt krijgen voor een opleiding."
      } ]
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48/contentblocks"
    }
  }
}

Response structure

Path Type Description

Path	Type	Description
`_embedded.contentBlocks`	`Array`	An array of Content Block resources
`_links`	`Object`	Links to this resource
`_embedded.contentBlocks[].title`	`String`	The title of the content block
`_embedded.contentBlocks[].subTitle`	`String`	The sub title of the content block
`_embedded.contentBlocks[].bodyText`	`String`	The body text (content) of the content block
`_embedded.contentBlocks[].group1`	`String`	The name of the group of grouping 1 this content block belongs to
`_embedded.contentBlocks[].group2`	`String`	The name of the group of grouping 2 this content block belongs to
`_embedded.contentBlocks[].group3`	`String`	The name of the group of grouping 3 this content block belongs to
`_embedded.contentBlocks[].relevantFor`	`Array`	The question and answer option combinations for which this content block is relevant. If a question of this set is answered, then this content block should only be shown if at least one answer matches the answer options of the appropriate question.
`_embedded.contentBlocks[].uniformProductContents`	`Array`	The uniform products for which content should be retrieved.
`_embedded.contentBlocks[].orderNoGroup`	`Number`	The ordering of the content block when no group exists
`_embedded.contentBlocks[].orderGroup1`	`Number`	The ordering of the content block in the group of grouping 1
`_embedded.contentBlocks[].orderGroup2`	`Number`	The ordering of the content block in the group of grouping 2
`_embedded.contentBlocks[].orderGroup3`	`Number`	The ordering of the content block in the group of grouping 3
`_embedded.contentBlocks[].relevantFor[].questionId`	`String`	The ID of a relevant question for which answer options are relevant
`_embedded.contentBlocks[].relevantFor[].answerOptionIds`	`Array`	The IDs of relevant answer options of the relevant question
`_embedded.contentBlocks[].uniformProductContents[].uniformProduct`	`String`	The uniform product name relevant to the content block
`_embedded.contentBlocks[].uniformProductContents[].text`	`String`	The text to show before the content for the uniform product

_embedded.contentBlocks

Array

An array of Content Block resources

_links

Object

Links to this resource

_embedded.contentBlocks[].title

String

The title of the content block

_embedded.contentBlocks[].subTitle

String

The sub title of the content block

_embedded.contentBlocks[].bodyText

String

The body text (content) of the content block

_embedded.contentBlocks[].group1

String

The name of the group of grouping 1 this content block belongs to

_embedded.contentBlocks[].group2

String

The name of the group of grouping 2 this content block belongs to

_embedded.contentBlocks[].group3

String

The name of the group of grouping 3 this content block belongs to

_embedded.contentBlocks[].relevantFor

Array

The question and answer option combinations for which this content block is relevant. If a question of this set is answered, then this content block should only be shown if at least one answer matches the answer options of the appropriate question.

_embedded.contentBlocks[].uniformProductContents

Array

The uniform products for which content should be retrieved.

_embedded.contentBlocks[].orderNoGroup

Number

The ordering of the content block when no group exists

_embedded.contentBlocks[].orderGroup1

Number

The ordering of the content block in the group of grouping 1

_embedded.contentBlocks[].orderGroup2

Number

The ordering of the content block in the group of grouping 2

_embedded.contentBlocks[].orderGroup3

Number

The ordering of the content block in the group of grouping 3

_embedded.contentBlocks[].relevantFor[].questionId

String

The ID of a relevant question for which answer options are relevant

_embedded.contentBlocks[].relevantFor[].answerOptionIds

Array

The IDs of relevant answer options of the relevant question

_embedded.contentBlocks[].uniformProductContents[].uniformProduct

String

The uniform product name relevant to the content block

_embedded.contentBlocks[].uniformProductContents[].text

String

The text to show before the content for the uniform product

Links

Relation Description

Relation	Description
`self`	Link to the (filtered) Content Blocks resources

self

Link to the (filtered) Content Blocks resources

Exporting a Filter Tool as PDF

A GET or POST request will export the Filter Tool with its corresponding Content Blocks in a PDF. The format of the PDF is determined by the value of the exportFormat field. The grouping to group the Content Blocks by can be provided. If no grouping is provided the first available grouping will be chosen, if existent. If question ids and answer ids are not supplied, then all Content Blocks belonging to this Filter Tool are returned. If question ids and answer ids are supplied, then the PDF will only contain the Content Blocks which match the provided input. If a Dutch municipality is provided, the Filter Tool will be enhanced with additional information which is provided by the municipality.

Path parameters

Table 3. /v1/filtertools/{id}/_pdf
Parameter	Description
`id`	Identifier of the Filter Tool

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/filtertools/599200eb28cf5b4208f53d48/_pdf?questionAndAnswerOptionId=idQuestions1_1%2Cq1a1&questionAndAnswerOptionId=idQuestions1_1%2Cq1a2&questionAndAnswerOptionIds=idQuestions1_2%2Cq2a1%2Cq2a2&questionAndAnswerOptionIds=idQuestions1_2%2Cq2a2%2Cq2a3&clientLocationUrl=https%3A%2F%2Fwww.rijksoverheid.nl%2Fonderwerpen%2Fscheiden%2Fvraag-en-antwoord%2Fchecklist-bij-scheiden-of-uit-elkaar-gaan' -i -X GET \
    -H 'Content-Type: application/x-www-form-urlencoded'

Request parameters

Parameter Description

Parameter	Description
`questionAndAnswerOptionId`	Value containing the question ID and answer option ID separated by a comma. Example value: "questionId,answerOption1Id". This parameter can be supplied one or multiple times.
`questionAndAnswerOptionIds`	Value containing the question ID and answer option IDs separated by a comma. Example value: "questionId,answerOption1Id,answerOption2Id". This parameter can be supplied one or multiple times.
`grouping`	The selected grouping as a number to group content blocks by. If no grouping is set the first available grouping will be used.
`municipality`	The name of the municipality used for enriching content blocks with 'localized' content. For a list of possible municipality names you can visit: https://standaarden.overheid.nl/owms/terms/Gemeente.html.
`clientLocationUrl`	The URL where the Filter Tool is located. This will be shown in the header of the PDF for future reference.

questionAndAnswerOptionId

Value containing the question ID and answer option ID separated by a comma. Example value: "questionId,answerOption1Id". This parameter can be supplied one or multiple times.

questionAndAnswerOptionIds

Value containing the question ID and answer option IDs separated by a comma. Example value: "questionId,answerOption1Id,answerOption2Id". This parameter can be supplied one or multiple times.

grouping

The selected grouping as a number to group content blocks by. If no grouping is set the first available grouping will be used.

municipality

The name of the municipality used for enriching content blocks with 'localized' content. For a list of possible municipality names you can visit: https://standaarden.overheid.nl/owms/terms/Gemeente.html.

clientLocationUrl

The URL where the Filter Tool is located. This will be shown in the header of the PDF for future reference.

Example response

HTTP/1.1 200 OK

<binary>

Listing Municipal Services

A GET or POST request will list municipal services for the provided municipality and uniform product names.

Request parameters

Parameter Description

Parameter	Description
`municipality`	The name of the municipality for which municipalServices should be retrieved. For a list of possible municipality names you can visit: https://standaarden.overheid.nl/owms/terms/Gemeente.html
`uniformProducts`	A comma-separated list of uniform product names for which municipalServices should be queried. For a list of possible product names you can visit: https://standaarden.overheid.nl/owms/terms/UniformeProductnaam.html
`language`	The language for which municipal services should be retrieved. This an optional parameter. If omitted, the default language is Dutch (nl).

municipality

The name of the municipality for which municipalServices should be retrieved. For a list of possible municipality names you can visit: https://standaarden.overheid.nl/owms/terms/Gemeente.html

uniformProducts

A comma-separated list of uniform product names for which municipalServices should be queried. For a list of possible product names you can visit: https://standaarden.overheid.nl/owms/terms/UniformeProductnaam.html

language

The language for which municipal services should be retrieved. This an optional parameter. If omitted, the default language is Dutch (nl).

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/municipalservices?municipality=Tilburg&uniformProducts=huwelijksaangifte&language=nl' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK

{
  "_embedded" : {
    "uniformProducts" : [ {
      "name" : "huwelijksaangifte",
      "municipalServices" : [ {
        "title" : "Trouwen",
        "abstract" : "Als u wilt trouwen of een geregistreerd partnerschap wilt aangaan, moet u dit eerst melden (voorheen: ondertrouw). Dit kunt u doen in de gemeente waar u wilt gaan trouwen, tenminste 2 weken en maximaal 1 jaar voor uw trouwdatum.",
        "uri" : "https://www.tilburg.nl/inwoners/geboorte-trouwen-overlijden/trouwen/"
      } ]
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/municipalservices?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Response structure

Path Type Description

Path	Type	Description
`_embedded.uniformProducts`	`Array`	An array of uniform products Municipal Services resources, grouped per requested uniform product.
`_links`	`Object`	Links to this resource
`_embedded.uniformProducts[].name`	`String`	The uniform product name
`_embedded.uniformProducts[].municipalServices`	`Array`	The municipal services for the uniform product
`_embedded.uniformProducts[].municipalServices[].title`	`String`	The title for the municipal service
`_embedded.uniformProducts[].municipalServices[].abstract`	`String`	The abstract for the municipal service
`_embedded.uniformProducts[].municipalServices[].uri`	`String`	The uri location for the municipal service

_embedded.uniformProducts

Array

An array of uniform products Municipal Services resources, grouped per requested uniform product.

_links

Object

Links to this resource

_embedded.uniformProducts[].name

String

The uniform product name

_embedded.uniformProducts[].municipalServices

Array

The municipal services for the uniform product

_embedded.uniformProducts[].municipalServices[].title

String

The title for the municipal service

_embedded.uniformProducts[].municipalServices[].abstract

String

The abstract for the municipal service

_embedded.uniformProducts[].municipalServices[].uri

String

The uri location for the municipal service

Links

Relation Description

Relation	Description
`self`	Link to the Municipal Services resources

self

Link to the Municipal Services resources

Listing Residences

A GET or POST request will list residences for the provided query.

Request parameters

Parameter Description

Parameter	Description
`query`	The query for which residences, their name starting with this query, should be retrieved. Residence names are obtained from https://almanak.overheid.nl/categorie/1/Gemeenten/ and municipality names are obtained from https://standaarden.overheid.nl/owms/terms/Gemeente.html

query

The query for which residences, their name starting with this query, should be retrieved. Residence names are obtained from https://almanak.overheid.nl/categorie/1/Gemeenten/ and municipality names are obtained from https://standaarden.overheid.nl/owms/terms/Gemeente.html

Example request

$ curl 'https://api.contenttoolsrijksoverheid.nl/v1/residences?query=Rijswijk' -i -X GET \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK

{
  "_embedded" : {
    "residences" : [ {
      "name" : "Rijswijk GLD",
      "municipality" : "Buren"
    }, {
      "name" : "Rijswijk NB",
      "municipality" : "Woudrichem"
    }, {
      "name" : "Rijswijk ZH",
      "municipality" : "Rijswijk"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.contenttoolsrijksoverheid.nl/v1/residences?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}

Response structure

Path Type Description

Path	Type	Description
`_embedded.residences`	`Array`	An array of Residence resources
`_links`	`Object`	Links to this resource
`_embedded.residences[].name`	`String`	The name of the residence
`_embedded.residences[].municipality`	`String`	The name of the municipality to which the residence belongs

_embedded.residences

Array

An array of Residence resources

_links

Object

Links to this resource

_embedded.residences[].name

String

The name of the residence

_embedded.residences[].municipality

String

The name of the municipality to which the residence belongs

Links

Relation Description

Relation	Description
`self`	Link to the Residences resources

self

Link to the Residences resources