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.0.1. 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"
}

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",
  "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",
  "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
  • kennitala (string): Ten-digit national id number, no hyphen
  • gender (string): male or female
  • 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, 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
  • 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",
  "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-DD format) on which the business was registered by the Directorate of Internal Revenue
  • modified_at (string): Date (in YYYY-MM-DD format) on which this business record was last modified. This refers to the legal record itself rather than the record in this database
  • updated_at (string): Date (in YYYY-MM-DD 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, or both) 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
  • 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

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 40 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
  • age
  • age_year_end
  • street
  • street_dative
  • 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
  • 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 25 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
  • kennitala
  • street
  • street_dative
  • postal_code
  • resident_country
  • resident_municipality
  • legal_residence_code
  • legal_residence_municipality
  • legal_residence_country
  • date_of_death
  • gender
  • marital_status
  • partner_kennitala
  • family_kennitala
  • 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
  • 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_en
  • description_masculine_en
  • description_feminine_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.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.