Endpoints

The MBX API currently supports for the following endpoints. The comments to the right of each endpoint parameter describe what information is needed.

countries

Method: GET

This endpoint is used to look up the available countries and their corresponding ISO codes. The columns associated with this endpoint include:

Field Name Data Type
created_at datetime (8)
id int
iso_code nvarchar (510)
name nvarchar (510)
updated_at datetime (8)

API request:

Python
apiServer = "https://api-sandbox.mbx.com"
credentials = Credentials('public-token-provided-by-mbx',
                          'secret-token-provided-by-mbx')

date = datetime.datetime.now().isoformat()
country_id = '0'                                                # The country_id value will represent
                                                                ## the country number or ID being 
                                                                ## requested.

url = '/v2/countries/' + country_id                             # This line will include the endpoint
                                                                # If no country_id value is provided
                                                                ## after the endpoint, the query will
                                                                ## return all available results for
                                                                ## that endpoint.
data = "{}"

sig = signature(credentials.secret, 'GET', data, url, date)     # This line will include the HTTP
                                                                ## verb or method used for the push
                                                                ## or request. This example is using
                                                                ## a GET request.

print requests.get(apiServer + url, data=data, headers = headers(credentials.token, sig, date)).text

API response:

JSON
{
    "count": 232,
    "total_results": 232,
    "offset": 0,
    "results": [
        {
            "id": 1,
            "name": "Jersey",
            "iso_code": "JE",
            "created_at": "2015-06-24T13:41:11.563Z",
            "updated_at": "2015-06-24T13:41:29.573Z"
        },
        {
            "id": 2,
            "name": "American Samoa",
            "iso_code": "AS",
            "created_at": "2015-06-24T13:41:11.563Z",
            "updated_at": "2015-06-24T13:41:29.573Z"
        },
        {
            "id": 3,
            "name": "Australia",
            "iso_code": "AU",
            "created_at": "2015-06-24T13:41:11.563Z",
            "updated_at": "2015-06-24T13:41:29.573Z"
        },
        ...
    ]
}

customer_catalog_items

Method: GET

This endpoint is used to view prices and SKUS on customer catalog items. Attributes of this endpoint include item ID, price, and customer SKU. The columns associated with this endpoint include:

Field Name Data Type
id int
customer_sku nvarchar (510)
price decimal (5)
item_id int

customer_order_submissions

Method: POST

This endpoint is used to submit new orders and view orders in process. Attributes of this endpoint include customer order information, importer of record, shipment information and method. The columns associated with this endpoint include:

Field Name Data Type
created_at datetime (8)
customer_data nvarchar (-1)
customer_order nvarchar (510)
id int
importer_of_record_id int
notes nvarchar (-1)
organization_id int
promise_date date (3)
purchase_order nvarchar (510)
recipient_id int
ship_account nvarchar (510)
ship_method_id int
updated_at datetime (8)
duties_and_taxes_account nvarchar (255)

To submit a new order, you will use the POST method and follow the API POST request example.

API POST request:

Python
apiServer = "https://api-sandbox.mbx.com"
credentials = Credentials('public-token-provided-by-mbx',
                          'secret-token-provided-by-mbx')

date = datetime.datetime.now().isoformat()
url = '/v2/customer_order_submissions'                          # This line will include the endpoint.
data = "{}"

sig = signature(credentials.secret, 'POST', data, url, date)    # This line will include the HTTP
                                                                ## verb or method used for the push
                                                                ## or request. This example is using
                                                                ## a POST push.

print requests.post(apiServer + url, data=data, headers = headers(credentials.token, sig, date)).text

