Introduction

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

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

The documentation below will show how to get the most out of the API and includes code samples in several popular programming languages. It also includes 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 a 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 means only you can see your pricing and order data.

To create a key, visit the preferences 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. You can disable it at any time or create a new key from the preferences page.

Accessing the API

There are two ways to access the API. The most common is to build an integration using a programming language such as Python or Java, which 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, which is the best format for automated integrations. It 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 support returning the response as a CSV file, which 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, requests made from the Web Browser will return a CSV by default, making it easy for you to add a link to get updated pricing or order information.

EXAMPLE JSON RESPONSE

Your First Request

Now we have an API key and have decided 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. It supports operations on the following object types, Customer, Address, Order, and Quote. The base URL for the API is shown on the right.

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

NetXL API Endpoint

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 use either method regardless of how you're accessing the API:

  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 as simple as appending the following key/value to the end of every URL you're making requests to:

api-key=<your-api-key>

Query String Example

Selecting the response type

Some API commands support returning the response as a CSV file, useful for importing into third party applications 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 send the `Accept` header as `application/json`. If you omit the header you will get JSON responses back by default, but it is recommended to set the header on every request This avoids any confusion if future commands have a different default response format

Making the request

Now that you have everything setup, it's time to make the first API request. We have two blog posts that show complete examples of calling the API using a programming language (Python) and a graphical tool (Postman).

  1. Read the Python API example
  2. Read the Postman API example

GET /customer

Log in to try the API commands

RESPONSE

Error Handling

There are multiple situations where the API might return an error. Most errors are caused by invalid data being provided to endpoints when asking to create objects. Consult the returned message to see why the command failed. You should also double check the documentation for the command in question to ensure the right data is being provided.

In rare cases, the API can fail due to an issue e.g. with a server, or some third party the service relies on. In most of these cases you'll not be able to fix the issue.

In all error cases, the response HTTP status code will be set, helping you to better understand the cause of the error.

Possible HTTP Error Codes

In the event of an error, the API will return one of the following error codes. In most cases a 4xx error can be fixed by adjusting the command, but a 5xx error can not

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, e.g. 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 request 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 API 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.

Error Body Response
  • message string

    Indicates what caused the returned error, especially useful for diagnosing 4xx errors

POST /order

400 Bad Request

Rate Limiting

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

Order and Quote 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 support if you want to apply for a trade or credit account.

Command Endpoints

Get your account details

Return the basic details of your account

Attributes
  • first_name string

    The first name of the account holder.

  • last_name string

    The surname of the account holder.

  • email_address string

    Login email address of the account holder.

  • accounts_email string optional

    Account email address that will receive copies of invoices

  • trade_account boolean

    Is your account flagged as a trade account.

  • credit_terms object optional

    Details of your credit account.

GET /customer

RESPONSE

Get your credit details

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

Attributes
  • credit_limit number

    Your current account credit limit.

  • total_outstanding number

    Total outstanding value of unpaid orders.

  • available_credit number

    Available credit for new orders.

  • outstanding_orders list

    List of outstanding orders, detailing each due date and amount due.

GET /customer/credit

RESPONSE

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.

Attributes
  • id string

    ID of the address, provide this in the order command to use this address..

  • contact_name string

    The recipient's name.

  • company_name string

    Name of the recipient company.

  • street_one string

    The first line of the recipient's address.

  • street_two string optional

    Second line of the recipient's address.

  • street_three string optional

    Third line of the recipient's address.

  • city string

    Recipients city.

  • state string

    Recipients county.

  • zip string

    Recipients postal code.

  • country_code string

    The two-letter country code of the address. Should be a valid country from the ISO 3166-1 alpha-2 list

  • contact_number string

    Contact phone number for the recipient. This will be provided to the courier for delivery.

GET /customer/address

RESPONSE

Create delivery address

Create a 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 be provided in international format.

POST /customer/address

RESPONSE

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 also 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, but it is possible to request that additional data is returned in the command. The method is documented below. Please be aware that requesting additional data may reduce the response speed of the command.

ENDPOINTS

The Product Object

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

Product Object
  • sku string

    The SKU for the product, used in the order command.

  • ean string

    The EAN of the product, this is normally a 13 digit EU EAN.

  • weight_kg number

    Weight of the product (including box) in kilograms.

  • box_width_mm number

    Width of the boxed product in millimetres.

  • box_height_mm number

    Height of the boxed product in millimetres.

  • box_length_mm number

    Length of the boxed product in millimetres.

  • clearance_product boolean

    Is this product a reduced/clearance product.

  • images list

    A list of the product images.

  • availability object

    Availability data for the product.

  • single_unit_cost number

    The net cost of a single unit based on your account pricing.

  • five_plus_unit_cost number

    The net cost of 5 or more units based on your account pricing.

  • ten_plus_unit_cost number

    The net cost of 10 or more units based on your account pricing.

  • name string

    The name of the product.

  • manufacturer string

    The product's manufacturer.

  • description string

    Detailed information about the product, this is the same as the copy on the NetXL product pages.

  • short_description string

    A summary of the key features of the product.

  • store_url string

    A link to the product page on NetXL.

  • categories list of string

    A list of categories this product is in.

  • attributes key/value pairs

    A list of key/value pairs for the attributes applied to the product.

  • related_products list of string

    A list of related product SKUs for this product.

  • similar_products list of string

    A list of similar product SKUs for this product.

