Introduction

The SnapFulfil Web API enables access to the following SnapFulfil entities:

• Attachments
• Closed Receipt Summary
• Closed Shipment Summary
• Customer Returns
• Customers
• Despatch Stock
• Kits
• Open Receipt Summary
• Open Shipments Summary
• Product Alternates
• Product Configuration
• Products
• Purchase Orders
• Receipt
• Replenishments
• Sales Orders
• Serial Movements Summary
• Serials Receipt
• Serials Shipment
• Shipment
• Shipment Status
• Shipment Dispatch
• Snap Inbound
• Snap Lookups
• Snap Outbound
• Special Condition Lines
• Special Conditions
• Stock Consignment
• Stock Detail
• Stock Movements
• STU
• STU Consignment
• Suppliers
• Tasks Receipt
• Tasks Shipment
• Tasks Summary

Documentation providing information on each entity, including URL schemes,
available HTTP operations and data models is provided as part of this
information pack.

The endpoints in this document have been grouped together for ease of reading.

Some of the example responses have been truncated for clarity. The full
data model is documented at the end of each endpoint.

This document is intended for developers familiar with HTTP and RESTful APIs and therefore experience with RESTful API’s is assumed.

Conventions used in this document

Endpoints are listed with an HTTP Method and a URL. Any text that is contained in double braces (e.g. {{receiptid}}) is a placeholder for your own values. The example calls are generated dynamically based on the language type selected at the top of the page. You can use the drop-down box to select your preferred language.

The document uses terminology that is commonplace within SnapFulfil (such as StU or StT). If you are unsure about any SnapFulfil terminology then please refer to the SnapFulfil Help Centre.

The SnapFulfil API is accessed using the following HTTP methods:

• GET Used for retrieving records from SnapFulfil
• POST Used for creating new records from SnapFulfil
• PUT Used for updating records from SnapFulfil
• DELETE Used for deleting records from SnapFulfil

Each endpoint details the methods available to it.

Authentication and Security

Your SnapFulfil Implementation Team will provide you with two URLs to access the
SnapFulfil API. One will provide access to a test environment, the other to your
live SnapFulfil environment.

Each call made to the SnapFulfil API is made via HTTPS, encrypting all data sent
to and received from the SnapFulfil servers using industry standard encryption.
Any attempt to access the API via HTTP will result in a HTTP 403 (Forbidden) error
message.

A unique user name and password must be presented with each call you make to the API using
Basic HTTP authentication. In addition to securing your access to your
SnapFulfil environment, your user account will also determine the language of
the SnapFulfil Lookup values returned as part of your data.

Content Negotiation

The SnapFulfil API supports JSON as a valid data format. When making GET calls, set the Accept and Content-Type HTTP header to application/json to request data to be returned in the appropriate format. If the server doesn’t recognise the format of your entity, it will return a HTTP 400 (Bad Request) error. Common errors include:

• Posting an array instead of an individual entity
• Malformed or invalid JSON/XML

OData System Query Options

For many of the endpoints that return a list of entities, the URL can accept one or more OData System Query Options as part of the query string. Supported OData System Query Options are:

• $top
• $skip
• $orderby
• $filter

Examples of OData System Query Options can be found in the individual endpoint sections.
Please see “Invalid Characters and URL Encoding” for details on encoding
System Query Options.

### Rate Limits

Each customer is limited to N calls per hour. If you exceed this limit, the SnapFulfil API will return an HTTP 429 (Too many requests) code and you should try your request again later. If you need to increase the SnapFulfil API hourly limit, please speak to your SnapFulfil Account Manager.

SnapFulfil Lookup codes

SnapFulfil validates certain values when they are interfaced into the system. This
means that the correct code must be sent for these values. The applicable values
are highlighted in the data models as ‘Snaplookup’ with the lookup code
afterwards.

Snaplookup [ORDTYPE]

In order to ascertain the correct codes, you can use the “Snap Lookups” endpoint,
passing the lookup code. This will return the possible values for that lookup
code.

Validation Error Reporting

When creating or updating entities, SnapFulfil will process the data according
to definitions configured in SnapFulfil.

If any of the fields fail validation, an array of error messages will be
returned to the API client. This will indicate the fields that failed, along
with an error code. If a human readable version of the error code is required,
you can use the MESSAGE Snaplookup code.

Updates from SnapFulfil

SnapFulfil can be configured to produce updates at pre-defined events (e.g.
Shipment is Despatched). To view these events, use the SnapOutbound endpoint.

Date Formats

The SnapFulfil API requires dates to be sent in the following format:

YYYY-MM-DDTHH24:MI:SS

