Documentation
Quickstart
The API endpoint is located at https://gdc.infiniteloop.ie/api.aspx 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