{
    "organization_id": 01234,                       # Customer organization ID
    "purchase_order": "56789",                      # Customer purchase order number
    "customer_order": "MBX-01234-56789",            # Customer internal order number
    "ship_method_id": 12,                           # Shipment method ID - See the Shipping Appendix
                                                    ## at the bottom of the document for
                                                    ## specific IDs
    "ship_account": "333444555",                    # The shipping account number that will be
                                                    ## billed - Optional
    "notes": "",                                    # Order level notes
    "customer_rma_case": "",                        # RMA case number 
    "recipient": {
        "name": "John L. Doe",                      # Recipient first and last name
        "company": "John L. Doe Ltd.",              # Recipient company name
        "email": "jdoe@email.com",                  # Recipient email address
        "phone": "1-555-555-6789",                  # Recipient phone number
        "address_1": "467 Highway #1",              # Recipient street address 1
                                                    ## Maximum 35 characters per address line
        "address_2": null,                          # Recipient street address 2 - Optional
        "address_3": null,                          # Recipient street address 3 - Optional
        "city": "Toronto",                          # Recipient city
        "state": "ON",                              # Recipient state or providence
        "zip": "M5A 123",                           # Recipient zip code
        "country": "CA"                             # Recipient country ISO code - See countries endpoint
    },
    "importer_of_record": {
        "name": "Max Power",                        # Importer first and last name
        "company": "Generic Inc.",                  # Importer company name
        "email": null,                              # Importer email address
        "phone": "1-555-555-1234",                  # Importer phone number
        "address_1": "123 Main Street",             # Importer street address 1
                                                    ## Maximum 35 characters per address line
        "address_2": "Unit 10",                     # Importer street address 2 - Optional
        "address_3": null,                          # Importer street address 3 - Optional
        "city": "Mississauga",                      # Importer city
        "state": "ON",                              # Importer state
        "zip": "L5L 123",                           # Importer zip code
        "country": "CA"                             # Importer country ISO code - See countries endpoint
    },
    "duties_and_taxes_account": 10000000,           # Duties and taxes account number
    "lines": [
        {
            "product_code": "Generic Product 1",    # Product code
            "quantity": 2,                          # Product quantity
            "customs_declared_value": 123.4,        # Unit customs value
                                                    ## The customs value for the order line will
                                                    ## be this value multiplied by
                                                    ## the product quantity
        },
        {
            "product_code": "Generic Product 2",    # Product code
            "quantity": 1,                          # Product quantity
            "customs_declared_value": 123.4,        # Unit customs value
        }
    ],
}

API POST response:

JSON
{
    "organization_id": 01234,
    "purchase_order": "56789",
    "ship_method_id": 24,                               # Shipping method ID that was used
    "ship_method": "FedEx Ground Canada",               # Shipping method that was used
    "ship_account": "0123456789",
    "end_user_po": "0123456789",
    "end_user_name": "Jane L. Doe",
    "end_user_order_dt": "2015-04-30T14:36:13.073726",
    "customer_order": "123456",
    "notes": "",
    "recipient": {
        "name": "John L. Doe",
        "company": "John L. Doe Ltd.",
        "email": "jdoe@email.com",
        "phone": "1-555-555-6789",
        "address_1": "467 Highway #1",
        "address_2": null,
        "address_3": null,
        "city": "Toranto",
        "state": "ON",
        "zip": "MSA",
        "country": "CA"
    },
    "importer_of_record": {
        "name": "Joe L. Doe",
        "company": "",
        "email": null,
        "phone": "1-555-555-8675",
        "address_1": "456 Second Street",
        "address_2": "Unit 10",
        "address_3": null,
        "city": "Mississauga",
        "state": "ON",
        "zip": "L5L 5Z9",
        "country": "CA"
    },
    "duties_and_taxes_account": 10000000,
    "invoices": [                                       # Invoices - Will not show up until the order
                                                        ## status is Shipped
       {
           "invoice_number": 123456                     # Invoice number for this line
       }
            ],
    "tracking_numbers": [                               # Tracking numbers - Will not show up until
                                                        # the order status is Shipped
       {
           "tracking_number": "ABCD123EFG456HIJ78",     # Tracking number for this line
           "weight": 10                                 # Weight for this line
       }
            ],
     "status": "shipped",                               # Shipping status - Pending, Released, or
                                                        ## Shipped
     "notes": "",
     "lines": [
         {
             "product_code": "Generic Product 1",
             "quantity": 1,
             "customs_declared_value": 123.4,
             "serial_numbers": [
                "555-666-777"                          # Serial number for this product code
             ]
         }
    ]
}

inventories

Method: GET

This endpoint is used to view customer-owned inventories. Attributes of this endpoint include item ID, inventory allocation and location. The columns associated with this endpoint include:

Field Name Data Type
id int
item_id int
inventory_location_id int
quantity_on_hand decimal (9)
quantity_allocated decimal (9)
quantity_on_order decimal (9)

API request:

Python
apiServer = "https://api-sandbox.mbx.com"
credentials = Credentials('public-token-provided-by-mbx',
                          'secret-token-provided-by-mbx')

date = datetime.datetime.now().isoformat()
inventory_id = '0'                                              # The inventory_id value will
                                                                ## represent the inventory number
                                                                ## or ID being requested.

url = '/v2/inventories/' + inventory_id                         # This line will include the endpoint.
                                                                # If no inventory_id value is
                                                                ## provided after the endpoint, the
                                                                ## query will return all available
                                                                ## results for that endpoint.
data = "{}"

sig = signature(credentials.secret, 'GET', data, url, date)     # This line will include the HTTP
                                                                ## verb or method used for the push
                                                                ## or request. This example is using
                                                                ## a GET request.

print requests.get(apiServer + url, data=data, headers = headers(credentials.token, sig, date)).text

API response:

