Establishing a local copy of the Person API

This page will walk you through the recommended steps for establishing a local copy of data from the Person API, and keep it updated with events from the event feed.

In short, a local copy can be established with these steps:

  1. First, retrieve the sequence number for the most recent event by calling the event/latest endpoint. Store this sequence number for later.
  2. Call the search/paged-match-list endpoint without any parameters. This will allow you to page through the entire population in the Person API, where each page contains a list of person references (person IDs).
  3. For each page with person IDs obtained from results of search/paged-match-list, utilize the person/bulk-by-id endpoint to fetch the complete person documents corresponding to those person IDs.
  4. Begin processing the event feed starting from the sequence number identified in step 1. Note that the most recent sequence number would have advanced while you were reading the entire population. Once you catch up to the latest event, your local copy will be up-to-date and ready for use.

Step 1: Store the most recent sequence number

Whenever information changes for a person in the Person API, events are emitted in the event feed. Calling the event/latest endpoint will return the most recent event in the event feed. The response will include the sequence number for the most recent event, in addition to a reference to the person which was updated, and an event type, which will indicate what information changed. A sample result will look like this:

{
  "sequenceNumber": "11618128",
  "personId": "2c37dae1-a161-433f-95b3-8a547e82caa5",
  "eventType": "ChangeInResidentialAddress"
}

In this step, the only thing we care about is extracting the sequence number for the most recent event and storing this, so we can start consuming events from this sequence number when we've established our local copy.

Step 2 and 3: Extract the population

The second and third step are done together, and the objective is to extract data for the entire population, by finding a reference to each unique person in the register and downloading the relevant data. It's also possible to do this step by targeting a subset of the population, this depends on the parameters you configure for the search/paged-match-list search.

The search/paged-match-list endpoint was created to search for large sets of people, but it also supports paging through the entire population. Calling the search/paged-match-list with no parameters will match the entire population, and allow you to page through pages with references to each unique person in the Person API. If a subset of the population is interesting instead, this search can be configured to meet your criteria. An example could be excluding persons with statuses Deceased, Discontinued, Inactive, but this will depend on your use-case. Regarding handling persons registered as discontinued in the Person API, please see handling discontinued persons.

We recommend setting the page size to max (10 000) for requests to search/paged-match-list. When requesting the next page, set the index offset to the end index of the previous result, plus one (endIndex + 1). See the API documentation for more detailed documentation on this endpoint.

A page result from search/paged-match-list does not include any person documents, but instead a list of person id references. The data for each person must be downloaded in bulk by using the person/bulk-by-id endpoint and providing a list of person id references. person/bulk-by-id only supports up to 100 ids, but multiple requests to this endpoint can be done in parallel if you want to speed up the extraction. Responses from person/bulk-by-id will return data on each person, and you'll also be forced to specify an information filter and if you want history in the person document (for instance historic identifiers or addresses).

After you've paged through all pages and downloaded data for all unique persons, your local copy is established.

Step 4: Keeping your local copy up to date

To keep your local copy up to date with changes from the Person API, you'll need to consume the event feed and update information on persons that have changed. The event feed can be consumed by calling the event endpoint, and specifying the lowest sequence number you want included in the result. The response will be a list of events (up to 1000) which are next in the event feed. To keep your local copy up to date, you'll need to continuously consume the events which have a higher sequence number than the one you stored in step 1. Call the event endpoint with this stored sequence number + 1, and the response will include all events that occurred while you were extracting the population. For each new event, download a new version of the person document for the person id given in the event by using person/get-by-id or person/bulk-by-id. Continuously store your last processed sequence number when you're consuming events, periodically call the event endpoint to check for new events. We'd recommend checking for new events fairly often (every 1/5/15/30 minutes) rather than doing a large sync for instance once a day.