National registers API

Já’s national registers API provides access to information on:

This data is provided as a set of core resources — like people and businesses — that you query using paginated API methods. If you need the entire dataset we also provide bulk data dumps.

Versioning

The current version of the API is 1.6.0. The API uses semantic versioning, so given a version number MAJOR.MINOR.PATCH we will increment the:

  • MAJOR version when we make incompatible API changes;

  • MINOR version when we add functionality in a backwards-compatible manner; and

  • PATCH version when we make backwards-compatible bug fixes.

A change in the MAJOR version will mean a change in the API’s base URL — e.g. from https://api.ja.is/skra/v1/ to https://api.ja.is/skra/v2/. We list all changes meriting an update to the version number in the Changelog.

Authentication

To authenticate your account when making a request to the API, include your API key in the Authorization header.

If you make an API request without authentication or if you send an invalid key, you will a receive a response with a 400 Bad Request status code.

Your key carries privileges, so be sure to keep it secret. Do not share your API key in publicly-accessible areas such as client-side code.

You must make all API requests over HTTPS.

Permissions

Your API key gives you access to the API while also defining what level of access you have. Your level of access defines what resources you have access to and, for people, what level of detail API methods will return.

All API keys have access to methods that return these resources:

If you have requested access to the Companies Register (Fyrirtækjaskrá) you will be able to use methods that return these resources:

If you have requested access to the National Register (Þjóðskrá) you will be able to use methods that return these resources:

The National Register is split into three: living people who reside — or once resided — in Iceland (grunnskrá); the deceased (horfinnaskrá); and the register of foreigners (utangarðsskrá). If your API key gives you permission to access API methods that return people, you will have access to the information in one or more of these registers. The registers you can access is dependent on the plan you have chosen.

Additionally, the level of detail you will see for each of these registers (grunnskrá, horfinnaskrá, and utangarðsskrá) is dependent on your plan. The higher your level, the more detail and data the API methods will return. Grúnnskrá and horfinnaskrá have three levels of access, utangarðsskrá has two.

For more information on access levels, see Já Gagnatorg.

Coordinates

In addition to the resource permissions above your API key may also give you access to geographic coordinates for people and businesses. If so, an extra object named coordinates will be included in

  • a Person resource’s permanent_address;

  • a Business resource’s legal_address; and

  • a Business resource’s postal_address.

The coordinates object contains WGS 84 longitude and latitude, and ISN93 x and y coordinates. See the person object or business object for an example.

Note

Where available, coordinates are included for:

  • All businesses

  • All people alive and resident in Iceland

Coordinates are sourced from staðfangaskrá and are included when a non-null address matches a record in staðfangaskrá. Coverage is greater than 95% for people, and greater than 80% for businesses. When staðfangaskrá includes multiple coordinates for a street address an average point is given.

Cross-origin resource sharing

You should not share your API key in publicly-accessible areas such as client-side code. For this reason the API does not support CORS requests by default — i.e. no Access-Control-Allow-Origin header is sent with a response.

If you do wish to make browser-based requests to the API within a private environment (an intranet, for example), contact us and we will include a set origin in the Access-Control-Allow-Origin response header that is linked to your API key.

Errors and status codes

The API responds with standard HTTP status codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed due to the information provided (e.g. a required parameter was omitted), and codes in the 5xx range indicate an error with Já’s servers (these are rare).

The status codes you may encounter are:

  • 200 OK: both request and response worked as expected

  • 400 Bad Request: the request was unacceptable, likely due to a missing parameter or an invalid parameter value

  • 401 Unauthorized: you failed to provide a valid API key, or you do not have permission to access the resource you requested

  • 404 Not Found: the requested resource doesn’t exist

  • 500 Internal Server Error: Something went wrong at Já’s end

When the API returns a 4xx or 5xx status code the response body will be a JSON object describing the error. For example:

{
  "type": "error",
  "error": "no postal code 000 found"
}

Incorrect URL encoding

When you make a request to the API, all characters in the URL — including the query-string — must be encoded using UTF-8 or ASCII. UTF-8 is recommended, but if you do use ASCII then characters not in that character-set (e.g. “ð”) must be percent-encoded. These details are usually handled by your programming language’s standard HTTP library.

Some HTTP libraries will encode URLs using ISO 8859-1 (aka Latin-1). In this case, if a non-ASCII character is sent in a URL the API will return 400 Bad Request with the following JSON payload:

{
  "type": "error",
  "error": "can't decode URL using UTF-8 (see https://gagnatorg.ja.is/docs/skra/v1/#incorrect-url-encoding)"
}

If you see this error you should refer to the documentation for your HTTP library to discover how to configure it to send URLs using UTF-8 or percent-encoded ASCII.

Pagination

You can fetch any API resource in bulk by using its ‘list’ API method. For example, you can fetch a list of people, business, or municipalities. These list API methods return a common structure and support three request parameters:

  • start: Index of the first item to be included in the page. All items before this point are skipped

  • count: Maximum number of items to return (possibly fewer if the search itself yields fewer items)

  • sort: Overrides the default sorting. Pass a resource attribute name and optionally prefix it with + for ascending order or - for descending order (e.g. -name to sort in descending order by name). If there is no prefix, items will be listed in ascending order

Note that start is 1-based. Omitting it is the same as sending start=1. If start is greater than the total number of items available, the API will respond with 400 Bad Request (see Errors and status codes).

The count parameter can be any valid number from 1 to 1000. Using a value outside that range will cause the API to respond with 400 Bad Request (see Errors and status codes). Omitting the count parameter is the same as sending count=10.

Every list API method returns a JSON object with two top-level names, items and meta:

{
  "items": [
    {
      "...": "..."
    }
  ],
  "meta": {
    "api_version": 1,
    "first_item": 1,
    "last_item": 10,
    "total_items": 990
  }
}

