# Skjalatilkynning API API that document providers use to register and maintain document references, along with sending notifications. Document Providers authenticate themselves with OAuth 2.0 Authentication using Client Credentials Grant () All operations that modify document references can take an array of 1-200 changes at time. They return an array result for each change in the same order as they were entered. ## Categories Returns possible categories of documents in Icelandic. Example of categories: Líf og Heilsa (e. Life and Health), Atvinna (e. Employment), Fjármál (e. Finances) > GET /api/v1/documentindexes/categories #### Response ```json ["string"] ``` | Variable | Type | Description | | -------- | ------ | --------------------------------------------------------------------------- | | \[] | String | Document categories that can be used when document reference is registered. | ## Types Returns possible types of documents in Icelandic. Example types: Launaseðill (e. Paycheck), Greiðsluseðill (e. Invoice), Yfirlit (e. Overview/Summary) > GET /api/v1/documentindexes/types #### Response ```json ["string"] ``` | Variable | Type | Description | | -------- | ------ | ------------------------------------------------------------------- | | \[] | String | Document type that can be used when registering document reference. | ## DocumentIndex A document provider registers references to documents. Each document is uniquely identified by a combination of `documentID` and `owner_kennitala`, which together form a unique key pair that can only be registered once. However, a document can be registered multiple times for different `owner_kennitala`, for example, when a couple needs access to the same document. Once the `publication_date` has passed, the recipient is notified and the document becomes visible. A published document **can not be removed** or have its contents modified, except if it was registered to an incorrect recipient. > POST /api/v1/documentindexes #### Request Body ```json [ { "kennitala": "string", "documentId": "string", "senderKennitala": "string", "senderName": "string", "authorKennitala": "string", "caseId": "string", "category": "string", "type": "string", "subType": "string", "subject": "string", "documentDate": "datetime", "publicationDate": "datetime", "minimumAuthenticationType": "string", "fileType": "string", "urgentUntil": "datetime" } ] ``` Array of document references. It‘s possible to submit 1-200 references at a time | Variable | Optional | Type | Description | | ------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | kennitala | N | String(10) | Kennitala of the document owner/recipient, that is the one who should see the document. Has to be a valid kennitala. | | documentId | N | String(50) | A unique identifier within a document provider. Used to retrieve a document, when user requests it. | | senderKennitala | N | String(10) | Sender kennitala (usually some institution). (A document provider can represent and register documents for many senders) | | senderName | N | String | Name of the sender. | | authorKennitala | Y | String(10) | Author kennitala (Usually same as the Sender (KennitalaSendanda)) | | caseId | Y | String | Case number within the institution (sender). | | category | N | String(25) | Document category. Only allowed predefined document categories. The operation SaekjaFlokka (e. GetCategories) returns the types that are available. | | type | Y | String(25) | Document type. Only allowed predefined document types. The operation SaekjaTegundir (e. GetTypes) returns the types that are available. | | subType | Y | String | Sub-type, selected by a document provider. | | subject | N | String(80) | Document name or description, free text up to 80 characters. | | documentDate | N | Datetime | Date of document (not publication date). | | publicationDate | Y | Datetime | Indicates when the document should appear to the user. For example, if the publisher wants to submit a reference tor a document to be published at the next month. If nothing is set, the document is displayed immediately. Date Display may not exceed 60 days in advance. | | minimumAuthenticationType | Y | String |

Minimum authentication type/strength to open/view the document. The default is LOW.
LOW = User/pass
SUBSTANTIAL = Two factor authentication (User/Pass and additionally an SMS)
HIGH = Client Certificate

| | fileType | Y | String |

Indicates the file type, current supported types are "url", "pdf" and "html". Unsupported file types are still available for download but will not be displayed properly.
If fileType is not provided "pdf" is assumed.