JSON
{
    "quantity_on_order": 0.0,                           # Quantity of inventory on order
    "created_at": "2014-07-25T11:19:43.940Z",
    "quantity_allocated": 0.0,                          # Quantity of allocated inventory
    "updated_at": "2015-04-01T08:12:31.847Z",
    "average_cost": 0.0,                                # Average cost for the inventory
    "quantity_on_hand": 0.0,                            # Quantity of inventory in stock
    "item_id": 127188,                                  # Item number or id associated to the
                                                        ## inventory
    "last_cost": 0.0,                                   # Last cost of the inventory
    "inventory_location_id": 1,                         # Location of the inventory
    "reorder_level": 0.0,                               # Reorder level for the inventory
    "id": 22742,                                        # Inventory number or id
    "order_up_to_level": 0.0,                           # Maximum order level for the inventory
    "lead_time": null                                   # Lead time for the inventory
}

invoices

Method: GET

This endpoint is used to view customer invoices. Attributes of this endpoint include billing and order information. The columns associated with this endpoint include:

Field Name Data Type
billed_at datetime (8)
created_at datetime (8)
id int
order_id int
total decimal (9)
updated_at datetime (8)

API request:

Python
apiServer = "https://api-sandbox.mbx.com"
credentials = Credentials('public-token-provided-by-mbx',
                          'secret-token-provided-by-mbx')

date = datetime.datetime.now().isoformat()
invoice_id = '0'                                                # The invoice_id will represent the
                                                                ## invoice number or ID being
                                                                ## requested.

url = '/v2/invoices/' + invoice_id                              # This line will include the endpoint.
                                                                # If no invoice_id value is provided
                                                                ## after the endpoint, the query
                                                                ## will return all available
                                                                ## results from that endpoint.
data = "{}"

sig = signature(credentials.secret, 'GET', data, url, date)     # This line will include the HTTP
                                                                ## verb or method used for the push
                                                                ## or request. This example is using
                                                                ## a GET request.

print requests.get(apiServer + url, data=data, headers = headers(credentials.token, sig, date)).text

API response:

JSON
{
    "count": 1,
    "total_results": 123,
    "offset": 0,
    "results": [
        {
            "id": 123456,                               # Inventory number or id
            "order_id": 654321,                         # Order number
            "billed_at": "2014-10-15T06:00:00.000Z",    # Date/time the invoice was billed
            "total": 0.0,                               # Total amount billed on the invoice
            "created_at": "2014-10-15T06:00:00.000Z",   # Date/time the invoice was created
            "updated_at": "2014-10-15T06:00:00.000Z"    # Date/time the invoice was updated
        }
    ],
    "errors":null
}

items

Method: GET

This endpoint is used to view customer-owned items. Attributes of this endpoint include item ID, name, and description. The columns associated with this endpoint include:

Field Name Data Type
id int
name nvarchar (510)
description nvarchar (510)
archived_at datetime (8)

API request:

Python
apiServer = "https://api-sandbox.mbx.com"
credentials = Credentials('public-token-provided-by-mbx',
                          'secret-token-provided-by-mbx')

date = datetime.datetime.now().isoformat()
item_id = '0'                                                   # The item_id value will represent
                                                                ## the item number or ID being
                                                                ## requested.

url = '/v2/items/' + item_id                                    # This line will include the endpoint.
                                                                # If no item_id value is provided
                                                                ## after the endpoint, the query
                                                                ## will return all available
                                                                ## results from that endpoint.

data = "{}"

sig = signature(credentials.secret, 'GET', data, url, date)     # This line will include the HTTP
                                                                ## verb or method used for the push
                                                                ## or request. This example is using
                                                                ## a GET request.

print requests.get(apiServer + url, data=data, headers = headers(credentials.token, sig, date)).text

API response:

JSON
{
    "item_category_id": 12,                             # Category number or ID associated to the
                                                        ## item
    "stocked": false,                                   # Item stocking status (true when stocked,
                                                        ## false when not stocked)
    "description": "Generic Appliance",                 # Item description
    "weight": null,                                     # Item weight
    "serialized": true,                                 # Item serial status (true when serialized,
                                                        ## false when not serialized)
    "created_at": "2009-02-17T10:52:00.000Z",
    "purchasing_group_id": 1,
    "updated_at": "2015-05-12T11:53:36.030Z",
    "manufacturer_sku": null,
    "archived_at": "2015-05-12T11:53:36.030Z",
    "manufacturer_id": null,                            # Manufacturer number or ID associated to the
                                                        ## item
    "owner_id": 12345,                                  # Customer number or ID associated to the
                                                        ## item
    "id": 123456,                                       # Item number or ID
    "name": "Generic Appliance"                         # Item name
}