items contains a list of the resources that match the parameters passed in the request, while meta is a dictionary that contains four keys:

  • api_version: The major version of the API. See Versioning

  • first_item: The 1-based index of the first item in the full (unpaginated) list of results. When items is an empty list, first_item will be null

  • last_item: The 1-based index of the last item in the full (unpaginated) list of results. When items is an empty list, last_item will be null

  • total_items: The total number of items, across all pages, that match the request parameters

As an example: you can request 100 people named Emil, ordered by date of birth in descending order, starting from the 101st:

curl "https://api.ja.is/skra/v1/people?name=emil&start=101&count=100&sort=-date_of_birth" -H Authorization:${JA_API_KEY}

Rate limiting

Your API key will have a pre-arranged monthly rate limit. You can check how much of your quota you’ve used, how much you have left, and your recent usage by requesting https://api.ja.is/usage/${JA_API_KEY}?format=json.

Core resources

All API methods return core resources, either as a list or as a single item. A core resource is represented as a JSON object with one mandatory name, type, that uniquely identifies the type of the core resource.

Kennitala

This is an object representing the structure and metadata of an Icelandic national id number (kennitala, plural kennitölur). You can retrieve it to check its validity and to get its associated date, check digit, and type (person or business).

{
  "type": "kennitala",
  "kennitala": "4308050530",
  "valid": true,
  "kennitala_type": "business",
  "date": "2005-08-03",
  "birth_number": 5,
  "check_digit": 3,
  "century": 21,
  "see_also": {
    "data": "https://api.ja.is/skra/v1/businesses/4308050530",
    "search": "https://api.ja.is/search?q=kennitala:4308050530"
  }
}

  • type (string): A unique identifier for the API resource type

  • kennitala (string): Ten-digit national id number, no hyphen. This will match the input parameter

  • valid (boolean): If the kennitala is valid then true, but otherwise false

  • kennitala_type (string): Either person if a personal kennitala or business if a business kennitala.

  • date (string): Date of birth (for a person) or date of registration (for a business), as parsed from the first six digits of the kennitala. YYYY-MM-DD format. If the kennitala contains an invalid date, this will be null

  • birth_number (int): Seventh and eighth digits in the kennitala as a single integer

  • check_digit (int): Ninth digit of the kennitala

  • century (int): Ordinal number of the century of birth, e.g. 20 for a person born in 1966. Note this follows the popular perception of a century (that the new century started on 1 January 2000) and not the strict sense (the new century started on 1 January 2001). If the century digit of the kennitala is invalid, this will be null

  • see_also (object): URLs provided by this and other Já APIs that provide further information related to this kennitala

Person

This is an object representing an individual, living or dead, who has been assigned a kennitala by Registers Iceland.

{
  "type": "person",
  "kennitala": "0102034579",
  "name": "Jón Jónsson",
  "short_name": "Jón Jónsson",
  "gender": "male",
  "citizenship": "IS",
  "citizenship": {
      "code": "IS",
      "name": {
          "en": "Iceland",
          "is": "Ísland"
      }
  },
  "date_of_birth": "1903-02-01",
  "date_of_birth_inferred": "1903-02-01",
  "age": 27,
  "age_year_end": 27,
  "birth_place": {
    "municipality": "0000",
    "country": {
      "code": "IS",
      "name": {
        "is": "Ísland",
        "en": "Iceland"
      }
    }
  },
  "permanent_address": {
    "street": {
      "nominative": "Edinborgargata 1",
      "dative": "Edinborgargötu 1"
    },
    "postal_code": 101,
    "town": {
      "nominative": "Reykjavík",
      "dative": "Reykjavík"
    },
    "country": {
      "code": "IS",
      "name": {
        "is": "Ísland",
        "en": "Iceland"
      }
    },
    "municipality": "0000",
    "coordinates": {
      "longitude": -21.933459,
      "latitude": 64.133525,
      "x_isn93": 356890,
      "y_isn93": 407992
    }
  },
  "legal_residence": {
    "code": "000012300010",
    "municipality": "0000",
    "country": {
      "code": "IS",
      "name": {
        "is": "Ísland",
        "en": "Iceland"
      }
    }
  },
  "december_legal_residence": {
    "code": null,
    "municipality": null,
    "country": null
  },
  "last_legal_residence": {
    "code": null,
    "municipality": null,
    "country": null
  },
  "temporary_residence": {
    "code": null,
    "municipality": null,
    "country": null
  },
  "tax_country": null,
  "family_kennitala": "0102034579",
  "partner_kennitala": "0102034579",
  "legal_residence_parent": null,
  "residence_parent": null,
  "custodians": null,
  "marital_status": {
    "code": "1",
    "description": {
      "is": "ógiftur",
      "en": "unmarried"
    }
  },
  "proxy_kennitala": null,
  "banned": true,
  "status": "dead",
  "date_of_death": "1930-02-01",
  "kennitala_requested_by": null,
  "alt_kennitala": null,
  "date_registered": null,
  "updated_at": "2010-01-02T00:00:00Z",
  "see_also": {
    "search": "https://api.ja.is/search?q=kennitala:0102034579",
    "map": "https://ja.is/kort/?type=map&x=356890&y=407992&z=11&mark=1"
  }
}

  • type (string): A unique identifier for the API resource type

  • name (string): Full name of the person

  • short_name (string): A shorter version of full name, max 31 characters (aka Miðlað nafn)

  • kennitala (string): Ten-digit national id number, no hyphen

  • gender (string): male, female, or non-binary

  • citizenship (object): A country object defining the person’s country of citizenship

  • date_of_birth (string): Date of birth in YYYY-MM-DD format

  • date_of_birth_inferred (string): Date of birth as inferred from the person’s kennitala. This is more reliable than the date_of_birth field, which can often be null

  • age (int): If alive, age of the person today. If deceased, age at death

  • age_year_end (int): If alive, age of the person on 31 December of this year. If deceased, age at death

  • birth_place (object): Place of birth. Includes municipality (for those born in Iceland) and a country object

  • permanent_address (object): Street, apartment number, postal code, town, and country. Both street and town are given as objects containing nominative and dative forms. Postal code is an integer, and country is a country object. If your API key has permission then coordinates will also be included (see Coordinates)

  • legal_residence (object): Current legal address. Contains code and municipality number (for residents of Iceland), and a country object. The code is a twelve-digit number that encodes municipality (digits 1–4), street (digits 5–8) and house (digits 9–12)

  • december_legal_residence (object): Legal address on 31 December last year. Contains a code and municipality number (for residents of Iceland), and a country object. The code is a twelve-digit number that encodes municipality (digits 1–4), street (digits 5–8) and house (digits 9–12)

  • last_legal_residence (object): Last legal address in Iceland for those no longer resident in the country. Contains a code, a municipality number, and a country object. The code is a twelve-digit number that encodes municipality (digits 1–4), street (digits 5–8) and house (digits 9–12)

  • temporary_residence (object): Temporary address for those more commonly residing elsewhere (e.g. students). Contains a code, a municipality number, and a country object. The code is a twelve-digit number that encodes municipality (digits 1–4), street (digits 5–8) and house (digits 9–12)

  • tax_country (object): A country object defining the country where this person pays their taxes

  • family_kennitala (string): A kennitala that links a married or cohabiting couple and their children. Ten-digit number, no hyphen

  • legal_residence_parent (string): The kennitala of a child’s parent living at its legal residence, in a split household

  • residence_parent (string): The kennitala of a child’s parent living at its alternative residence, in a split household

  • custodians (array): A list of a child’s custodian kennitalas

  • partner_kennitala (string): The kennitala of this person’s spouse or partner. Ten-digit number, no hyphen

  • marital_status (object): A marital status object

  • proxy_kennitala (string): If a person lives abroad and they have nominated someone to represent them in Iceland, this field will include the nominee’s kennitala

  • banned (boolean): If true, the person does not want to be contacted by parties that conduct direct marketing

  • status (string): individual (people living in Iceland), alien (foreigners living abroad), dead, or departed (people whose whereabouts is unknown)

  • date_of_death (string): Date of death, in YYYY-MM-DD format

  • kennitala_requested_by (string): Ten-digit national id number, no hyphen, of the person or business who requested this person be assigned a kennitala

  • alt_kennitala (string): In the rare instance a person was previously assigned a kennitala, it’s included here. Ten digits, no hyphen

  • date_registered (string): Date (in YYYY-MM-DD format) on which the person was registered with Registers Iceland

  • updated_at (string): Date (in YYYY-MM-DD format) on which the record was last updated

  • see_also (object): URLs provided by other Já APIs that provide further information related to this kennitala

