Getting Started

If you've just installed the SalesPad Web API, head over to the Database Update page and perform the database update.
Next, you may update your licenses as needed in the Licenses page.
After this, you are ready to begin using the API! Continue reading below to learn about authentication and more.

---

Request Headers

SalesPad API requires an Authorization or a Session-ID header for each request.

To begin using the SalesPad API, make a request to GET /api/Session/Permanent with SalesPad credentials in the Authorization header as specified in the example below. A successful response will contain a Session GUID (Globally Unique Identifier).
For ALL subsequent requests, this Session GUID must be included in a Session-ID header.

If desired, you may also use GET /api/Session to create a session. Based on user group, these sessions will either consume a desktop seat or an external API seat, and will expire in 15 minutes of inactivity.

Example Headers:

Authorization: Basic dXNlcjpwYXNz	SalesPad API uses Basic Authentication to obtain a Session ID. The SalesPad username and password should be in the format of username:password (using a colon as the delimiter), prefixed with the keyword Basic and encoded in Base64. This value is then sent to one of the above Session endpoints using the Authorization header.
Session-ID: EDFBCDBC-8324-42EE-8EAE-23A8FE657CCE	SalesPad API requires a Session ID for every API call (with the exception of GET /api/Session and GET /api/Session/Permanent, which will provide the Session ID).

---

CORS

By default, CORS (Cross-Origin Resource Sharing) is enabled for all domains ( denoted by * ). If you wish to restrict this, please change the following value in web.config:

<configuration>
  <system.webserver>
    <httpprotocol>
      <customheaders>
        <add name="Access-Control-Allow-Methods" value="POST, GET, PUT, DELETE, OPTIONS" />
        <add name="Access-Control-Allow-Headers" value="Content-Type, Authorization, Session-ID, Context-ID" />
        <add name="Access-Control-Allow-Origin" value="*" />
      </customheaders>
    </httpprotocol>
  </system.webserver>
</configuration>

For example, to only allow CORS requests from localhost:9000, you should change the bolded line to:
  <add name="Access-Control-Allow-Origin" value="localhost:9000" />

---

OData

Most SalesPad API GET requests are OData enabled, which means you can make use of a select set of Query Options to filter results returned by the API.
SalesPad WebAPI uses System.Web.Http.Odata ODataQueryOptions which currently only supports $filter, $orderby, $top, $skip, and $inlinecount.
See OData's Documentation for further information on how to use Query Options.

For example, to retrieve Customers with a Credit Limit greater than $30,000 with Payment Term of 'CREDIT CARD', ordered by Customer Name in descending order, you should use the following query:
  GET api/Customer?$filter=Customer_Credit_Limit gt 30000 and Payment_Terms eq 'CREDIT CARD' &$orderby=Customer_Name desc

Or, to retrieve Sales Documents for Customers who's name starts with 'R', retrieving the second through fifth documents returned when ordered by Zip Code, you should use the following query:
  GET api/SalesDocument?$filter=startswith(Customer_Name,'R') &$orderby=Zip &$skip=1 &$top=4

---

Batch Requests

Batch request endpoints are available at api/batch and api/sequentialBatch. Like their names suggest, api/sequentialBatch executes the requests in sequential order, meaning the second request in the batch won't start until the first one is completed. If order of execution is not important, use api/batch to execute the requests asynchronously.
To send a batch request, the individual requests are bundled into the request content in MIME multipart format. The Content-Type is specified as multipart/mixed, with a boundary value which marks the beginning of each request and allows the server to unwrap the batch request into separate requests.
Please note that each part of the batch request is run separately; thus, the Session-ID header is required for each individual request.
The following sample batch request will execute two GET requests in sequential order:

• GET /api/currency?$filter=Currency_ID eq 'Z-US$' - OData request for 'Z-US$' currency information
• GET /api/countrycode/US - A request for 'US' country code information

POST http://localhost:5501/api/sequentialBatch HTTP/1.1
Session-ID: fb973191-d7f1-466e-84a0-235250f7bc63
Content-Type: multipart/mixed; boundary="99729b72-30c0-402e-be99-4ba6c14a56d7"
Host: localhost:5501
Content-Length: 553
Expect: 100-continue
Connection: Keep-Alive

--99729b72-30c0-402e-be99-4ba6c14a56d7
Content-Type: application/http; msgtype=request

GET /api/currency?$filter=Currency_ID%20eq%20'Z-US$' HTTP/1.1
Host: localhost:5501
Session-ID: fb973191-d7f1-466e-84a0-235250f7bc63

--99729b72-30c0-402e-be99-4ba6c14a56d7
Content-Type: application/http; msgtype=request

GET /api/countrycode/US HTTP/1.1
Host: localhost:5501
Session-ID: fb973191-d7f1-466e-84a0-235250f7bc63

--99729b72-30c0-402e-be99-4ba6c14a56d7--