| | urgentUntil | Y | Datetime | Marks the document as urgent. Requires special permission to be utilized. | #### Response ```json [ { "kennitala": "string", "documentId": "string", "wantsPaper": true, "success": true, "errors": ["string"] } ] ``` | Property | Type | Description | | ---------- | ------- | --------------------------------------------------------------------- | | kennitala | String | Kennitala of the document owner/recipient. | | documentId | String | A unique identifier for the reference within the document provider | | wantsPaper | Boolean | [Paper preference](#paper-preference) of the document owner/recipient | | success | Boolean | Successful | | errors\[] | String | Error messages (only if success=false). | ## Notification Creates a 'hnipp' notification that sends both a push notification and an email to the recipient. Notifications utilize templates to manage the their content. Read more about templates here: [Notifications / Hnipp ](https://docs.devland.is/products/notifications-hnipp/new-notification-setup-guide) > POST /api/v1/notifications #### Request Body ```json [ { "kennitala": "string", "senderKennitala": "string", "templateId": "string", "templateArguments": { "argKey": "argValue" }, "publicationDate": "datetime" } ] ``` Array of notifications. It‘s possible to submit 1-200 references at a time | Variable | Optional | Type | Description | | ----------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | kennitala | N | String(10) | Kennitala of the recipient. Has to be a valid kennitala. | | senderKennitala | N | String(50) | Sender kennitala (usually some institution). (A document provider can represent and send notifications for many senders) | | templateId | N | String | An ID referencing a template, the template contains the textual information for the notification in all supported languages. | | templateArguments | - | Object | Arguments that fill in the dynamic portions of a template. Should contain key-value pairs the template requires. Required if the template has arguments. | | publicationDate | Y | DateTime | Indicates when the notification should be pushed to the user. If nothing is set, the notification is queued immediately. | #### Response ```json [ { "kennitala": "string", "success": true, "errors": ["string"] } ] ``` | Property | Type | Description | | --------- | ------- | ------------------------------------------------ | | kennitala | String | Kennitala of the recipient. | | success | Boolean | Indicates if the requets was a success | | errors\[] | String | Any error messages (only if the request failed). | ### Example request Registering two notifications to different individuals. ```json [ { "kennitala": "0000000000", "senderKennitala": "0000000000", "templateId": "HNIPP.EXAMPLE.TEMPLATE", "templateArguments": { "salutation": "Hello world!" }, "publicationDate": "01-01-2024" }, { "kennitala": "0000000001", "senderKennitala": "0000000000", "templateId": "HNIPP.EXAMPLE.TEMPLATE", "templateArguments": { "salutation": "Greetings world!" }, "publicationDate": "01-01-2024" } ] ``` ## Withdraw An operation to withdraw a document that is no longer available for publication. This can **only** be used if the document was sent to an **incorrect recipient** or if the `publication_date` has not passed. If a document needs to be withdrawn after it was opened by the recipient, the document provider must notify the recipient of the withdrawal. > POST /api/v1/documentindexes/withdraw #### Request Body ```json [ { "kennitala": "string", "documentId": "string", "reason": "string" } ] ``` Array of withdrawn references. It‘s possible to withdraw 1-200 references at a time | Variable | Type | Description | | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | kennitala | String(10) | Owner/recipient kennitala. | | documentId | String | A unique identifier which was used when the document was registered (for the reference within the document provider). | | reason | String | Reason for withdrawal. | #### Response ```json [ { "kennitala": "string", "documentId": "string", "success": true, "errors": ["string"] } ] ``` | Property | Type | Description | | ---------- | ------- | ------------------------------------------------------------------ | | kennitala | String | Kennitala of the document owner/recipient. | | documentId | String | A unique identifier for the reference within the document provider | | success | Boolean | Successful | | errors\[] | String | Error messages (only if success=false). | ## Read > POST /api/v1/documentindexes/read If a document provider has published a document in a location other than island.is, the document can be marked as read. Thus, the user can see that he has opened the document regardless of where he opened it. #### Request Body ```json [ { "kennitala": "string", "documentId": "string" } ] ``` It‘s possible to mark 1-200 references as read at a time | Variable | Type | Description | | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | kennitala | String(10) | Owner/recipient kennitala. | | documentId | String | A unique identifier which was used when the document was registered (for the reference within the document provider). | #### Response ```json [ { "kennitala": "string", "documentId": "string", "success": true, "errors": ["string"] } ] ``` | Property | Type | Description | | ---------- | ------- | ------------------------------------------------------------------ | | kennitala | String | Kennitala of the document owner/recipient. | | documentId | String | A unique identifier for the reference within the document provider | | success | Boolean | Successful | | errors\[] | String | Error messages (only if success=false). | ## Update Reference > POST /api/v1/documentindexes/updateReference If the document's publication date has not elapsed, the document provider can change the documents reference. #### Request Body ```json [ { "kennitala": "string", "documentId": "string", "updatedDocumentId": "string" } ] ``` It‘s possible to change 1-200 references at a time | Variable | Type | Description | | ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | kennitala | String(10) | Owner/recipient kennitala. | | documentId | String | A unique identifier which was used when the document was registered (for the reference within the document provider). | | updatedDocumentId | String | The new unique identifier. | #### Response ```json [ { "kennitala": "string", "documentId": "string", "success": true, "errors": ["string"] } ] ``` | Property | Type | Description | | ---------- | ------- | ------------------------------------------------------------------ | | kennitala | String | Kennitala of the document owner/recipient. | | documentId | String | A unique identifier for the reference within the document provider | | success | Boolean | Successful | | errors\[] | String | Error messages (only if success=false). | ## Paper Preference A document recipient can register to receive a physical paper document on Island.is. It is up to the document provider to keep track of and send paper mail if the recipient wants it. > GET /api/v1/{kennitala}/paper Returns the paper preference of the kennitala. #### Response ```json { "kennitala": "string", "wantsPaper": true, } ``` | Variable | Type | Description | | ---------- | ------- | ------------------------ | | kennitala | String | Kennitala of the user | | wantsPaper | Boolean | Does the user want paper | | | | | > GET /api/v1/paper Returns recipients that wish to receive a physical paper document. #### Query parameters | Variable | Type | Description | | -------- | ------ | -------------------------------- | | page | Number | Requested page | | pageSize | Number | Item count of the requested page | #### Response ```json [ { "kennitala": "string", "wantsPaper": true, } ] ``` | Property | Type | Description | | ---------- | ------- | ------------------------ | | kennitala | String | Kennitala of the user | | wantsPaper | Boolean | Does the user want paper |