Business

This is an object representing either:

  • a commercial entity that is registered in Iceland and has been assigned a kennitala by the Directorate of Internal Revenue; or

  • an individual who has a sole proprietorship or is otherwise registered to conduct business.

{
  "type": "business",
  "kennitala": "4308050530",
  "full_name": "Já hf.",
  "short_name": "Já hf.",
  "alt_foreign_name": null,
  "is_company": true,
  "business_type": {
    "code": "D1",
    "name": {
      "is": "Hlutafélag, almennt (hf)",
      "en": "Public limited company"
    }
  },
  "business_activity": null,
  "parent_company_kennitala": null,
  "director": "0102034579",
  "legal_address": {
    "street": {
      "nominative": "Álfheimar 74",
      "dative": "Álfheimum 74"
    },
    "postal_code": 104,
    "town": {
      "nominative": "Reykjavík",
      "dative": "Reykjavík"
    },
    "country": {
      "code": "IS",
      "name": {
        "is": "Ísland",
        "en": "Iceland"
      }
    },
    "municipality": "0000",
    "coordinates": {
      "longitude": -21.86832,
      "latitude": 64.133685,
      "x_isn93": 360363,
      "y_isn93": 406591
    }
  },
  "postal_address": {
    "street": {
      "nominative": "Álfheimar 74",
      "dative": "Álfheimum 74"
    },
    "postal_code": 104,
    "town": {
      "nominative": "Reykjavík",
      "dative": "Reykjavík"
    },
    "country": {
      "code": "IS",
      "name": {
        "is": "Ísland",
        "en": "Iceland"
      }
    },
    "municipality": "0000",
    "coordinates": {
      "longitude": -21.86832,
      "latitude": 64.133685,
      "x_isn93": 360363,
      "y_isn93": 406591
    }
  },
  "international_address": null,
  "receiver": null,
  "currency": "ISK",
  "share_capital": 80000000,
  "remarks": null,
  "banned": false,
  "isat": {
    "code": "63.99.0",
    "name": {
      "is": "Önnur ótalin starfsemi á sviði upplýsingaþjónustu",
      "en": "Other information service activities n.e.c."
    }
  },
  "vsk": [
    {
      "vsk_number": "87491",
      "isat": {
        "code": "63.99.0",
        "name": {
          "is": "Önnur ótalin starfsemi á sviði upplýsingaþjónustu",
          "en": "Other information service activities n.e.c."
        }
      },
      "opened": "2005-08-01",
      "closed": null
    }
  ],
  "date_bankrupt": null,
  "date_established": "2005-07-19",
  "registered_at": "2005-08-03T11:46:41Z",
  "deregistered": false,
  "deregistered_at": null,
  "deregistration_reason": null,
  "modified_at": "2017-01-18T00:00:00Z",
  "updated_at": "2017-01-26T15:54:38Z",
  "see_also": {
    "search": "https://api.ja.is/search?q=kennitala:4308050530"
  }
}

  • type (string): A unique identifier for the API resource type

  • kennitala (string): Ten-digit national id number, no hyphen

  • full_name (string): Legal name of the business

  • short_name (string): Short or abbreviated form of full_name. If full_name doesn’t need abbreviating, short_name will equal full_name

  • alt_foreign_name (string): An alternative name for the business in a language other than Icelandic

  • is_company (boolean): False if the data is for is a person registered for business, true otherwise

  • business_type (business type object) Legal business classification

  • business_activity (string): Short description (commonly one word) of the activity in which the business is engaged, e.g. sóknarnefnd

  • parent_company_kennitala (string): Ten-digit national id number, no hyphen, of the parent company

  • director (string): Ten-digit national id number, no hyphen, of the chairman or chief executive of the business

  • legal_address (object): Street, postal code, town and country. Both street and town are given as objects containing nominative and dative forms. Postal code is an integer, and country is a country object. If your API key has permission then coordinates will also be included (see Coordinates)

  • postal_address (object): Street, postal code, town and country. Both street and town are given as objects containing nominative and dative forms. Postal code is an integer, and country is a country object. If your API key has permission then coordinates will also be included (see Coordinates)

  • international_address (object): Street, place (town, city, etc) and country. Street and place are strings while country is a country object.

  • receiver (object): Ten-digit national id number, no hyphen, of the person or business appointed to administer the business

  • currency (string): Three-digit ISO 4217 code of the currency in which business is conducted

  • share_capital (integer): Nominal value of issued shares, in krónur

  • remarks (string): Used by the Directorate of Internal Revenue for free-form notes

  • banned (boolean): If true, the business does not want to be contacted by parties that conduct direct marketing

  • vsk (list): A list of objects each containing a VAT number (virðisaukaskattsnúmer or VSK-númer) along with the business classification object to which the number is linked. The VAT number may contain leading zeroes so it’s given as a string. If a VAT number is no longer used a date is included as closed

  • isat (object): The main business classification used by the business

  • date_bankrupt (string): Date (in YYYY-MM-DD format) on which the business filed for bankruptcy

  • date_established (string): Date (in YYYY-MM-DD format) on which the business was established

  • registered_at (string): Date (in YYYY-MM-DDTHH:mm:ssZ format) on which the business was registered by the Directorate of Internal Revenue

  • modified_at (string): Date (in YYYY-MM-DDTHH:mm:ssZ format) on which this business record was last modified. This refers to the legal record itself rather than the record in this database

  • deregistered (boolean): True if business is deregistered, false otherwise

  • deregistered_at (string): Date (in YYYY-MM-DDTHH:mm:ssZ format) on which the business was deregistered by the Directorate of Internal Revenue

  • deregistation_reason (string): The reason for the business deregistation by the Directorate of Internal Revenue

  • updated_at (string): Date (in YYYY-MM-DDTHH:mm:ssZ format) on which the business record was last updated. This refers to the record in this database rather than the legal record itself

  • see_also (list): URLs provided by other Já APIs that provide further information related to this kennitala

