API

Overview

LinXmart provides an optional web-based API, allowing the management and orchestration of data through the system.

Any client that supports HTTP can be used.

The table below outlines the four main HTTP operations (methods) that are supported and their general usage.

Method	Description
GET	Retrieve an resource or a list of resources.
POST	Add a new resource to an existing resource.
PUT	Update an existing resource.
DELETE	Remove an existing resource.

Base URL

All URLs referenced in the documentation will have the following base:

https://<hostname>/api/v<version>

The LinXmart API uses versioning via the URL - the latest version is 3.2.

All calls are also forced over HTTPS for data privacy, ensuring encryption across the wire.

Resources

The following diagram shows the Resources available via the API and their relationships.

Data linkage process

• Data Providers are created to represent organisations that are custodians of data to link. Each Data Provider has one or more Event Types created representing a dataset type, the file layout described by an Import Format;
• A Project is created to contain the linkage data;
• Envelopes containing linkage data files are uploaded to the server - these contain a reference to the Project. These data files are all linked by the system and a Linkage is created for each one;
• An Extraction Project is created under a Project to group together a set of extraction results. This can either be for enduring linkage keys that persist over time, or point in time extractions based on the date and time of the creation of the Extraction Project;
• Envelopes containing extraction data files are uploaded to the server - these contain a reference to the Extraction Project. An Extraction is created for each one;
• When the Extractions are complete, the Results can be downloaded.

Requests

The LinXmart Web API supports JSON with its response. The Accept header should be set appropriately.

• For JSON, set the Accept header to application/json.

Credentials

All requests require NTLM or Bearer Token authentication to be passed - this is done with the Authorization request header. If no credentials are sent, a 401 UNAUTHORIZED is returned.

The account used for authentication must be added as a user in LinXmart with the Access to the system via the Web API application permission.

Fetching lists of items

Some resource GETs provide limit and offset query parameters for paging of large result sets.

Response Codes

The table below shows the possible response codes from the API.

Operation	Description
200 OK	The request was successful.
201 CREATED	The request was successful and a new resource has been created. The new resource URI is returned in the Location header response.
202 ACCEPTED	Record marked for deletion (EventType and DataProvider).
204 NO CONTENT	The request was successful and the response was empty.
304 NOT MODIFIED	Record exists but the file already deleted (Result)
400 BAD REQUEST	The data provided in the request failed validation or was not appropriate in context.
401 UNAUTHORIZED	The credentials provided for the request were invalid.
404 NOT FOUND	The resource requested was not found.
405 METHOD NOT ALLOWED	The HTTP method in the request is not supported by the resource.
409 CONFLICT	There is a conflict with the data that has been provided and the change has been abandoned.

Details

A full API reference is available.

📄️ API Reference