Introduction

Welcome to the AHEAD API. This API outlines some of the standard integration capabilities offered by AHEAD Systems. Our API follows standard RESTful practices, which means that the API users can push and request information directly to and from the API using standard HTTP verbs.

We also have webhooks available that allow you to subscribe to specific order events. When one of those events is triggered, we’ll send an HTTP POST payload to the webhook’s configured URL.

In addition, we offer a variety of other custom integration paths and have setup custom EDI’s with most ERP systems, such as NetSuite, Oracle, and SAP.

For additional details and integration assistance, please contact your account manager to setup an integration consultation with our technical team.

What You Can Do with the API

The AHEAD Systems API allows you to integrate your internal operations with AHEAD Systems to automate and streamline activities such as purchasing, fulfillment and inventory management. Using our API and direct integration services you can reduce process time and lower your administration costs by pulling and pushing data directly between your system and AHEAD Systems operating platform.

Examples include:

Get automatic updates of your fulfillment orders with shipment notifications and tracking information.
Push purchase orders and fulfillment orders directly to AHEAD from your order management platform.
Update purchase and fulfillment orders with real time anticipated shipment dates.
Streamline billing reconciliation by pulling outstanding invoice information.
Pull real-time inventory information directly into your application.

Authentication

The AHEAD API supports the OAuth 2.0 protocol for authentication and authorization. AHEAD supports common OAuth 2 scenarios such as those for server and client-side applications.

OAuth 2

To begin, AHEAD will provide you with a client id and client secret which will be used to authenticate your application. You will need to provide a redirect URL which will be used to receive the access grant or authentication token.

Step 1: Obtain an access grant

To start the authentication process, your application must obtain an access grant by sending your client_id to the GET /oauth/authorize endpoint. The only unique parameter in this request is the client_id, which will be provided by AHEAD.

GET /oauth/authorize?response_type=code&client_id=myclientid HTTP/1.1
User-Agent: Example HTTP Client
Host: api.mbx.com
Accept: */*

The API server will respond with a 302 redirect to your predefined redirect URL with the access grant code as the parameter. Your application at the redirect URL can then pull the access grant code from its parameters. Alternatively, your application may elect to receive the code directly from the Location HTTP response header.

HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Status: 302 Found
Location: http://www.example.com?code=examplegrant

If the client id is not valid, the API server will return a 401 error with the error message of Invalid client_id.

Step 2: Obtain a bearer token

After receiving the access grant code from step 1, you will use it to request a bearer token from the POST /oauth/token endpoint. You will also include the client_id and client_secret provided by AHEAD within the parameter list.

POST /oauth/token HTTP/1.1
Host: api.mbx.com
User-Agent: Example HTTP Client
Accept: */*
Content-Length: 107

grant_type=authorization_code&code=t5vTMArm3dd1kufSvAw3dw&client_id=myclientid&client_secret=myclientsecret

If all the parameters are correct, the API server will respond with a JSON object containing the bearer token and for how long the bearer token is valid.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Status: 200 OK

{"access_token":"Px_SL8iAOWQVcqKqs3CU_A","token_type":"bearer",
"expires_in":10800,"refresh_token":"WURMUaWlrd0-ImwapRsHaw"}

This bearer token will be used to authorize future API requests. Since bearer tokens are set to expire after 3 hours, a refresh token can also be given to generate new bearer tokens.

Step 3: Authenticate using the bearer token

To authorize an individual request, include an authorization header with the given bearer token from step 2. For example, you can make a request to the GET /v2/authenticate endpoint to validate that your bearer token is valid.

GET /v2/authenticate HTTP/1.1
Host: api.mbx.com
User-Agent: Example HTTP Client
Accept: */*
Authorization: Bearer Px_SL8iAOWQVcqKqs3CU_A

If the request was successfully authorized, you will receive a 200 OK response with the results of the given query.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Status: 200 OK

Successfully authenticated as Example Organization

The 'q' Parameter

Requests will be passed through the "q" parameter as URI escaped JSON.

Command example:

Python

GET /v2/people?q=%7B"limit"%3A5%7D

Output Format

Results will be returned in standard JSON format.

JSON example:

JSON

{
    "count":1000,
    "offset":0,
    "total_results":54153,
    "results":
        [
            {
                ...
            }
        ],
    "errors":null
}

HTTP Verbs

The HTTP verb examples below are using the items endpoint. The actions of the verbs will work the same across all endpoints.

GET

If the API user needs to retrieve a list of items from the API, they can send a GET request to the items endpoint.

GET request example:

Python

print requests.get("https://api.mbx.com/v2/items", headers = headers(credentials.token, sig, date)).text

If the API user needs to retrieve information on a specific item from the API, they can send a GET request to the items endpoint that includes the item ID.

GET request example (for specific item):

Python

print requests.get("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

DELETE

If the API user needs to delete a record, they can send a DELETE request to the model endpoint.

DELETE request example:

Python

print requests.delete("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

POST

If the API user needs to create a record, they can send a POST request to the model endpoint.

POST request example:

Python

print requests.post("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

PUT

If the API user needs to update a record, they can send a PUT request to the model endpoint.

PUT request example:

Python

print requests.put("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text