Postal code

This is an object representing a current or historical Icelandic postal code.

{
  "type": "postal_code",
  "postal_code": 200,
  "town": {
    "nominative": "Kópavogur",
    "dative": "Kópavogi"
  }
}

  • type (string): A unique identifier for the API resource type

  • postal_code (int): Three-digit postal code

  • town (object): Name of the town associated with the postal code, in both nominative and dative case. Both cases will always be included (i.e. no null values or empty strings)

Municipality

This is an object representing a current or historical Icelandic municipality.

{
  "type": "municipality",
  "number": "1100",
  "name": {
    "nominative": "Seltjarnarneskaupstaður"
  },
  "former_names": [
    {
      "nominative": "Seltjarnarneshreppur"
    }
  ]
}

  • type (string): A unique identifier for the API resource type

  • number (string): The municipality’s unique four-digit id. May be left-padded with zeroes

  • name (object): Name of the municipality in the nominative case

  • former_names (array): Names of any defunct municipalities that used this municipality’s unique id in the past

Note

A municipality’s name and former names are currently given only in the nominative case, but in the future we may also include other cases.

Country

This is an object representing a country as defined by Registers Iceland. This is based on ISO 3166 with extensions.

{
  "type": "country",
  "code": "IS",
  "name": {
    "en": "Iceland",
    "is": "Ísland"
  }
}

  • type (string): A unique identifier for the API resource type

  • code (string): Two-digit unique id. Based on ISO 3166 alpha-2 codes but includes additions

  • name (object): Name of the country in both Icelandic and English. The Icelandic name is provided in the nominative case only

Marital status

An object representing the marital status of a person. There are ten possible statuses:

  • 1: unmarried

  • 3: married or in a registered partnership

  • 4: widow or widower

  • 5: formally separated

  • 6: divorced

  • 7: informally separated

  • 8: married to a foreigner not registered due to extraterritorial rights (e.g. an ambassador)

  • 9: marital status unknown

  • 0: living abroad and married to a foreigner who’s not registered

  • L: living in Iceland and married to a foreigner who’s not registered

When this object is embedded in a person object the status’s descriptions are grammatically gendered based upon the person. For example, for a widowed man the Icelandic description will be ekkill and the English description will be widower; but for a widowed woman the Icelandic description will be ekkja and the English description will be widow.

When an API method returns this as a top-level object you can choose the grammatical gender (masculine, feminine, non-binary, or a generic phrase) with a query parameter.

{
  "type": "marital_status",
  "code": "1",
  "description": {
    "is": "ógift",
    "en": "unmarried"
  }
}

  • type (string): A unique identifier for the API resource type

  • code (string): One of the ten possible status codes listed above

  • description (object) Description of the marital status in both Icelandic and English

Business type

This is an object representing a legal business classification.

{
  "type": "business_type",
  "code": "D1",
  "name": {
    "is": "Hlutafélag, almennt (hf)",
    "en": "Public limited company"
  }
}

  • type (string): A unique identifier for the API resource type

  • code (string): Two-character unique id

  • name (object) Description of the business type in both Icelandic and English

