Introduction

The NetXL API is a powerful set of tools that allow you to automate key interactions with us. These include getting real-time pricing and stock availability, requesting quotes, and creating and confirming orders.

The API is free and available to all trade customers, however to create an order you are required to have a credit account. Payment via PayPal and Credit/Debit card is not currently supported by the API.

The documentation below will show how to get the most out of the API. It includes code samples in several popular programming languages, as well as guides on using the API with several popular GUI based tools; perfect for customers with less development experience.

Getting Started

First things first, in order to use the API, you will need to create an API key. We use this to identify the requests you make as coming from your account, which ensures we return the correct information to you, and nobody else can see your pricing and order data.

To create an API key, visit the API section of the NetXL customer dashboard.

Your API key is unique to your account; you should not share it with anyone you do not trust, and you can disable it at any time or create a new key from your dashboard.

Accessing the API

There are two main ways to access the API. The most common is to build an integration using a programming language such as Python or Java. This allows you to automate calls to the API, tightly integrating into existing systems.

The other way is to use a graphical tool such as Postman or Paw (or even a Web Browser). This method lets you query the API for data on an ad-hoc basis, without any need for computer programming experience.

Response Data Formats - JSON & CSV

By default, the API will return all responses in JSON format. This is the best format for automated integrations, and is also human readable due to its structured layout and key/value structure. An example response for the /customer command is shown on the right.

Several API commands also support returning the response as a CSV file; this is useful for customers who wish to import the data into a third party such as Microsoft Excel or Google Sheets. How to return a CSV is explained below. Additionally, any requests made from a Web Browser will return a CSV by default, making it easy for you to create links to updated pricing or order information.

Your First Request

Now that we have an API key and have decided on how to access the API (programmatically or with a tool), it's time to make our first request.

The NetXL API is a RESTful API. The base URL for the API is shown on the right.

For our first request, we'll ask the API to return our customer information, which includes our name, email address, and details of any credit account we hold.

Authenticating your API requests

For every request you need to provide the API key as a form of authentication. There are two ways to do this, and you can choose whichever you prefer:

1. Supply the key as a HTTP Header in the request
2. Use a Query String in the URL to provide it

Provide the key as a HTTP header

To provide the API key as an extra HTTP header, include the following header in your HTTP requests

X-Api-Key: <your-api-key>

Provide the key using a query string

Providing the API key using a query string is a simple as appending the following key/value to the end of every URL you're making requests to

api-key=<your-api-key>

Selecting the response type

Some API commands support returning the response as a CSV file, useful for importing into third party application such as Microsoft Excel or Google Sheets.

To request the response as a CSV file you should set the 'Accept' header on your request to `text/csv` as follows

Accept: text/csv

All other requests should set the `Accept` header to `application/json`. This is currently the default response type, however it's recommend to send the header on every request to avoid confusion should this change for future commands.

Making the request

Now that you have everything set up, its time to make your first API request. We have a blog post containing examples of calling the API both using a programming language (Python) and a graphical tool (Postman).

1. Read the API beginner's guide

Error Handling

If you receive an error response from the API, the first thing you should check is the HTTP response status code.

Most errors are caused by invalid requests being sent to the API. In these cases we'll return a 4xx status code, and it should be possible to fix the error by making changes to the request you are sending.

You should double-check the documentation for the command in question, and it can also be helpful to consult the message returned in the response body, to see why the command failed.

In rare cases, the API can fail due to a server side issue. In this case we'll return a 5xx status code, and you'll likely not be able to fix the issue yourself. You can try the request again at a later date, or contact our support team for assistance.

Possible HTTP Error Codes

Below is a list of the most common error codes the API can return. You can read more about HTTP status codes here

400 Bad Request

Indicates that the API could not complete the request, check the response message for the cause of the error

401 Unauthorized

Your API key is not valid, please check it and try again

402 Payment Required

Insufficient available credit on your account.

404 Not Found

This indicates either the URL was not valid, or the object you requested does not exist, for example trying to query an invalid order reference

409 Conflict

The request could not be processed as it would cause duplicated data to be created. Check the response message for details

429 Too Many Requests

Your requests to the API have been rate limited, please wait 5 minutes and try your command again

500 Internal Server Error

An unexpected error occurred in the API, you should try your command again or contact support for assistance

503 Service Unavailable

The API is temporarily unavailable, try your command again in a few minutes

504 Gateway Timeout

A third party service the API relies on is unavailable, try your command again in a few minutes

Rate Limiting

To ensure system stability and performance of the service, the rate of requests you can send to the API is limited. If you exceed the limit, you will receive a 429 HTTP status code response, and should retry your command after a short delay.

The Order and Quote creation commands are not rate limited.

Account Details & Addresses

