Corporate LinX - Documentation Library

Introduction

This document outlines a basic introduction in to interacting with the corporate LinX (“CLX”) API.  It introduces some basic API concepts like making REST calls and submitting JSON messages as well as discussing some of the basics of OData within Corporate LinX API contexts.

Step 1 - Account Setup

Corporate LinX recommends that in the first instance you ensure you have an account by going to the portal of our mutual client and signing up.

Normal User Access

By registering using a portal applications registration form this does two things:

  1. Sets up an account in our Single Sign On database
  2. Adds you as a user (puts you in the “users” role) to that portal

From there you can via the portal request more access to transactions uploaded to that portal following the CLX User Onboarding Process.

The API Method

First thing required is to build a registration request:

HTTP POSThttps://<AppURL>/Api/Account/Register
        {
            DisplayName: "Joe Bloggs",
            Email:"joe.bloggs@corporatelinx.com",
            Password:"superSecretPassword123!!",
            Culture: "en-GB",
            PhoneNumber: "01234 567 890",
            AppId: 0
        }

AppId is optional (if you don’t have one it’s not an issue, but providing this will automatically register the new account within the app).

The rest of the information here is pretty simple user information that might appear on any registration form.

Step 2 - Authentication

Next is to use these credentials to Authenticate and get a token.

HTTP POST https://<AppURL>/Api/Account/Login
        {
            User: “joe.bloggs@corporatelinx.com”,
            Pass: “superSecretPassword123!!"
        }

The server will respond with a token the value of which can be used in all subsequent calls to the API.

Step 3 - Metadata

The API describes itself through exposing metadata to us that we can use to establish the data formatting rules that it expects us to follow.  This is done in several ways. 

OData Metadata (For Standards Compliance)

The first of which is the standard OData “metablob”. 

The Corporate LinX API is split in to multiple “Contexts” and you can grab the metadata for a single context by building a URL in the form:

  https://api.corporatelinx.com/Api/{contextName}/$metadata

This will expose a large “blob” of XML data that describes the configured OData “model” exposed by the server.

At CLX we decided that this wasn’t really enough and that for our own portal use scenarios when building applications for clients you often either don’t want the whole lot or you want the data in a different format (e.g. JSON because that’s what web pages like to use best).

We therefore expose the metadata in two other forms: 

Complete Description as JSON

  The entire API is described for all contexts in JSON format at the URL:

    https://api.corporatelinx.com/Api/Getmetadata

Localised JSON Description

  Each endpoint within a context has a Getmetadata custom function defined to get only the metadata for that entity type, for example:

     https://api.corporatelinx.com/Api/B2B/Invoice/Getmetadata

Step 4 - Working with Transactions

Fetching Data

Now that you have an account and a token issued by logging in to the account, an administrative user needs to grant you access to the transactions you want to interact with, this process can vary from client to client, so for the purpose of keeping this document simple we will assume this has been completed and that the account you have created now has access to transactions.

Our API is implemented on top of the Odata standard as documented by Oasis at http://odata.org which then enables us to build a query based on our unique requirements. 

Firstly; all requests need to be HTTP GET requests and include a header named “Authorisation” with a value of “bearer <your auth token from step 2>” this will ensure that the API knows who you are.

It’s also worth noting that all our client portals have the full API mapped to Https://<website>/Api/ as an “api root” visiting any Corporate LinX portal using your favourite browser you should be able to see in the dev tools (F12 usually) something like this: 

Dev Tools

Then the URL will inform the API the question you want to ask it.

If I want a list of Invoices simply get: session.apiRoot + “B2B/Invoice” from javascript on the page.

 

Let's look at some examples:

So in this case the full URL for the request detailed above would be:

            https://dev.corporatelinx.com/Api/B2B/Invoice

 

To get a specific Invoice, I can specify an invoice ID (e value from the Id property in the previous result set) to the end of the URL like this:

               https://dev.corporatelinx.com/Api/B2B/Invoice(123)

We can also ask for data that meets filter criteria by adding the odata “$filter” parameter to the url’s query like this:

             https://dev.corporatelinx.com/Api/B2B/Invoice?$filter=DueDate gt 2020-10-01

 

In addition to that we can expand in to related inforamation to get the Lines on an invoice like this:

             https://dev.corporatelinx.com/Api/B2B/Invoice?$filter=DueDate gt 2020-10-01&$expand=Lines

 

 

This will return the nested Line items on each of the invoices in the json result.

The API Supports full "CRUD"

In addition to being able to pull data out of the system we also support “full CRUD” (Create, Read, Update, Delete) for most data types.

What this means is if you have the right privileges in the system, you can fully manage sets of data.

You can do the following:

  • POST new data to the system with a HTTP POST
  • Update data in the system but PUT-ing a new version
  • DELETE data by issuing DELETE requests.

The Upper case keywords in the list are because this is a HTTP pattern that has been established in the OData standard and it has been implemented in our API.

HTTP GET https://dev.corporatelinx.com/Api/B2B/Invoice({some Invoice Id})

Then edit one of the property values and send that transaction back to the API with a HTTP PUT to have the API apply the change to it.

Deletions work by simply issuing a HTTP DELETE request to the “get by id” URL like this:

HTTP DELETE https://dev.corporatelinx.com/Api/B2B/Invoice({some Invoice Id})

 

That leaves creation which is done using HTTP POST to the endpoint that handles the data type you want to post. So, to add a new Invoice to the system we would issue a HTTP POST to the URL https://dev.corporatelinx.com/Api/B2B/Invoice and the body of the request should be a new invoice without the primary key value populated.