Business classification

This is an object representing a classification of a field of business, known as Íslensk atvinnugreinaflokkun or ísat in Icelandic.

{
  "type": "business_classification",
  "code": "01.13.2",
  "name": {
    "is": "Ræktun á kartöflum",
    "en": "Growing of potatoes"
  }
}

  • type (string): A unique identifier for the API resource type

  • code (string): Two-character unique id

  • name (object) Description of the business type in both Icelandic and English

API methods

All requests must be made over HTTPS using the GET method. All responses will return the Content-Type application/json and a JSON object as the response body. API URLs are relative to https://api.ja.is/skra.

Blank fields are included as null instead of being omitted.

The folllwing API methods are available:

GET /v1/kennitolur/(kennitala)

Returns metadata for a kennitala. The response contains a single kennitala object.

Parameters:

  • kennitala – Ten-digit national id number, no hyphen

Query Parameters:

  • redirect – If found in the query-string, the response will return 303 See Other with the Location header set to the API endpoint for the resource. See explanation below

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/kennitolur/4308050530 -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "kennitala",
   "kennitala": "4308050530",
   "valid": true,
   "kennitala_type": "business",
   "date": "2005-08-03",
   "birth_number": 5,
   "check_digit": 3,
   "century": 21,
   "see_also": {
     "data": "https://api.ja.is/skra/v1/businesses/4308050530",
     "search": "https://api.ja.is/search?q=kennitala:4308050530"
   }
 }

Note

There are rare cases (0.0003%) of people and businesses being assigned invalid kennitölur — for example, Verzlunarskóli Íslands (690269-1399).

If you find yourself in a position where you want to look up both people and businesses without picking the correct API endpoint for each, you may call this endpoint with the redirect query-string parameter. A 303 See Other response will be returned, redirecting you to the API endpoint approriate for the kennitala’s resource type.

For example, if you were to make a HEAD request to look up Já’s kennitala, and you included redirect in the query-string:

 $ curl -I https://api.ja.is/skra/v1/kennitolur/4308050530?redirect -H Authorization:${JA_API_KEY}

You would receive a response like this:

HTTP/1.1 303 See Other
Location: https://api.ja.is/skra/v1/businesses/4308050530
Content-Type: application/json

You can then make a GET request to the URL in the Location header. Many programming languages’ HTTP libraries will handle this for you automatically.

Note

There is no guarantee that a resource matching the kennitala exists.

GET /v1/people/(kennitala)

Retrieves the details for a single person. If a match is found for the provided kennitala, the response will contain a person object.

Parameters:

  • kennitala – Ten-digit national id number, no hyphen

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/people/0102034579 -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "type": "person",
   "kennitala": "0102034579",
   "name": "Jón Jónsson",
   "...": "..."
 }

For an example of a complete response see the person object section.

GET /v1/people

Returns the details for people who match the search criteria. If the search is successful a paginated list object is returned that contains zero or more person objects.

Query Parameters:

  • kennitala – Ten-digit national id number, no hyphen. Exact match on a person’s kennitala field only

  • name – A space-separated list of whole words to search for in a person’s name field. The search is case-insensitive.

  • street – A space-separated list of words to search for in a person’s street address. Both dative and nominative forms are supported. The search is case-insensitive. Each alphanumeric search word matches prefixes and whole words. Numeric search words match whole words only (e.g. banka 2 will match Bankastræti 2 but not Bankastræti 20).

  • family_kennitala – An exact ten-digit national id number to match against a kennitala that links a married or cohabiting couple and their children

  • legal_residence_parent – An exact ten-digit national id number to match against a kennitala of a parent living at the child’s legal residence.

  • residence_parent – An exact ten-digit national id number to match against a kennitala of a parent living at the child’s alternate residence.

  • custodian_kennitala – An exact ten-digit national id number to match against a kennitala of a child’s custodians.

  • postal_code – Three-digit Icelandic postal code to match against a person’s postal address

  • status – One of individual (people living in Iceland), alien (foreigners living abroad), dead, or departed (people whose whereabouts is unknown). Access to these statuses is dependent on your permissions

All query parameters are optional but you must include at least one. You may include multiple status query parameters (e.g. status=individual&status=alien). Pagination query parameters are also accepted (see Pagination).

Status Codes:

Example request:

 $ curl -G https://api.ja.is/skra/v1/people --data-urlencode "name=jón jónsson" -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "person",
       "kennitala": "0102034579",
       "name": "Jón Jónsson",
       "...": "..."
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 562
   }
 }

The person object section contains a complete example.

GET /v1/postal-codes/(postal_code)

Retrieves the details for a single postal code. If a match is found the response will contain a postal code object.

Parameters:

  • postal_code – Three-digit Icelandic postal code

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/postal-codes/101 -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "postal_code",
   "postal_code": 101,
   "town": {
     "nominative": "Reykjavík",
     "dative": "Reykjavík"
   }
 }
GET /v1/postal-codes

Returns the details for all postal codes. A paginated list object is returned that contains at least one postal code object.

Pagination query parameters are accepted (see Pagination).

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/postal-codes -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "postal_code",
       "postal_code": 101,
       "town": {
         "nominative": "Reykjavík",
         "dative": "Reykjavík"
       }
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 149
   }
 }
GET /v1/municipalities/(number)

Retrieves the details for a single municipality. If a match is found the response will contain a municipality object.

Parameters:

  • number – Four-digit unique id

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/municipalities/6100 -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "municipality",
   "number": "6100",
   "name": {
     "nominative": "Norðurþing"
   },
   "former_names": [
     {
       "nominative": "Húsavíkurkaupstaður"
     },
     {
       "nominative": "Húsavíkurhreppur"
     },
     {
       "nominative": "Húsavíkavíkurkaupstaður"
     },
     {
       "nominative": "Húsavíkurbær"
     }
   ]
 }
GET /v1/municipalities