e.g. 2012-10-01T19:32:49

Integers and Decimals.

Integers can be up to 18 characters in length.

Decimal values can be up to a total of 18 characters in length and up to 6
significant places.

Invalid Characters and URL Encoding

There are a number of characters that must be encoded in any URL sent to the SnapFulfil API. The below table, whilst not exhaustive, details some of the more common reserved characters and the corresponding ASCII value.

For some languages (such as CURL), URL-encoding must be used. Many REST clients (such as Insomnia or Postman) will take care of some URL encoding but not others. If in doubt, it is best to URL-encode all URLs.

For ease of reading, the examples in this document are not URL-encoded.

Set up a SnapFulfil User for Web API access

API users are configured within SnapFulfil and must be set up with appropriate access to the API Host and for the Business (Biz). If your operation uses multiple Biz’s or multiple Stock Owners then you will need to ensure the API user only has access to the appropriate Biz.

To create a new API user, open the User screen in SnapFulfil and create a New User as normal on the Detail screen.
On the Permissions tab, you will specify which Interface Host the user is assigned to (this should be the API Host, however it is possible for SnapFulfil to be configured with multiple API Hosts). It is on this screen that you will also specify which Biz or Biz’s the user has access to.

We recommend that different user accounts are created for API users, screen users and RF users.

Notes

• It is important to only select one interface organisation for the user.
• If your SnapFulfil system is setup with multiple hosts, you will need to
  create multiple API users.
• API users configured as above will not be able to log in to the SnapFulfil application or RF device.

Snap Web API - Testing the API using a REST Client

To test the various end-points available in the SnapFulfil API, you can use a
REST API client.

The SnapFulfil API has been tested using the Postman REST Client which is
available from https://www.getpostman.com/.

Notes on using Postman

• Make sure that you select Basic Auth in the Authorization tab and enter your API username and password.
• Headers can be set on the Headers tab.
• When testing POST or PUT operations, place your XML or JSON payload in the
  Body tab.
• The results of any operations will be returned in the Response pane.

Goods In

The Goods In endpoints are as follows:

• Attachments

• Receipts

• Customer Returns

• Purchase Orders

• Serials Receipts

• Stock Consignment

• StU Consignment

• Open Receipt Summary

• Closed Receipt Summary

Attachments

Please see “Products & Inventory | Attachments” for details on this endpoint.

Receipt

The Receipt endpoint allows the user to create, update, view and delete Receipt information within SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Receipt records

https://lintliveapi.snapfilfil.net/api/receipts

GET a specific Receipt record

https://lintliveapi.snapfilfil.net/api/receipts/{{receiptid}}

Example response: json{ "ReceiptId": "APIRECEIPT", "BizId": "BIZ1", "Stage": "00", ... "MaintInd": "W", "ReceiptLines": [ { "ReceiptId": "APIRECEIPT", "Line": "K43MPVYGQT", "Level": "00", ... "SpecialConditionInd": null, "Stage": "00" } ], "ReceiptAddresses": [] }

POST a new Receipt

https://lintliveapi.snapfilfil.net/api/receipts

PUT a Receipt record

https://lintliveapi.snapfilfil.net/api/receipts/{{receiptid}}

DELETE a Receipt record

https://lintliveapi.snapfilfil.net/api/receipts/{{receiptid}}

System Query Options

The GET operation for the receipt listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 10 Receipt records

https://lintliveapi.snapfilfil.net/api/receipts?$top=10

GET the top 10 Receipt records, ordered by SKU ID

https://lintliveapi.snapfilfil.net/api/receipts?$top=10&orderby=SKUId

GET Receipt records where the Receipt ID starts with “10000”

https://lintliveapi.snapfilfil.net/api/receipts?$filter=startswith(ReceiptId,'10000')

Data Model

Receipt Header Data Model

Receipt Line Data Model

Receipt Address Data Model

Customer Returns

The Customers endpoint allows the user to create, update, view and delete Customer Returns information.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Customer Return records

https://lintliveapi.snapfilfil.net/api/customerreturns

GET a specific Customer Returns record

https://lintliveapi.snapfilfil.net/api/customerreturns/{{returnid}}

POST a new Customer Return

https://lintliveapi.snapfilfil.net/api/customerreturns

PUT a Customer Return record

https://lintliveapi.snapfilfil.net/api/customerreturns/{{returnid}}

DELETE a Customer Return record

https://lintliveapi.snapfilfil.net/api/customerreturns/{{returnid}}

System Query Options

The GET operation for the receipt listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 10 Customer Return records

https://lintliveapi.snapfilfil.net/api/customerreturns?$top=10

