Getting started

This is a short introduction explaining how to enable API access to a Brightpearl account and how to authenticate yourself at runtime. If you are looking for more information on the technologies, concepts and principles behind the API, please read the API fundamentals.

1. Create a trial account

While you are learning to use the Brightpearl API, we strongly recommend you setup a Brightpearl trial account to practice with. Trial accounts give you access to the same features as a paid account, but expire after 30 days.

If you are an existing Brightpearl customer, you may find it convenient to give your trial account a similar name to your actual account. For example, if your actual account is called, mycompany, you might want to call your trial account mycompanyapitest. Note that this is referred to as your account id.

A word of caution: your trial account will let you send emails just like a paid account, so only use real email addresses in your trial if you are happy for those addresses to receive emails.

Note: If you are using the API to create Orders. It is strongly recommended you set prices on sale quotes/orders and purchase orders to show as 4 decimal places. You can do this via 'SETUP > Sales > Sales Setup' Under the title 'General Sales, Credit and Quote settings' select '4 decimal places on price' and click 'Save Changes

2. Enable API access for your Brightpearl user

Access to the API can be restricted to individual users of your Brightpearl account and by default this access is disabled.

To enable access:

Log in to your account (via the Brightpearl homepage)
Click on 'Setup'
Click on 'Staff/Users'
Click on 'List staff'
Find the staff member you would like to allow API access for.
Under the API column, click on the red X. This will turn into a green tick which means that that user now has API access

3. Set up a basic test environment

The API we make public is a subset of the API we use internally, so we would like to recommend some basic tools we use for connecting to and testing the API.

Google Chrome
Advanced REST client Application for Chrome - An excellent tool that we use inhouse to make calls to our API. This application allows you to store previous calls made which is pretty useful when making lots of different calls to the API
Firefox - Firefox is good because of the extensive range of developer focused plugins available
Poster - this is a OK plugin for making calls to RESTful APIs like ours.
JSONovich - a plugin for making JSON responses easier to read.
Live HTTP Headers - a plugin which provides access to HTTP headers being sent back and forth while you are testing the API.

4. Building the URI for Authentication

The Brightpearl API is made available as a set of web services. Every call to these web services starts with an HTTP request with a URI, an HTTP method and sometimes a 'body'. We refer to an HTTP request sent by you and the subsequent server response as a 'message'.

This first message you will need is the authenticate message. This message sends your credentials to Brightpearl, which will send back a response containing an authentication token. This token will need to be passed back with any subsequent requests you make to the API.

Authenticate URI

Most URIs for Brightpearl web services follow a common syntax, but the authenticate message is slightly different. The format for the authenticate URI is:

https://ws-{datacentre-id}.brightpearl.com/{account-id}/authorise

To find your datacentre-id, refer to the table in the guide to URI syntax

The URI for the account mycompanyapitest which has the timezone of GMT would be

https://ws-eu1.brightpearl.com/mycompanyapitest/authorise

5. Authenticating

Open Firefox and Choose Tools->Poster. This will open up the the poster interface.

In the 'URL' text field, enter the Authenticate URI as described above (remembering to use the account ID and datacentre ID appropriate to you).

In the large text area at the bottom of the window, enter:

Replacing youremail and yourpassrod with the email address and Brightpearl password for the Brightpearl user you gave API acccess in step 3. Note that the API is only accessible using HTTPS, so your password is not transmitted as plain text.

If you have not used it before, the code fragment above is an example of JSON. JSON is not white-space sensitive, so don't worry about the indentation when you copy-and-paste the code into Poster

Press the 'POST' button in poster to send this request to Brightpearl as an HTTP POST. You will notice other buttons representing the most common HTTP methods and a dropdown and green 'go' buttons for the less common methods.

6. The authentication token

The response from the Brightpearl API will appear in a pop-up, and should look something like:

This is your authentication token which will allow you to use the rest of the Brightpearl without having to pass your username and password along with each message. Instead you will pass the token as an HTTP request header.

The authentication token will expire if you do not access the API for 30 minutes. After 30 minutes of inactivity, simply send another authenticate request and you will receive a new token.

There is the possibility that the authentication token may become invalidated for reasons outside the remit of the 30 minutes window therefore we do advise that requests made to the API are coded in such a way to cope with such an eventuality.

7. Using a real message

Now that you have an authentication token, you can start using the messages you see in the left-hand navigation bar. The simplest message to try first is a Warehouse GET.

You can test this in Poster by opening a new Poster window (Tools->Poster in Firefox) and entering

{uri-prefix}/warehouse-service/warehouse

in the URL field. If you can't remember what your URI prefix is, refer to the guide to URI syntax.

You should then click on the 'Headers' button/tab in the middle of the Poster window. Enter brightpearl-auth in the 'Name' text field, and your authentication token in the 'Value' text field. Press 'Add/Change'

You can now press the GET button and should see a response similar to:

8. Next steps

Congratulations! You have now connected to the Brightpearl API. Although Poster is a great tool for exploring the API, it is most likely that you will be using a programming language like Java or PHP to integrate your software with Brightpearl. Please read the API fundamentals. for some pointers on how to start building a real integration.