Returns the details for all municipalities. A paginated list object is returned that contains at least one municipality object.

Pagination query parameters are accepted (see Pagination).

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/municipalities -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "municipality",
       "number": "0000",
       "name": {
         "nominative": "Reykjavíkurborg"
       },
       "former_names": [
         {
           "nominative": ""
         }
       ]
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 303          }
 }
GET /v1/countries/(code)

Retrieves the details for a single country. If a match is found the response will contain a country object.

Parameters:
Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/countries/FR -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "country",
   "code": "FR",
   "name": {
     "is": "Frakkland",
     "en": "France"
   }
 }
GET /v1/countries

Returns the details for all countries. A paginated list object is returned that contains at least one country object.

Pagination query parameters are accepted (see Pagination).

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/countries -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "country",
       "code": "00",
       "name": {
         "is": "Ótilgreint",
         "en": "Unknown"
       }
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 263
   }
 }
GET /v1/marital-statuses/(code)

Retrieves the details for a single marital status. If a match is found the response will contain a marital status object.

Parameters:

  • code – Unique code for the marital status; one character

Query Parameters:

  • gender – A marital status’s description can be dependent on the gender of the person it’s linked to, for example widower or widow in English (ekkill or ekkja in Icelandic). By default descriptions include both grammatical cases (widower or widow), but if you want only a particular gender, pass feminine (widow) or masculine (widower)

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/marital-status/4?gender=feminine -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "marital_status",
   "code": "4",
   "description": {
     "is": "ekkja",
     "en": "widow"
   }
 }
GET /v1/marital-statuses

Returns the details for all marital statuses. A paginated list object is returned that contains at least one marital status object.

Pagination query parameters are accepted (see Pagination).

Query Parameters:

  • gender – A marital status’s description can be dependent on the gender of the person it’s linked to, for example widower or widow in English (ekkill or ekkja in Icelandic). By default descriptions include both grammatical cases (widower or widow), but if you want only a particular gender for all returned marital statuses, pass feminine (widow) or masculine (widower)

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/marital-statuses?gender=feminine -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "marital_status",
       "code": "1",
       "description": {
         "is": "ógift",
         "en": "single"
       }
     },
     {
       "...": "...",
     },
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 10
   }
 }
GET /v1/businesses/(kennitala)

Retrieves the details for a single business. If a match is found for the provided kennitala, the response will contain a business object.

Parameters:

  • kennitala – Ten-digit national id number, no hyphen

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/businesses/4308050530 -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "type": "business",
   "kennitala": "4308050530",
   "full_name": "Já hf.",
   "...": "..."
 }

For an example of a complete response see the business object section.

GET /v1/businesses

Returns the details for businesses who match the search criteria. If the search is successful a paginated list object is returned that contains zero or more business objects.

Query Parameters:

  • kennitala – Ten-digit national id number, no hyphen. Exact match against a business’s kennitala or that of its parent company or director

  • name – A space-separated list of whole words to search for in a business’s full name, short name, or alternative foreign name. The search is case-insensitive.

  • street – A space-separated list of words to search for in a businesses’s street address. Searches postal, legal, and international addresses in nominative and dative cases. The search is case-insensitive. Each alphanumeric search word matches prefixes and whole words, numeric search words match whole words only (e.g. banka 2 will match Bankastræti 2 but not Bankastræti 20).

  • postal_code – Three-digit Icelandic postal code to match against a business’s legal or postal address

  • municipality – Four-digit unique id to match against the Icelandic municipality in a business’s legal or postal address

  • business_type – Two-character code to match against a business’s type

  • include_deregistered – Boolean value to indicate if degeristered businesses should be included in the results, default is false. (unless searching by kennitala or deregistered=true)

All query parameters are optional but you must include at least one. Pagination query parameters are also accepted (see Pagination).

Status Codes:

Example request:

 $ curl -G https://api.ja.is/skra/v1/businesses --data-urlencode "name=já hf" -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "business",
       "kennitala": "4308050530",
       "full_name": "Já hf.",
       "short_name": "Já hf.",
       "...": "..."
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 2,
     "total_items": 2
   }
 }

The business object section contains a complete example.

GET /v1/business-types/(code)

Retrieves the details for a single business type. If a match is found the response will contain a business type object.

Parameters:

  • code – Two-character unique id

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/business-types/A5 -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "business_type",
   "code": "A5",
   "name": {
     "is": "Einstaklingur í atvinnurekstri með skráð firmaheiti",
     "en": "Sole proprietorship with trading name"
   }
 }
GET /v1/business-types

Returns the details for all business types. A paginated list object is returned that contains at least one business type object.

Pagination query parameters are accepted (see Pagination).

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/business-types -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "business_type",
       "code": "A1",
       "name": {
         "is": "Einstaklingur í atvinnurekstri",
         "en": "Sole proprietorship"
       }
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 38
   }
 }
GET /v1/isat/(code)

Retrieves the details for a single business classification (ísat). If a match is found the response will contain a business classification object.

Parameters:

  • code – Unique id in the format DD.DD.D, where D is a single digit

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/isat/10.52.0 -H Authorization:${JA_API_KEY}

Example response:

 {
   "type": "business_classification",
   "code": "10.52.0",
   "name": {
     "is": "Ísgerð",
     "en": "Manufacture of ice cream"
   }
 }
GET /v1/isat

Returns the details for all business classifications. A paginated list object is returned that contains at least one business classification object.

Pagination query parameters are accepted (see Pagination).

Status Codes:

Example request:

 $ curl https://api.ja.is/skra/v1/isat -H Authorization:${JA_API_KEY}

Example response (truncated for brevity):

 {
   "items": [
     {
       "type": "business_classification",
       "code": "01.11.0",
       "name": {
         "is": "Kornrækt (að undanskildum hrísgrjónum), ræktun belgjurta og olíufræja",
         "en": "Growing of cereals (except rice), leguminous crops and oil seeds"
       }
     },
     { "...": "..." }
   ],
   "meta": {
     "api_version": 1,
     "first_item": 1,
     "last_item": 10,
     "total_items": 586
   }
 }