GET the top 5 Customer Return records, ordered by OrderClass

{{Host}}/api/customerreturns?$top=5&orderby=OrderClass

GET Customer Returns records where the OrderClass value starts with “STD”

https://lintliveapi.snapfilfil.net/api/customerreturns?$filter=startswith(OrderClass,%20'STD')

Data Model

Customer Returns Header Data Model

Customer Returns Line Data Model

Customer Returns Address Data Model

Purchase Orders

The Purchase Orders endpoint allows the user to create, update, view and delete Purchase Orders within SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Purchase Order records

https://lintliveapi.snapfilfil.net/api/purchaseorders

GET a specific Purchase Order record

https://lintliveapi.snapfilfil.net/api/purchaseorders/{{purchaseorderid}}

POST a new Purchase Order record

https://lintliveapi.snapfilfil.net/api/purchaseorders

PUT a Purchase Order record

{{Host}}/api/purchaseorders/{{purchaseorderid}}

DELETE a Purchase Order record

https://lintliveapi.snapfilfil.net/api/purchaseorders/{{purchaseorderid}}

System Query Options

The GET operation for the Purchase Order listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 10 Purchase Order records

https://lintliveapi.snapfilfil.net/api/purchaseorders?$top=10

GET the top 10 Purchase Order records, ordered by OrderClass

https://lintliveapi.snapfilfil.net/api/purchaseorders?$top=10&orderby=OrderClass

GET Purchase Orders records starting with “TWL”

https://lintliveapi.snapfilfil.net/api/purchaseorders?$filter=startswith(PurchaseOrderId,%20’TWL’)

Data Model

Purchase Orders Header Data Model

Purchase Orders Line Data Model

Purchase Order Address Data Model

Serials Receipts

The Serials Receipts endpoint allows the user to create, update, view and delete Serials Receipts within SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Serials Receipts records

https://lintliveapi.snapfilfil.net/api/serialsreceipt

GET a specific Serials Receipts record

https://lintliveapi.snapfilfil.net/api/serialsreceipt/{{serialreceiptid}}

POST a new Serials Receipts record

https://lintliveapi.snapfilfil.net/api/serialsreceipt

PUT a Serials Receipt record

https://lintliveapi.snapfilfil.net/api/serialsreceipt/{{serialreceiptid}}

DELETE a Serials Receipt record

https://lintliveapi.snapfilfil.net/api/serialsreceipt/{{serialreceiptid}}

Data Model

Serials Receipt Data Model

Stock Consignment

Please see “Goods Out | Stock Consignment” for details on this endpoint.

StU Consignment

Please see “Goods Out | StU Consignment” for details on this endpoint.

Open Receipt Summary

The Open Receipt Summary endpoint is used to accessing information on Receipts that are open, providing a high-level view of Receipt information.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Open Receipts records

https://lintliveapi.snapfilfil.net/api/openreceiptssummary

GET a specific Open Receipt record

https://lintliveapi.snapfilfil.net/api/openreceiptssummary/{{receiptid}}

GET all Open Receipts by Site ID

https://lintliveapi.snapfilfil.net/api/openreceiptssummary/{{siteid}}

Example response: json{ "ReceiptId": "APIRECEIPT", "BizId": "BIZ1", "Stage": "00", ... "MaintInd": "W", "ReceiptLines": [ { "ReceiptId": "APIRECEIPT", "Line": "K43MPVYGQT", "Level": "00", ... "SpecialConditionInd": null, "Stage": "00" } ], "ReceiptAddresses": [] }

System Query Options

The GET operation for the Open Receipt listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET a summary of all Open Receipts, ordered by Count

https://lintliveapi.snapfilfil.net/api/openreceiptssummary?$orderby=Count

GET the top 5 Open Receipt summary records

https://lintliveapi.snapfilfil.net/api/openreceiptssummary?$top=5

Data Model

Open Receipt Summary Data Model

Closed Receipt Summary

The Closed Receipt Summary endpoint is used to access information on Receipts that are closed, providing a high-level view of Receipt information.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Closed Receipts

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary

GET a specific Closed Receipt

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary/{{receiptid}}

Example response: json{ "ReceiptId": "APIRECEIPT", "BizId": "BIZ1", "Stage": "00", ... "MaintInd": "W", "ReceiptLines": [ { "ReceiptId": "APIRECEIPT", "Line": "K43MPVYGQT", "Level": "00", ... "SpecialConditionInd": null, "Stage": "00" } ], "ReceiptAddresses": [] }

GET all closed Receipts by Site ID

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary/{{siteid}}

