Global Data Consortium / Infinite Loop API

This dashboard outlines the use of the GDC API offered by Infinite Loop Development Ltd

Use the navigation on the left hand side to navigate the features of this API

Interactive Test

IP Whitelist

Your current IP address must be already on the whitelist before you can make changes to it.

Statistics

Please see below the total number of API calls per source per month

Documentation

Quickstart

The API endpoint is located at https://gdc.infiniteloop.ie/api and accepts JSON via HTTP POST in the format;
Note: ... indicates elided text
{
    "TRANSACTION_ID":"...",
    "SOURCE":"...",
    "COUNTRY":"...",
    "VAT":"...",
    "LASTNAME":"...",
    "FIRSTNAME":"...",
    "STREET":"...",
    "STREETNUMBER":"...",
    "ZIP":"...",
    "CITY":"...",
    "RECORD_LIMIT": "..."
    "HIDE_CANDIDATE": "..."
}
If matching records are found, the API should return a HTTP status 200 and with the following response for Austria ("AT")
{
"TRANSACTION_ID": "...",
"DATA": [
{
"VAT": "...",
"LASTNAME": "...",
"FIRSTNAME": "...",
"STREET": "...",
"STREETNUMBER": "...",
"ZIP": "...",
"CITY": "...",
"UPDATED" : ...,
"SOURCE" : "GVT",
"Scoring": {
  "VAT_Match": ...,
  "LASTNAME_Match": ...,
  "FIRSTNAME_Match": ...,
  "STREET_Match": ...,
  "STREETNUMBER_Match": ...,
  "ZIP_Match": ...,
  "CITY_Match": ...,
  "BIRTHMONTH_Match": ...,
  "BIRTHYEAR_Match": ...,
  "LASTNAME_Score": ...,
  "FIRSTNAME_Score": ...,
  "STREET_Score": ...,
  "CITY_Score": ...,
}
},
{...}
]
}
The "UPDATED" property indicates the date at which the data was last updated from source.

The "Scoring" element indicates a true/false for an exact property match, i.e. VAT_Match,
and a percentage match in the case of a fuzzy match, i.e. LASTNAME_Score based on its Levenshtein distance.


The "SOURCE" property indicates the originator of the data currently set to GVT (Government)


If no matching records are found, the API will return an empty array as follows;
{
"TRANSACTION_ID": "...",
"DATA": []
}
If an error has occurred, the API will return with a HTTP status 500, and a response in the form;
Typically the "Message" property of the error response may explain the error
{
"ClassName": "System.Exception",
"Message": "...",
"Data": ...,
"InnerException": null,
"HelpURL": null,
"StackTraceString": "...",
"RemoteStackTraceString": null,
"RemoteStackIndex": 0,
"ExceptionMethod": "....",
"HResult": ...,
"Source": "GDC",
"WatsonBuckets": null
}

Security

There are two levels of security used in this API, the first is an IP whitelist that allows access to authorized known IP addresses only. This is managed via the IP Whitelist option on the menu bar. Note that only previously authorized IP addresses an manage the Whitelist. The second level of security is HTTP Basic authentication, where a username and password is provided as the Authorization header. This will be provided via email.

Versioning

The request and response formats may differ for other future data sources. At the present time, the source "VAT" and countries "AT" , "DK" , "FI", "IT", "LU" , "MT" , "NL" and "PT" are available (without VAT number). The source "COMPANIESHOUSE" is available for "GB" (United Kingdom). so all requests and responses refer to this data source only. Future development of this API is inevitable, so any client code should allow for extra parameters to be added to the request, and/or extra properties to be added to the response. The flat structure of the request and response will be maintained, and the fields listed above will not be removed, renamed, or change data type.

If an inevitable breaking change were to occur, then a second API endpoint would be created such as "/v2/API.aspx", all client code should be migrated to the new API, as the previous API would no longer be maintained, but should be still available indefinitely.

In the case that the data is restricted to a certain extra-EU jurisdiction, for example Japan, then the API url for that country will be of the form https://gdc-{country}.infiniteloop.ie

Parameters

View the swagger definition of this API here; Swagger.yaml
TRANSACTION_ID
Optional parameter, Sample Value "7e90dfc5-404b-4455-95e2-4bfaaf6c5eea".
This is a unique identifier that can be used to correlate requests at a later point in time,
If it is not provided, one will be automatically generated.
Source
Mandatory parameter, Sample Value "VAT".
Determines the data source, currently "VAT", and "COMPANIESHOUSE" are the only allowed values.
COUNTRY
Mandatory parameter, Sample Value "AT".
Determines the country, currently the following countries are available Without VAT number provided
  • "AT" (Austria) JSON
  • "DK" (Denmark) JSON
  • "FI" (Finland) JSON
  • "IT" (Italy) JSON
  • "LU" (Luxembourg) JSON
  • "MT" (Malta) JSON
  • "NL" (Netherlands) JSON
  • "PT" (Portugal) JSON
  • "GB" (United Kingdom) - COMPANIESHOUSE only JSON

Whereas, With VAT number provided JSON, all EU countries are supported.
VAT
Optional parameter, Sample Value "128462293".
The VAT number of the sought individual. If this is provided, then all EU countries are available.
LASTNAME
Optional parameter, Sample Value "MATTHIAS". Fuzzy match permitted.
The family Name of the sought individual
FIRSTNAME
Optional parameter, Sample Value "RAUCH". Fuzzy match permitted.
The first Name of the sought individual
STREET
Optional parameter, Sample Value "WIESENWEG". Fuzzy match permitted.
The street address of the sought individual
STREETNUMBER
Optional parameter, Sample Value "16".
The street number of the sought individual
ZIP
Optional parameter, Sample Value "6074".
The zip code of the sought individual
CITY
Optional parameter, Sample Value "RINN". Fuzzy match permitted.
The city of the sought individual
BIRTHMONTH
Optional parameter, Sample Value "04", United Kingdom, COMPANIESHOUSE data only.
The month of birth of the sought individual
BIRTHYEAR
Optional parameter, Sample Value "1964". United Kingdom, COMPANIESHOUSE data only.
The year of birth of the sought individual
RECORD_LIMIT
Optional parameter, Sample Value "5". JSON
Sets the maximum number or results to return. Defaults to 5.
HIDE_CANDIDATE
Optional parameter, Sample Value "true". JSON
Removes any PII from the response, defaults to false.
HEARTBEAT
Optional parameter JSON
Returns the database and code version numbers.
Legal Notices
"COMPANIESHOUSE" source data within this API is under Crown copyright and reproduced with the permission of Companies House under delegated authority from the Controller of HMSO

Transaction Lookup

Search for a transaction id to retrieve information on a past request