Bulk data dumps

In addition to the API endpoints documented above, you can retrieve the complete set of items for any of the core resources using the bulk data dumps. You must make all requests over HTTPS using the GET method.

You can see what dumps are available to you (see Permissions) using the following URL:

GET /v1/dump

Returns an object containing all bulk data URLs that can be accessed with the API key provided in the Authorization header.

Example request:

$ curl https://api.ja.is/skra/v1/dump -H Authorization:${JA_API_KEY}

Example response:

{
  "grunnskra": "https://api.ja.is/skra/v1/dump/grunnskra",
  "postal_codes": "https://api.ja.is/skra/v1/dump/postal-codes",
  "municipalities": "https://api.ja.is/skra/v1/dump/municipalities",
  "former_municipality_names": "https://api.ja.is/skra/v1/dump/former-municipality-names",
  "countries": "https://api.ja.is/skra/v1/dump/countries",
  "marital_statuses": "https://api.ja.is/skra/v1/dump/marital-statuses",
  "businesses": "https://api.ja.is/skra/v1/dump/businesses",
  "business_types": "https://api.ja.is/skra/v1/dump/business-types",
  "business_classifications": "https://api.ja.is/skra/v1/dump/isat",
  "businesses_classifications": "https://api.ja.is/skra/v1/dump/businesses-isat",
  "businesses_vsk_numbers": "https://api.ja.is/skra/v1/dump/businesses-vsk-numbers"
}

Data dumps work differently to the API methods: responses will return 303 See Other with a URL in the Location header that returns a CSV data dump. The URL will expire five minutes after you receive the 303 See Other response. Upon expiry you will receive an 403 Forbidden response from the redirected URL.

The CSV data dumps are always gzip-compressed, no matter what you send in the request’s Accept-Encoding.

If you need a consistent filename for a data dump, use the value of the of the filename parameter from the Content-Disposition response header. For example, the redirected response from /v1/dump/horfinnaskra will return:

Content-Disposition: attachment; filename=horfinnaskra.csv

URLs are relative to https://api.ja.is/skra.

The following bulk data dumps are available:

GET /v1/dump/grunnskra

Returns a CSV file containing the grunnskrá register.

Grunnskrá is defined by Registers Iceland as the register of all living people who either reside in Iceland now, or have done in the past. This is equivalent to all people with the status individual.

Up to 43 columns may appear in the CSV response, although the composition of the file will depend upon the level of detail granted by your API key (see Permissions). The columns match the data available in the person object, but data that has no value for living people (e.g. date of death) is not included.

The complete list of available columns is:

  • name

  • short_name

  • kennitala

  • age

  • age_year_end

  • street

  • street_dative

  • apartment_number

  • postal_code

  • resident_country

  • resident_municipality

  • longitude

  • latitude

  • x_isn93

  • y_isn93

  • banned

  • proxy_kennitala

  • family_kennitala

  • gender

  • marital_status

  • partner_kennitala

  • legal_residence_code

  • legal_residence_municipality

  • legal_residence_country

  • legal_residence_parent

  • residence_parent

  • citizenship

  • date_of_birth

  • date_of_birth_inferred

  • birth_municipality

  • birth_country

  • december_legal_residence_code

  • december_legal_residence_municipality

  • december_legal_residence_country

  • last_legal_residence_code

  • last_legal_residence_municipality

  • last_legal_residence_country

  • temporary_residence_code

  • temporary_residence_municipality

  • temporary_residence_country

  • status

  • alt_kennitala

  • date_registered

  • updated_at

GET /v1/dump/horfinnaskra

Returns a CSV file containing the horfinnaskrá register.

Horfinnaskrá is defined by Registers Iceland as the register of the dead. This is equivalent to all people with the status dead or departed.

Up to 32 columns may appear in the CSV response, although the composition of the file will depend upon the level of detail granted by your API key (see Permissions). The columns match the data available in the person object, but some data (e.g. date of birth) is emptied by Registers Iceland upon death and thus is not included.

The complete list of available columns is:

  • name

  • short_name

  • kennitala

  • street

  • street_dative

  • postal_code

  • resident_country

  • resident_municipality

  • longitude

  • latitude

  • x_isn93

  • y_isn93

  • legal_residence_code

  • legal_residence_municipality

  • legal_residence_country

  • date_of_death

  • gender

  • marital_status

  • partner_kennitala

  • family_kennitala

  • legal_residence_parent

  • residence_parent

  • banned

  • citizenship

  • date_of_birth_inferred

  • age

  • age_year_end

  • birth_municipality

  • birth_country

  • status

  • alt_kennitala

  • updated_at

GET /v1/dump/utangardsskra

Returns a CSV file containing the utangarðsskrá register.

Utangarðsskrá is defined by Registers Iceland as the register of living people who have never been resident in Iceland. This is equivalent to all people with the status alien.

Up to 24 columns may appear in the CSV response, although the composition of the file will depend upon the level of detail granted by your API key (see Permissions). The columns match the data available in the person object, but data that has no value for living people (e.g. date of death) is not included.

The complete list of available columns is:

  • name

  • kennitala

  • street

  • street_dative

  • postal_code

  • resident_country

  • resident_municipality

  • longitude

  • latitude

  • x_isn93

  • y_isn93

  • kennitala_requested_by

  • gender

  • marital_status

  • banned

  • citizenship

  • date_of_birth_inferred

  • age

  • age_year_end

  • tax_country

  • status

  • alt_kennitala

  • date_registered

  • updated_at

GET /v1/dump/businesses

Returns a CSV file containing the complete register of businesses.

There are 41 columns in the CSV response. These columns match the data available in the business object.