Example Response json{ "ReceiptId": "APIRECEIPT", "BizId": "BIZ1", "Stage": "00", ... "MaintInd": "W", "ReceiptLines": [ { "ReceiptId": "APIRECEIPT", "Line": "K43MPVYGQT", "Level": "00", ... "SpecialConditionInd": null, "Stage": "00" } ], "ReceiptAddresses": [] }

GET a summary of Closed Receipts from a specific site closed on a specific day

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary/{{siteid}}/{{date}}

System Query Options

The GET operation for the Closed Receipt listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET a summary of all Closed Receipts, ordered by Count

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary?$orderby=Count

GET the top 5 Closed Receipt summary records

https://lintliveapi.snapfilfil.net/api/closedreceiptssummary?$top=5

Data Model

Closed Receipt Summary Data Model

Goods Out

The Goods Out endpoints are as follows:

• Attachments
• Shipment
• Load
• Sales Order
• Special Conditions
• Special Condition Lines
• Serials Shipments
• Shipment Status
• Shipment Dispatch
• Open Shipments Summary
• Closed Shipments Summary
• Despatch Stock
• Stock Consignment
• StU Consignment

Attachments

Please see “Products & Inventory | Attachments” for details on this endpoint.

Shipment

The Shipment endpoint allows the user to create, update, view and delete Shipments within SnapFulfil. It is important that the Shipment information is confirmed where possible before it is submitted. Once a Shipment has passed stage Due Out (stage 00), certain data (such as Shipment Line data) cannot be amended without cancelling the Shipment and resubmitting it under a new ID. SnapFulfil does permit Shipment Header fields to be amended after a Shipment has passed stage Due Out. Common uses of this functionality are:

• Updating the carrier tracking number outside of an integrated service.
• Updating the customer reference fields.
• Updating the status (for example: Cancelled, Credit Hold, Suspend).

To update the Shipment Header data, a PUT should be used. For a full list of editable fields after Due Out, please refer to the Shipment Header Data Model.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Shipments

https://lintliveapi.snapfilfil.net/api/shipments

GET a specific Shipment record

https://lintliveapi.snapfilfil.net/api/shipments/{{shipmentid}}

Example response:

{
    "ShipmentId": "APISHIPMENT",
    "BizId": "BIZ1",
    "Stage": "90",
    ...
    "MaintInd": "H",
    "ShipmentLines": [
        {
            "ShipmentId": "APISHIPMENT",
            "Line": "JHTM3MC990",
            "Level": "00",
            ...
            "SpecialConditionInd": "0",
            "Stage": "90"
        }      
    ],
    "ShipAddress": [
        {
            "Table": "SHH",
            "ShipmentId": "APISHIPMENT",
            "AddressId": "HOME",
            ...
            "Longitude": 0.000000
        }
    ],
    "ShipContacts": [
        {
            "Table": "SHH",
            "ShipmentId": "APISHIPMENT",
            "LineId": "1",
            ...
            "Language": null
        }
    ],
    "ShipmentDespatch": [
        {
            "ShipmentId": "APISHIPMENT",
            "Type": "OS",
            "Stu": "STU1",
            ...
            "ManifestInd": null
        }
    ]
}

POST a new Shipment record

https://lintliveapi.snapfilfil.net/api/shipments

PUT a Shipment record

https://lintliveapi.snapfilfil.net/api/shipments/{{shipmentid}}

DELETE a Shipment record

https://lintliveapi.snapfilfil.net/api/shipments/{{shipmentid}}

System Query Options

The GET operation for the Shipment listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 5 Shipment records

https://lintliveapi.snapfilfil.net/api/shipments?$top=5

GET the top 5 Shipment records, ordered by SKUId

https://lintliveapi.snapfilfil.net/api/shipments?$top=5&orderby=SKUId

GET Shipments starting with “10000”

https://lintliveapi.snapfilfil.net/api/shipments?$filter=startswith(ShipmentId,%20'10000')

Data Model

Shipment Header Data Model

Shipment Line Data Model

Shipment Address Data Model

Shipment Contact Data Model

Shipment Despatch Data Model

Load

The Load endpoint allows the user to create, update, view and delete Load information within SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Load records

https://lintliveapi.snapfilfil.net/api/load

GET a specific Load record

https://lintliveapi.snapfilfil.net/api/load/{{loadid}}

Example response:

{
    "Type": "OL",
    "Site": "0001",
    "LoadID": "120-SM-SM-SM-5",
    "Status": "00",
    "ShipMethod": "TEST",
    "Route": "TEST",
    "Details": "SMM API TEST",
    "WHS": "AASITE0001",
    ...
}