ship_methods

Method: GET

This endpoint is used to view shipping methods. The fields associated with this endpoint include:

Field Name Data Type Description
id int Unique ID of the shipping method
name nvarchar (510) Display name for the shipping method
description nvarchar (510) Method description
carrier nvarchar (510) Name of the company providing the shipping services

automation_queues

Method: GET

This endpoint retrieves the automation queues associated with your organization.

Field Name Data Type Description
id int Unique ID of the automation queue
serial_id int Serial associated with the automation queue
work_order_id int Work order associated with the automation queue
finished boolean True if the automation queue was successfully finished
ip_address nvarchar (255) IP address of the system

Method: POST

This endpoint is used for direct integration into Forge, our image/test environment. Only used in cases when customer specific software is run outside of Forge and image/test status needs to be updated within our system. Sending a POST request creates a list of preset tasks to be executed. The columns associated with this endpoint include:

Field Name Data Type Required? Description
manufacturer_serial string (256) yes The serial of the system
automation_tasks array yes Item tasks that the system must complete. See "Task data" for more details
ip_address string yes The IP of the system

API POST Example:

JSON
{
    "manufacturer_serial": "124567",                     # The serial number of the system
    "ip_address": "8.8.8.8",                             # The IP of the system
    "automation_tasks":[{                                # Item tasks that the system must complete
      "task_type_id": 1,                                 ## See below for additional task data information
      "sequence": 1
    },{
      "task_type_id": 2,
      "sequence": 2,
      "assignee_id": 123456
    }]
}

Task Data:

Field Name Type Required? Description
task_type_id int yes The id for the task type. See automation_task_types endpoint below for more details
sequence int yes An integer which identifies a task within a queue - must be unique per queue
assignee_id int no Specifies who is responsible for running the task. This is used when some tasks have to be run in Forge and others have to be run outside of Forge.

automation_task_types

Method: GET

This endpoint is used for direct integration into Forge. Sending a GET request returns a list of the available task types. The columns associated with this endpoint include:

Field Name Data Type Required? Description
id int yes The primary key of the row
name string (256) yes A human readable task name
description string (256) no A human readable task description

automation_tasks

Method: PUT

This endpoint is used for direct integration into Forge. Used for updating the status of a registered task. The columns associated with this endpoint include:

Field Name Data Type Required? Description
manufacturer_serial string (256) yes The serial number of the system
message_type string yes The action to be taken for this serial. Must be a valid message type value (see below)
message string (256) no A status update for the operator
sequence int yes Defines which task this update is for. Checked against the sequence submitted when the queue is created
ip_address string yes The IP address of the system

Valid message_type values:

Value Description
"start" Marks the task as started
"complete" Marks the task as usccessfully completed
"fail" Marks the task as failed and creates a new unstarted task
"notify" Updates the latest message for the task

API PUT Examples:

JSON
{
    "manufacturer_serial": "124567",                     # The serial number of the system
    "ip_address": "8.8.8.8",                             # The IP of the system
    "sequence": 0,                                       # Sequence of the task the update is for
    "message": "Started Run-In",                         # A status update on the current action to be seen by the operator
    "message_type": "start"                              # The action to be taken on the serial
}
JSON
{
    "manufacturer_serial": "124567",                     
    "ip_address": "8.8.8.8",                             
    "sequence": 0,                                       
    "message": "Reticulating splines",                       
    "message_type": "notify"                              

serial_data

Method: GET

This endpoint is used for serial data submission. The columns associated with this endpoint include:

Field Name Data Type Required? Description
manufacturer_serial string (256) yes Serial number of the system (serial submitted to Forge)
serial_data_type_id int yes The ID of the data type
metadata string (256) no Metadata associated with the serial data
value string (256) yes The value of the serial data

WebHooks

Order Update

The status response parameter, used for the customer_order_submissions endpoint, will change depending on the status of the order. The possible statuses are:

Status Description
Pending Order is pending and is currently on hold
Released Order has been released from hold and will be processed shortly
Shipped Order has been shipped

The invoices and tracking_numbers response parameters will not show up until the order status is shipped.


Reports

Automation Tasks

/v2/automation_tasks/details.csv

Returns a CSV report of all automation tasks for your organization.

Field Name Description
id Automation task ID
automation_queue_id Automation queue ID
automation_task_type_id Automation task type ID
sequence Sequence of this task within the queue
started_at Time the task was started
completed_at Time the task was completed
failed True if the task was marked as failed
message Message submitted for the task
assignee_id Organization ID assigned to the task
assignee_name Organization name assigned to the task
work_order_id Work order assigned to the automation queue
serial_id Serial for the system assigned to the automation queue
item_id Item ID for the system
manufacturer_serial Serial number for the system