CommunicationParty API

The intended use for this API is to get a local copy of communication parties in the Addressregistry (AR), and to keep this copy up to date.

First the /CommunicationPartyExport endpoint can be used to get a full export of all active communication parties, and then use /CommunicationPartyEvents to get updates on the parties. See this GitHub repo for a simple example on how to implement this usage pattern.

The events endpoint contains CommunicationParty.Updated and CommunicationParty.Created events. Each event contains a communication party object. See details below.

Auth

Some parts of the API are restricted, and require authorization. See the Auth page for more information.

Environments

Environment URL
Test cpe.test.grunndata.nhn.no
Production cpe.grunndata.nhn.no

Swagger

Environment URL
Test cpe.test.grunndata.nhn.no/swagger
Production cpe.grunndata.nhn.no/swagger

Endpoints

HTTP Method Endpoint Description
GET /CommunicationPartyExport Get full export of all active communication parties
GET /CommunicationPartyEvents Get events
GET /CommunicationParties/herId Get a single communication party by herId

GET /CommunicationPartyExport

Get a full export of all active CommunicationParties. Returns streamed JSON data.

Compressed gzip response is also available. Set Accept-Encoding: application/gzip in the request header for compressed response with gzip

Example

Get export

GET /CommunicationPartyExport

Response

The response contains an updated list of all active communicationparties in the AddressRegistry.

LastDateTimeOffset and LastEventId contains the datetimeoffset and eventID of the last update included in the export. These can be used as parameters in the events endpoint to get the updates that has happened since the full export was gathered.

{

    "LastDateTimeOffset": "datetimeoffset",
    "LastEventId": "string",
    "CommunicationParties": [
        {
            "object"
        }
    ]
}

GET /CommunicationPartyEvents

Get CommunicationParty events based on given parameters. The number of events varies, but getting updates once every hour should be sufficient. NB: The value in fromDatetime needs to be URL Encoded.

Path parameters

Parameter Type Description
eventId string The id of the first event from where to start the search
fromDatetime string The datetimestamp of the event from where to get events from
Size int The size of the page

Example

Get all events

GET /CommunicationPartyEvents

Get events from a given id

GET /CommunicationPartyEvents?EventId=ddcae29a-68bc-40f9-854d-bad97d784a04

Get events from a given datetime Datetime format needs to be yyyy-mm-ddTHH:mm:ss.fffzzz (2023-07-10T16:00:00.000+02:00) and the value needs to be urlencoded

GET /CommunicationPartyEvents?FromDatetime=2023-06-07T07%3A11%3A25.000%2B02%3A00

Get events from a given datetime with a given number of objects in the response

GET /CommunicationPartyEvents?FromDatetime=2023-06-07T07%3A11%3A25.000%2B02%3A00&Size=1

Response

The response returns a link Next that contains a url with the eventid of the last event in the response. This is for quering the next page of events.

{
    "communicationParties": [
        {
            "EventId": "string",
            "FromDatetime": "datetimeoffset",
            "HerId": "int",
            "OrgNr": "int",
            "EventType": "string",
            "CommunicationParty": "object"
        }
    ],
    "_Links": {
        "next": {
            "href": "string"
        }
    }
}

GET /CommunicationParties/HerId

Get a single communication party by herId. This endpoint will only return active communication parties (valid.to after today).

Example

GET /CommunicationParties/59

Response

Returns the herId, herId of parent (-1 if no parent) and type of the communication party (organization, service or organizationPerson), in addition to the communication party object.

Returns 404 if the communication party is deactivated.

{
    "HerId": "int",
    "ParentHerId": "int",
    "Type": "string",
    "CommunicationParty": "object"
}

CommunicationParty objects

The CommunicationParty objects are based on the contracts found here.

There are some minor changes from these contracts:

  • In the Organization object, Departments, People and Services will always be null. The objects will exist on their own, with parent data populated. If an update happens on an organization that affects the underlying services and organization people, an event will be created for each of the underlying communication parties as well.
  • In the Person object CitizenID, Organizations and Departments is set to null, and in Person:HPRInformation the objects Authorizationsand SpecialCompetences is set to null. If this information is needed it should be gathered from the Health Personell Registry - HPR.