POST a new Load record

https://lintliveapi.snapfilfil.net/api/load

PUT a Load record

https://lintliveapi.snapfilfil.net/api/load/{{loadid}}

DELETE a Load record

https://lintliveapi.snapfilfil.net/api/load/{{loadid}}

System Query Options

The GET operation for the receipt listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 5 Load records

https://lintliveapi.snapfilfil.net/api/load?$top=5

GET the top 5 Load records, ordered by LoadID

https://lintliveapi.snapfilfil.net/api/load?$top=5&orderby=LoadID

GET Loads where the LoadID starts with “12”

https://lintliveapi.snapfilfil.net/api/load?$filter=startswith(LoadID,'12')

Data Model

Vehicle Load Data Model

Sales Orders

The Sales Orders endpoint allows the user to create, update, view and delete Sales Orders within SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Sales Orders

https://lintliveapi.snapfilfil.net/api/salesorders

GET a specific Sales Order record

https://lintliveapi.snapfilfil.net/api/salesorders/{{salesorderid}}

Example response:

{
    "OrderId": "APISALESORDER",
    "BizId": "BIZ1",
    ...
    "MaintInd": "W",
    "SOLines": [
        {
            "OrderId": "APISALESORDER",
            "Line": "K5U1UDD3PW",
            "Level": "00",
            ...
            "Stage": "10"
        }
    ],
    "Addresses": [
        {
            "OrderId": "APISALESORDER",
            "Table": "SOH",
            "AddressId": "ADD1",
            ...
            "Longitude": 0.000000
        }
    ]
}

POST a new Sales Order record

https://lintliveapi.snapfilfil.net/api/salesorders

PUT a Sales Order record

https://lintliveapi.snapfilfil.net/api/salesorders/{{salesordersid}}

DELETE a Sales Order record

https://lintliveapi.snapfilfil.net/api/salesorders/{{salesorderid}}

System Query Options

The GET operation for the Sales Order listing supports the following OData System Query Options:

• $top
• $skip
• $filter
• $orderby

GET the top 5 Sales Order records

https://lintliveapi.snapfilfil.net/api/SalesOrders?$top=5

GET the top 5 Sales Order records, ordered by OrderId

https://lintliveapi.snapfilfil.net/api/SalesOrders?$top=5&orderby=OrderId

GET all Sales Orders records ending with “6”

https://lintliveapi.snapfilfil.net/api/SalesOrders?$filter=endswith(OrderId,'6')

Data Model

Sales Order Header Data Model

Sales Order Line Data Model

Sales Order Address Data Model

Sales Order Contact Data Model

Sales Order Despatch Data Model

Special Conditions

The Special Conditions endpoint allows the user to create, update, view and delete Special Conditions within SnapFulfil. Please also refer to “Special Condition Lines”.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET all Special Conditions for a specific Shipment

https://lintliveapi.snapfilfil.net/api/specialconditions/{{shipmentid}}/{{table}}

Example response

[
    {
        "Table": "SHH",
        "ShipmentId": "APISHIPMENT",
        ...
        "Code": "OWNER",
        "Logic": "=",
        "Value": "SNAPFULFIL"
    }
]

GET a specific Special Condition for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditions/{{shipmentid}}/{{table}}/{{key}}/{{keyline}}/{{line}}

POST a new Special Condition

https://lintliveapi.snapfilfil.net/api/specialconditions

PUT a specific Special Condition for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditions/{{shipmentid}}/{{table}}/{{key}}/{{keyline}}/{{line}}

DELETE a specific Special Condition for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditions/{{shipmentid}}/{{table}}/{{key}}/{{keyline}}/{{line}}

Data Model

Special Conditions Data Model

Special Condition Lines

The Special Condition Lines endpoint allows the user to create, update, view and delete Special Condition Lines within SnapFulfil. Please also refer to “Special Conditions”.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values

Usage

GET a specific Special Condition Line for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditionlines/{{shipmentid}}

POST a new Special Condition Line for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditionlines/{{shipmentid}}

PUT a Special Condition Line for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditionlines/{{table}}/{{shipmentid}}/{{shipmentlineid}}/{{generatedlineid}}

DELETE a Special Condition Line for a Shipment

https://lintliveapi.snapfilfil.net/api/specialconditionlines/{{table}}/{{shipmentid}}/{{shipmentlineid}}/{{generatedlineid}}

Data Model

Special Condition Line Data Model

Serials Shipments

The Serials Shipment endpoint allows the user to view Shipments containing serialised stock from SnapFulfil.

Supported Methods

GET
POST
PUT
DELETE

Expected Return Values