Example Product Object

Searching the product catalogue

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

Results can also be filtered to only products in stock, or to only include/exclude clearance products.

Query String Parameters
  • manufacturer string optional

    Filter results to certain brands, supply a comma delimited list (Grandstream,Ubiquiti,2N).

  • query string optional

    Free text search of the product name/details.

  • category string optional

    category - Filter results to specific categories, e.g. IP Hardware PBX, voip Adapters.

  • clearance boolean optional

    When "true" only return clearance products, when "false" exclude clearance products, when omitted return both regular and clearance products.

  • inStock boolean optional

    When "true" only return in-stock products (false has no effect).

  • sort string optional

    How to sort the returned results, must be one of: price, availability, sku or name.

  • extra string optional

    List of extra fields to return in the response, supports the following fields: description, shortDescription, related, similar.

  • attribute string optional

    List of attributes to filter by (see attribute filtering).

GET /product

RESPONSE

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 more than 16 PoE ports.

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

GET /product?Range (ft)>=300,Range (ft)<=400

RESPONSE

Orders and Quotes

The API allows you to query your order history. Credit account customers can 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 in one go. Use this second method when you do not require pricing or shipping quotes.

ENDPOINTS

The Order Object

  • order_id number

    The NetXL ID for this order.

  • order_reference string

    The NetXL order reference. Starts either NXL or DUK depending on your packing choice.

  • customer_reference string optional

    Your order reference.

  • confirmation_code string

    The code required to confirm this order. Orders can be confirmed for up to 7 days after they are created.

  • items list

    A list of items in this order.

  • cost_net number

    The net cost of the items in the order (does not including shipping).

  • cost_tax number

    The applicable tax for the order.

  • cost_gross number

    The gross cost of the order.

  • auto_confirm boolean

    Should this order be automatically confirmed.

  • shipping_weight number

    The total weight of this order for shipping purposes.

  • shipping_options list

    A list of valid shipping methods for this order, along with a cost for each.

  • shipping_method number

    The shipping method to use for this order. Must be one returned in the shipping_options list.

  • billing_address object

    Billing address to use for the order. You can provide either the full address, or the ID of an existing address.

  • shipping_address object

    Shipping address to use for the order. You can provide either the full address, or the ID of an existing address.

Example Order Object

Creating an order

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

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

Additionally, if using auto confirmation, you will be required to provide a shipping method, or to 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 provide the following additional parameters with your order request:

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

POST /order

Order Created Successfully

Confirming an Order

Once you have 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 is 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. Alternatively, you can use your account default, provided the default method was returned in the shipping_options field when creating the order

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

PUT /order/<confirmation-code>

RESPONSE

Understanding Auto Confirmation

When creating an order, it is 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 the NetXL dashboard.

Invalid Shipping Method

If the shipping method you provided is not valid for this order, you will receive an error response. You can see the valid shipping methods by disabling auto-confirmation and creating and confirming the order as normal.

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 when auto confirmation is used, though you may 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 then create a quote for the requested items.

You will be notified via email once the quote is created, you can confirm the order using the confirmation code as normal, but with the adjusted pricing.

POST /quote

Categories & Attributes

These commands can be used to obtain a list of categories and attributes that can then be used to filter the product catalogue.

Command Endpoints

Categories

Returns a list of categories that can then be used to filter the product catalogue using the `category` query string parameter
The Category Object
  • name string

    The name of the category, can be used to filter the product catalogue.

  • children list

    Subcategories of this category.

GET /category

RESPONSE

Attributes

Returns a list of attributes and their possible values. These can then be combined into a filter using the 'attribute' query string parameter
The Attribute Object
  • name string

    The name of this attribute. Used in the product catalogue search.

  • type number

    What type of attribute this is, either Boolean (boolean), String (string) or Number (int). Affects which filters can be used in the product catalogue search.

  • possible_values list

    List of all possible values for this attribute. Can be used to help filter the product catalogue.

GET /attribute

RESPONSE

Manufacturers

Returns a list of manufacturer names. These can be used to filter the product catalogue using the `manufacturer` query string parameter.
The Manufacturer Object
  • name string

    The manufacturer name.

GET /manufacturer

RESPONSE