The complete list of available columns is:

  • kennitala

  • full_name

  • short_name

  • alt_foreign_name

  • is_company

  • business_type

  • business_activity

  • parent_company_kennitala

  • chairman

  • board_member

  • receiver_kennitala

  • receiver_name

  • legal_address_street

  • legal_address_street_dative

  • legal_address_postal_code

  • legal_address_municipality

  • legal_address_country

  • legal_address_longitude

  • legal_address_latitude

  • legal_address_x_isn93

  • legal_address_y_isn93

  • address_street

  • address_street_dative

  • address_postal_code

  • address_municipality

  • address_longitude

  • address_latitude

  • address_x_isn93

  • address_y_isn93

  • intl_address_street

  • intl_address_place

  • intl_address_country

  • currency

  • share_capital

  • remarks

  • banned

  • date_bankrupt

  • date_established

  • registered_at

  • deregistered

  • deregistered_at

  • deregistration_reason

  • modified_at

  • updated_at

GET /v1/dump/postal-codes

Returns a CSV file containing all Icelandic postal codes used by Registers Iceland and the Directorate of Internal Revenue.

There are three columns in the CSV response. These columns match the data available in the postal code object:

  • postal_code

  • name_nominative

  • name_dative

GET /v1/dump/municipalities

Returns a CSV file containing all Icelandic municipalities used by Registers Iceland and the Directorate of Internal Revenue.

There are two columns in the CSV response. These columns match data available in the municipality object:

  • number

  • name_nominative

GET /v1/dump/former-municipality-names

Returns a CSV file containing all former names of Icelandic municipalities used by Registers Iceland and the Directorate of Internal Revenue.

There are two columns in the CSV response. These columns match data available in the former_names key of the municipality object:

  • municipality

  • name_nominative

GET /v1/dump/countries

Returns a CSV file containing all countries used by Registers Iceland and the Directorate of Internal Revenue.

There are three columns in the CSV response. These columns match the data available in the country object:

  • code

  • name_is

  • name_en

GET /v1/dump/marital-statuses

Returns a CSV file containing all marital statuses used by Registers Iceland.

There are seven columns in the CSV response. These columns match the data available in the marital status object:

  • code

  • description_is

  • description_masculine_is

  • description_feminine_is

  • description_non_binary_is

  • description_en

  • description_masculine_en

  • description_feminine_en

  • description_non_binary_en

GET /v1/dump/isat

Returns a CSV file containing all business classifications used by the Directorate of Internal Revenue.

These are known as Íslensk atvinnugreinaflokkun or ísat in Icelandic. There are three columns in the CSV response. These columns match the data available in the business classification object:

  • code

  • name_is

  • name_en

GET /v1/dump/businesses-isat

Returns a CSV that matches businesses to one or more business classification. Each row matches one business (via its kennitala) to one ísat (via its code).

  • kennitala

  • code

GET /v1/dump/business-types

Returns a CSV file containing all business types used by the Directorate of Internal Revenue.

There are three columns in the CSV response. These columns match the data available in the business type object:

  • code

  • name_is

  • name_en

GET /v1/dump/businesses-vsk-numbers

Returns a CSV that matches businesses to their VAT numbers (Icelandic: virðisaukaskattsnúmer or VSK-númer). Each row matches one business (via its kennitala) to one VAT number.

There are five columns in the CSV response. These columns match the data available in the vsk key in the business object:

  • kennitala

  • code

  • vsk_number

  • opened

  • closed

Changelog

  • v1.6.0 — 2024-04-05: Add fields apartment_number to grunnskra.

  • v1.5.0 — 2023-07-04: Add fields deregistered, deregistered_at and deregistration_reason to Business objects.

  • v1.4.0 — 2023-06-21: Add new field short_name, maximum 31 character version of name (aka Miðlað nafn)

  • v1.3.0 — 2022-09-01: Add new field custodian_details, that contains detailed information about custody of children.

  • v1.2.0 — 2022-09-01: Add new fields legal_residence_parent, residence_parent and custodians to support different types of households.

  • v1.1.2 — 2021-01-25: Return a correct JSON error response when people or businesses are filtered using a non-numeric postal code. No changes were made to the public REST API interface.

  • v1.1.1 — 2021-01-22: The marital status for a person who has chosen a non-binary gender is now returned in the masculine grammatical case.

  • v1.1.0 — 2021-01-19: Added support for Registers Iceland’s recent implementation of an individual’s right to define their own gender. The API now returns male, female, or non-binary for a person’s gender. Previously the only supported values were male or female.

  • v1.0.11 — 2020-08-19: Changes to our internal workflow. No changes were made to the public API.

  • v1.0.10 — 2020-03-17: Minor improvements to make the data import more robust. No changes were made to the public API.

  • v1.0.9 — 2020-02-18: Internal improvements to our API monitoring. No changes were made to the public API.

  • v1.0.8 — 2020-01-02: Due to changes in the source data, a person’s family_kennitala field (fjölskyldunúmer) may now be null. Previously, the field was always populated with a kennitala.

  • v1.0.7 — 2019-10-03: Added support for the new postal codes that came into use on 1st October 2019: 102, 161, 206, 342, 604–607, and 803–806.

  • v1.0.6 — 2019-09-11: Added documentation on Incorrect URL encoding.

  • v1.0.5 — 2019-09-10: Internal improvements to the API. No changes were made to the public API.

  • v1.0.4 — 2019-01-10: Addresses for people and businesses in Sandgerði and Garður now use the merged municipality’s new name, Suðurnesjabær.

  • v1.0.3 — 2018-06-12: Added support for the new merged municipality of Sandgerði and Garður.

  • v1.0.2 — 2017-12-04: Addresses for people and businesses now use Iceland’s new postal codes where appropriate.

  • v1.0.1 — 2017-08-31: Improvements to the internal administration of API key permissions. No changes were made to the public API.

  • v1.0.0 — 2017-06-13: Initial release.