These commands allow you to query your account details, including your credit status and shipping addresses.

Contact our support team if you wish to apply for a credit account.

Get your account details

Return the basic details of your account

Get your credit details

Return the details of your credit account, including your credit limit, total outstanding order value, and available credit. The response will also include details of any open orders.

Get Addresses

Return a list of all active addresses on the account. The "id" field can be used in the /order command to avoid having to supply full address data every time.

Create delivery address

This command can be used to create a new address, whose ID can then be reused when creating orders.

Important! Please ensure the correct country code is provided; incorrect codes (such as GB for Jersey) will result in incorrect shipping estimates and may result in orders being cancelled.

For UK addresses, the 'contact_number' field can be provided in either local or international format (e.g. 0330043300 or +44330043300). For all other countries the number should always be provided in international format.

Product Catalogue

One of the key features of the API is the ability to search and filter the product catalogue. Products can be filtered by manufacturer, category or attribute. The catalogue can additionally be searched using a free text field.

Each product that is returned will include a single, 5+ and 10+ price. These prices reflect any custom pricing or discounts applied to your account.

Real time stock info is returned for each product; the number available at the time of the request is returned in the product object. Additionally, trade account customers can see the expected arrival dates of new stock from manufacturers.

By default only a subset of the product data is returned, however, it is possible to request the additional data is returned in the command, as documented below. Please be aware that requesting additional data may reduce the response speed of the command.

The Product Object

The product object provides comprehensive details about every product available via NetXL.

Searching the product catalogue

In order to search and filter the product catalogue, you should build up a query string to append to the end of the API endpoint (https://api.netxl.com/product). This query string allows you to filter the catalogue by manufacturers, categories, and attributes.

Attribute Filtering

String attributes can be filtered by equality, for example:

supports_poe=true

Number attributes can be filtered by < <= = => >, for example:

poe_ports>=16

This would query all switches with at least 16 PoE ports.

A list of attributes and their types can be obtained using the attribute list command.

Orders and Quotes

The API can be used to query your order history. Credit account customers can also create orders using their credit limit.

There are two ways to create an order. The first is a two step process, where the order must be confirmed using a secondary API call.

The other is a single call, that will create and confirm the order at once. Use this method when you do not require pricing or shipping quotes.

The Order Object

Creating an order

To create an order, you need to provide three key things to the API:

1. A reference for you to identify this order
2. A list of Item SKU's and quantities you wish to order
3. The billing and shipping addresses

Additionally, if using auto confirmation, you will be required to provide a shipping method, or set a default method in the NetXL dashboard.

Providing the item list

For each item you wish to order, you are required to provide the SKU and the quantity of units required. SKU's can be obtained using the product catalogue search or from the NetXL website.

Billing & Shipping Addresses

For the addresses, you can either provide the full address details, or use an existing address by providing it's ID. If you provide both the details and an ID, then the ID will take priority and the details will be ignored.

Optional Additional Parameters

You may additionally provide the following additional parameters with your order request:

1. auto_confirm: Should this order be automatically confirmed
2. shipping_method: The shipping method to use for this order

Confirming an Order

Once you've created an order, you can check the pricing and shipping costs. If you're happy with these, you can use the confirmation_code provided to confirm the order. It's at this point that your order will be placed and entered into our fulfilment queue.

Confirming the order

To confirm the order, you need to provide a shipping method. If no shipping method is provided but you have a default method set on your account, we will try to use this where applicable (i.e. where the default method was returned in the shipping_options field). Otherwise you will receive an error response.

Upon confirming your order, the response will include an order ID and reference from NetXL. These can be used to query the order API, or when contacting NetXL for assistance.

Understanding Auto Confirmation

When creating an order, it's possible to skip the confirmation stage by setting `auto_confirm` to true in the original request.

In order to use auto-confirmation, you must send a shipping_method parameter in your request, or have a default shipping method set in your NetXL dashboard.

Invalid Shipping Method

If the shipping method you provided is not valid for the order, you will receive an error response. You can check the valid shipping methods by disabling auto-confirmation flag.

Pricing

Auto confirmed orders will use the current live price for each item. This may be more or less than the previous price paid for an item. NetXL will not provide refunds for differences in price where an item has increased in price. You may however still cancel an order prior to shipping.

Cancel or Amend Order

To cancel or make changes to an order, please raise a support ticket or call 0330 043 3000 for assistance.

Requesting a Quote

To request a quote for an order, send your POST request to /quote instead of /order. This will raise a ticket with NetXL customer support, who will create a quote for the requested items. You will be notified via email once the quote has been created.

Preconfiguration

Once an order has been created, you can then submit configuration details for any order items that support preconfiguration.

Categories & Attributes

Categories

Attributes

Manufacturers