SalesSystemCRM API v1
Connect your website to SalesSystemCRM
Here's all the technical information for integration with SalesSystemCRM.
General Information
The SalesSystemCRM API is a way to integrate your website with SalesSystemCRM. It's powerful enough for you to build an entire ecommerce website with a shopping basket and payment processing through SagePay.
Benefits
If you develop your website into SalesSystemCRM you will have your website orders and customer details arriving directly into SalesSystemCRM instantly ready for dispatchment. But if that wasn't enough, are many other other excellent advantages:
- It's free for existing customers!
- Easier to add ecommerce to your website.
- Your customers can login on your own website.
- Follow up on unfulfilled orders from your websites checkout.
- Manage your inventory on your website, upload images and change product information, switch them on / off.
- Operate price bands for different customers, i.e. trade / retail customers.
- Create a callbacks at a specific times for your customers.
- Receive support requests from your website.
- Manage newsletter subscriptions.
- Process website orders into different sales teams.
- Manage tax free customer in different continents.
- Flexible and powerful enough to build a single page checkout.
The Basics
Our API will give you the tools to build a bespoke shopping basket and integrate many features into your website with SalesSystemCRM. You can connect to our API over HTTP POST and HTTP GET and the data is returned is JSON. This gives you (and us) an extremely lightweight method to communicate betweeen our servers. Click here for information on JSONP
Sessions
The SalesSystemCRM API optionally provides entire session management for your website customers keeping tracking of who they are. If you decide to use our session features then when your customers visit your website and start shopping, they're actually shopping with us. All your website needs to do is remember who they are! We'll get into that in the Getting Started section above.
Security
We recommend that you communicate with the SalesSystemCRM API using our SSL socket with a minimum of 128bit encryption to protect the data between your website and SalesSystemCRM.
Keep in touch
We are interested in your feedback. Please do contact us if you have any technical issues, feature requests or have found something missing from the documentation.
Not a developer?
Ok so you like the look, but haven't a clue how to do all this! Well please get in touch and we can assist in getting your website setup.
Getting Started
To get your integration up and running, you'll need to take your favourite programming language and use some of it's features for communicating with the SalesSystemCRM API. Whether you're a PHP, ASP, Perl, Ruby on Rails or other developer this is all possible.
- PHP - contains the decode_json tag
- .NET Framework 3.5 - has the JavaScriptSerializer class
- .NET Framework 4+ - has the DataContractJsonSerializer class
- Perl - contains a decode_json tag
- Lasso - contains the decode_json tag
- ...most other languages have support.
Best methods
We recommend that you use HTTP POST requests to the SalesSystemCRM API and then use some deserialisation techniques to parse the response. If possible we highly recommend that you cache requests that you frequently use - this will only speed up your website for your customers which has to be a good thing!
Making a Request
The End Point for Version 1 of our API is:
The following is required for every API request and must be sent via HTTP GET or HTTP POST:
Your API Key is a string that is configured in SalesSystemCRM Setup
Here you are specifying that that you are requesting an output of JSONP. Your API Key is a string that is setup and configured in the SalesSystemCRM Setup menu.
We recommend that you keep your API key secure and not public facing.
Examples
A simple add contact form on your website
You've a form on your website where your customer adds their details to create an account, essentially adding them to SalesSystemCRM, so you'll know who they are when they return and login. For this you'll need to make a request to add the their contact details and create the account when you validate your form and the sumbit button is clicked. So we'll make a HTTP GET request to the SalesSystemCRM API (you can use HTTP POST to send the form fields if preferred) using the addContact method:
Now the SalesSystemCRM API will respond. Here's a successful response:
That's all good, as we can see that there's no "error_code" supplied. Note the "session_id" - you will use to track your customer when using SalesSystemCRM API.
Let's have a look at a failed request. For example the {customers_super_strong_password} was not so strong after all and they completely forgot to enter it!
Ok, now we have an "error_code" and a map of all invalid errors contained in "error_invalid" - so the method has failed. We still have a "session_id" returned, as it's worth tracking the customer regardless, however the "error_code" is reason enough to request the "client_password" from your form again.
Let's recap on what effect we have had:
- We successfully added a Contact.
- We have been returned a "session_id", so we have an active session.
- As they're a new customer they are now logged in to the API.
That now gives us much more flexibilty!
Returning a customer details
Well we've added a customer, but now we need to fetch his details. Let's look at a quick request using the getContact method:
Easily done, we provide the "session_id" and the SalesSystemCRM API knows who the customer is and fetches his details. We have filtered the request to return only his first, last and company names, along with his email address and whether he is subscribed to your newsletters.
Let's look at the response.
All looks good and by using the "filter" parameters in our request we have returned the correct fields that we requested.
But let's have a look at the response if we run the same getContact method and the customer wasn't logged in!
So we have an "error_code" and a "error_message" letting us know that the customer is not logged in.
Updating a customers details
Let's update the customers details, by supplying a new email address using the updateContact method.
And a successful response:
Logging out the Customer
Finally we will log out the customer.
And we get a successful response with no error:
Please take a look at the API Documentation for further information on these methods.
Documentation
The following documentation outlines the methods that can be used with the SalesSystemCRM API as current of Version 1. Please start by reading the Getting Started section for some examples of how to put these methods into a practice.
Show all Methods | Collapse all Methods
addActivity ( )
Description
Adds an activity to SalesSystemCRM. The customer must be logged into the API to be able to add Activities so correctly associated. It is advisable to add Activities within working hours.
Parameters
session_id (required) string = Current session for the customer on the server
activity_subject (required) string = A subject for the activity.
activity_start (required) date = Activity Start Date (YYYY-MM-DDThh:mm:ss)
activity_end (required) date = Activity End Date (YYYY-MM-DDThh:mm:ss)
activity_type (optional) string = An Asset (defaults to 'DA1' - Call)
activity_team (optional) string = Code for a Staff Team (Defaults to 'TM1' the first team within SalesSystemCRM)
activity_location (optional) string = A description of the location of the activity
activity_notes (optional) string = Notes on the activity
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
activity_ref (optional) integer = The client key returned if request is successful
activity_key (optional) 18 char string = The client key returned if request is successful
Example HTTP GET Request
Request to add an activity to call a customer between 13:00:00 and 13:15:00 on 01/01/2010. The time is formatted in UTC, please see the getDateTime method.
Example JSON Response
The return of the 'activity_ref' (i.e. 100 in this case) can be used to supply the customer with a reference to the activity.
addCase ( )
Description
Adds a Case to SalesSystemCRM. If the customer is logged into the API then the Case will be associated with the Contact, otherwise the addContactLite will be called first (Please see addContactLite in the documentation).
Parameters
session_id (optional) string = Current session for the customer on the server
case_subject (required) string = A subject for the Case.
case_message (required) date = A message for the Case.
email_template (optional) integer = Document ID to use an html email template in response to the customer.
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
case_ref (optional) integer = The client key returned if request is successful
case_key (optional) 18 char string = The client key returned if request is successful
Example HTTP GET Request
Request to add a case for a customer. In the first example the customer was logged in, so there was no requirement to send over any customer details and a case would be added in reference to the existing customer. In the second example the customer was not logged in, so customer data has been passed with the case data so the SalesSystemCRM API calls the addContact method prior to the case being added.
Example JSON Response
The return of the 'case_ref' (i.e. 150 in this case) can be used to supply the customer with a reference to the case.
addContact ( )
Description
Takes Customer data from a visitor to your website and adds a Contact to SalesSystemCRM. Customer data passed to the SalesSystemCRM API will always be prefixed with {client_}, whilst customer data returned will always be prefixed with {contact_}. If the request is successful the session_id holds a reference to the Contact for all future requests and the Contact will be treated as logged into the API, until the clientLogout or sessionEnd method is called or furthermore the session expires.
Parameters
client_firstname (required) string = The First Name of the Contact.
client_lastname (required) string = The First Name of the Contact.
client_company (optional) string = The Company Name for the Contact.
client_email (required) string = Work Email Address
client_email2 (required) string = Secondary Work Email Address
client_emailhome (optional) string = Home Email Address
client_emailhome2 (optional) string = Secondary Home Email Address
client_emailbilling (optional) string = Billing Email Address
client_password (required) string = A password for the client (min 6 chars, [A-Z|0-9])
client_title (optional) string = Mr, Mrs,
client_address1 (optional) string = First Line of Contact Billing Addresses
client_address2 (optional) string = Second Line of Contact Billing Addresses
client_address3 (optional) string = Third Line of Contact Billing Addresses
client_state (optional) string = Used for US States in Contact Billing Addresses
client_postcode (optional) string = Postcode of Contact Billing Addresses
client_country (optional) string = ISO 3166-1 2-letter country codes
client_phone (optional) string = Contact phone number
client_mobile (optional) string = Contact mobile number
client_fax (optional) string = Contact fax number
client_type (optional) string = Asset (defaults to SalesSystemCRM default Contact Type)
client_found (optional) string = Asset (defaults to SalesSystemCRM default Contact Found)
client_url (optional) string = Contact website address (only if valid url)
client_url2 (optional) string = Secondary website address (only if valid url)
client_newsletter (optional) string = (Y/N) as Yes or No (defaults to N if unspecified)
client_dataprotect (optional) string = Whether the Contact data can be sold. (Y/N) as Yes or No (defaults to N if unspecified)
client_taxable (optional) string = (Y/N/R) as Yes, No, Domestic Reverse Charge (defaults to Y if unspecified)
client_team (optional) string = Code for the Staff Team (Defaults to 'TM1' the first team within SalesSystemCRM)
client_currency (optional) string = ISO 4217 3-letter Currency Codes (defaults to the system default currency)
client_label (optional) string = Asset (defaults to none - Black)
client_dob (optional) date = Contacts Date of Birth (YYYY-MM-DD)
client_terms (optional) date = Date agreed to Terms and Conditions (YYYY-MM-DD)
client_timezone (optional) string = Contacts Timezone
client_agentname (optional) string = Name of agent
client_assistantname (optional) string = Name of Assistant
client_recommendedby (optional) string = Contact Recommended By
client_employeeno (optional) integer = No of employees
client_companyturnover (optional) integer = Company Turnover
client_jobposition (optional) string = Job Position
client_distributor (optional) string = Contacts Distrubutor
client_aim (optional) string = Contacts AOL Instant Messenger Account
client_jabber (optional) string = Contacts Jabber Messenger Account
client_skypename (optional) string = Contacts Skype Username
client_msn (optional) string = Contacts MSN Messenger Account
client_google (optional) string = Contacts Chat Account
client_yahoo (optional) string = Contacts YahooChat Account
client_gender (optional) string = Contacts gender (male|female)
client_blog (optional) string = Contacts blog feed
client_twitter (optional) string = Contacts Twitter Account
client_facebookuser (optional) string = Contacts Facebook User Account
client_facebookpage (optional) string = Contacts Facebook Page
client_facebookgroup (optional) string = Contacts Facebook Group
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
session_id (required) string = Current session for the customer on the server
contact_key (optional) string = The unique client key returned if request is successful
Example HTTP GET Request
Request to add a Contact in SalesSystemCRM supplying a first, last and company name, two email addresses, a billing address, phone, fax and mobile numbers, a website address and with newsletter subscriptions enabled.
Example JSON Response
A successful response contains the 'contact_ref' which is the unique customer number within SalesSystemCRM (i.e. 12345 in this case).
addOrder ( )
Description
Adds a sales order to SalesSystemCRM. The method will fail unless the client is logged in and has items in their basket. Optionally credit card details can be supplied for online payment processing through SagePay. Various SalesSystemCRM system settings available in the Setup menu are used to control payments through the API. If a payment fails or payment processing is disabled, the addOrder method will add a quote to SalesSystemCRM so it may be followed by sales staff.
Parameters
session_id (optional) string = Current session for the customer on the server
order_address1 (optional) string = First Line of Order Delivery Address
order_address2 (optional) string = Second Line of Order Delivery Address
order_address3 (optional) string = Third Line of Order Delivery Address
order_state (optional) string = Used for US States in Order Delivery Address
order_postcode (optional) string = Postcode of Order Delivery Address
order_country (optional) string = ISO 3166-1 2-letter country codes
order_notes (optional) string = Notes specific to the order (appears on Quotes and Invoices)
order_deliverynotes (optional) string = Notes specific to the delivery of the order (appears on Packing Lists).
order_label (optional) string = Asset (defaults to none - Black).
order_team (optional) string = The team for the order
order_datetime (optional) date = Creation date of the order (YYYY-MM-DD 00:00:00)
order_delivery_date (optional) date = Delivery date of the order (YYYY-MM-DD)
order_clientref (optional) string = The customers order reference
remit_payment (optional) boolean = Bypass payment for systems that are set to accept payments.
email_template (optional) integer = Document ID to use an html email template in response to the customer.
card_holdername (optional) string = Name (as seen on Card).
card_number (optional) string = Customer Card Number.
card_start_month (optional) string = Card Start Month (2 digit).
card_start_year (optional) string = Card Start Year (2 digit).
card_expire_month (optional) string = Card Expiry Month (2 digit).
card_expire_year (optional) string = Card Expiry Year (2 digit).
card_issuenumber (optional) string = Card Issue Number.
card_type (optional) string = Menu of Card Types for Sage Pay and other payment processing services.
card_cv2 (optional) string = CV2 Code.
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
order_ref (required) string = An order number provided after a successful response
order_key (required) string = An order key provided after a successful response
order_subtotal (optional) decimal = The NET order total
order_tax (optional) decimal = The TAX order total
order_total (optional) decimal = The GROSS order total
Example HTTP GET Request
The two example requests above work differently depending on settings within SalesSystemCRM setup. Example A has no request for payment, so a Quote will be added to SalesSystemCRM. Example B requests payment, so authorization will be requested through SagePay for the customers credit card and amount and if successful an order added and set to Deliver. If Example B fails the process falls back and adds a Quote as in Example A. The API knows the customers shopping basket from the 'session_id' provided within the request, so most parameters are optional when using this method. (Please note SagePay requires delivery addresses then authorizing payments).
Example JSON Response
The successful response contains the 'order_ref' as the order number that can be provided to the customer. We would encourage you to either call the endCartSession method when you have a successful response, so the customer has an empty shopping basket, or to call the endSession method to logout the customer and empty the basket.
addToCart ( )
Description
Adds a product to the customers shopping basket. The method will setup an empty basket for the user if no session information is provided.
Parameters
session_id (optional) string = Current session for the customer on the server
sku (required) string = The product code.
uom (optional) string = The uom (i.e. unit - default, pack, case, layer, pallet and container)
quantity (required) string = The quantity of product.
unitprice (optional) decimal = A custom NET unit price.
unittaxrate (optional) decimal = A custom tax rate (i.e. 0.175 for 17.5 percent tax)
location (optional) string = The stock location of the product.
noedit (optional) boolean = Flags the product as a fixed line item.
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
session_id (required) string = Current session for the customer on the server
Example HTTP GET Request
Both of these requests will add 24 x PRODUCTCODE to the customers shopping basket and returns a 'session_id'. Example A uses pricing data from within SalesSystemCRM and is the recommend method. Example B adds PRODUCTCODE with a defined unit price and tax rate, so will not work with price bands. Example B is ideal for integrating a third party solution to add orders to your system.
Example JSON Response
A successful response will contain the 'session_id' which will match the input parameter if provided.
addTransaction ( )
Description
Adds a payment for a Sales Order to SalesSystemCRM. The method will fail unless the client is logged in and is related to the Order for which you intend to record payment. Optionally the gateway can be selected and credit card details supplied for online payment processing through SagePay. Various SalesSystemCRM system settings available in the Setup menu are used to control payments through the API.
Parameters
session_id (optional) string = Current session for the customer on the server
order_key (optional) string = The key for a Sales Order
transaction_amount (required) decimal = Payment amount
transaction_method (required) string = Payment method options:
- Gateway: processes through Payment Service Provider (e.g SagePay)
- Cash: records a cash payment
- Cheque: records a cheque payment
- Chip-Pin: records a chip 'npin transaction taken on a PDQ by Staff
- Credit-Card: records a credit card payment
- Debit-Card: records a debit card payment
- Direct-Credit: records a direct credit payment
- EFTPOS: records a EFTPOS or BACS payment
- Money-Order: records a money order deposit
- PayPal: records a Paypal payment (processes by third party)
transaction_date (optional) string = The date of the Transaction.
transaction_fxrate (optional) decimal = FX Rate for the transaction (only for FX Orders)
email_template (optional) integer = Document ID to use an html email template in response to the customer.
card_holdername (optional) string = Name (as seen on Card).
card_number (optional) string = Customer Card Number.
card_start_month (optional) string = Card Start Month (2 digit).
card_start_year (optional) string = Card Start Year (2 digit).
card_expire_month (optional) string = Card Expiry Month (2 digit).
card_expire_year (optional) string = Card Expiry Year (2 digit).
card_issuenumber (optional) string = Card Issue Number.
card_type (optional) string = Menu of Card Types for Sage Pay and other payment processing services.
card_cv2 (optional) string = CV2 Code.
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
transaction_key (required) string = An transaction number provided after a successful response
Example HTTP GET Request
The two example requests above work differently depending on settings within SalesSystemCRM setup. Example A has no request for payment, so a Quote will be added to SalesSystemCRM. Example B requests payment, so authorization will be requested through SagePay for the customers credit card and amount and if successful an order added and set to Deliver. If Example B fails the process falls back and adds a Quote as in Example A. The API knows the customers shopping basket from the 'session_id' provided within the request, so most parameters are optional when using this method. (Please note SagePay requires delivery addresses then authorizing payments).
Example JSON Response
The successful response contains the 'transaction_ref' and the 'order_ref' which can be provided to the customer.
clientLogin ( )
Description
Logs the customer into SalesSystemCRM with their email address and password. Reprices the customers shopping basket for their price band within SalesSystemCRM.
Parameters
session_id (optional) string = Current session for the customer on the server
client_username (optional) string = Username of the Contact
client_password (optional) string = Password for the Contact (min 6 chars, [A-Z|0-9])
filter (optional) array = Items that you wish in your response
- contact_ref (optional) string = The Contact id / number
- contact_firstname (optional) string = The First Name of the Contact
- contact_lastname (optional) string = The Last Name of the Contact
Returns
session_id (required) string = Current session for the customer on the server
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
contact_ref (optional) string = The Contact id / number
contact_firstname (optional) string = The First Name of the Contact
contact_lastname (optional) string = The Last Name of the Contact
Example HTTP GET Request
This request provides the customers username and password and request some details to be returned by the 'filter' parameter.
Example JSON Response
A successful response will contain a 'session_id' which should be used to keep track of the customer whilst they are logged in (you might have already had one, in which case the response should match the parameter used). Furthermore the 'contact_ref' displays the Contact id / number (i.e. 123 in this case) from within SalesSystemCRM and there is some additional contact information that has been requested through the 'filter' parameter.
clientLogout ( )
Description
Logs out the customer from the SalesSystemCRM API
Parameters
session_id (required) string = The customers current session on the server
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
Example HTTP GET Request
Requires the 'session_id' in order to logout the customer.
Example JSON Response
Successfully logs out the customer but still returns the 'session_id' as the customer may still have items in their basket.
clientResetPassword ( )
Description
Resets the customers password for access on your website.
Parameters
session_id (optional) string = Current session for the customer on the server
client_username (required) string = The username of the Contact.
Returns
error_code (required) integer = The error code (null if no error)
error_message (optional) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
session_id (required) string = Current session for the customer on the server
contact_ref (required) integer = The customer number
contact_key (required) string = The unique client key returned if request is successful
Example HTTP GET Request
Let the SalesSystemCRM API know the 'client_username' and it will reset the password and send the customer an email with new login details. Optionally a 'session_id' can be passed in to keep the active session alive. If the customer is already logged in then the API will return error_code 1503, as the method is to be used when a password is unknown. The updateContact method can be called when a customer is logged in to the API to update a password to a user specific value.
Example JSON Response
A successful response will also contain the customer number as the 'contact_ref' (i.e. 12345 in this case).
deleteFromCart ( )
Description
Deletes a product from the shopping basket when provided a reference to the line item. The getCart method returns references to line items that can be used with this method. We recommend that you recall the getCart method afterwards to return a refreshed shopping basket.
Parameters
ref (required) string = A line item reference code (usually returned from the getCart method)
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = The customers current session on the server
Example HTTP GET Request
Requires the 'session_id' for reference to the customers shopping basket and a 'ref' to a line item contained within the customers shopping basket (i.e. 1234567890 in this case).
Example JSON Response
Successfully removes the line item from the basket and returns the 'session_id'.
deleteProductFromCart ( )
Description
Deletes a product from the shopping basket when provided a product code. We recommend that you recall the getCart method afterwards to return a refreshed shopping basket.
Parameters
sku (required) string = A product code
session_id (required) string = The customers current session on the server
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = The customers current session on the server
Example HTTP GET Request
Requires the 'session_id' for reference to the customers shopping basket and a 'sku' as a product code contained in the customers basket (i.e. PRODUCTCODE in this case).
Example JSON Response
Successfully removes the product from the basket and returns the 'session_id'.
endCartSession ( )
Description
Empties the current shopping basket. This method will keep the client logged in, but remove the shopping basket.
Parameters
session_id (required) string = The customers current session on the server
Returns
session_id (required) string = A string to use as a unique session id for the customer
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
Example HTTP GET Request
Requires the 'session_id' for reference to the customers shopping basket.
Example JSON Response
Successfully removes the shopping basket and returns the 'session_id'.
endSession ( )
Description
Ends the current session with the SalesSystemCRM API, which in turn will logout the client.
Parameters
session_id (required) string = The customers current session on the server
Returns
session_id (required) string = A string to use as a unique session id for the customer
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
Example HTTP GET Request
Only the 'session_id' required.
Example JSON Response
Removes the current session and returns no 'session_id'.
getActivities ( )
Description
Returns activities from SalesSystemCRM, when provided a start and end date
Parameters
activity_type (optional) string = Code for a category as specified in SalesSystemCRM.
activity_start (required) date = Start date.
activity_end (required) date = End date.
skip (optional) integer = Current skip records value
limit (optional) integer = Amount of records to return
filter (optional) array - Specified content to return.
- ref (optional) string = Activity reference
- subject (optional) string = Activity subject
- start (optional) string = End Date
- end (optional) string = Start Date
- description (optional) string = The activity description
- notes (optional) string = The activity notes
- category (optional) string = The activity category code
- type (optional) string = The activity type code
- sku (optional) string = The product code relating to the activity
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
Example HTTP GET Request
Requests activities which are Events on SalesSystemCRM using the Events code 'DD1'. We are requesting the first 10 results, but only one has been found.
Example JSON Response
Returns events as defined in the request.
getAsset ( )
Description
Requests a menu from SalesSystemCRM. An asset is a customisable menu of options used and maintained from within SalesSystemCRM. Retrieving assets can be useful if you need to display menus from SalesSystemCRM on a website. The codes for items within assets can also be found within SalesSystemCRM when editing menus.
Parameters
asset_name (required) string = The reference name to the SalesSystemCRM asset.
- contact_title = A list of contact titles (e.g. Mr., Mrs., Miss, etc.)
- contact_found = A list of contact found methods
- contact_type = A list of contact types
- activity_type = A list of activity types
- activity_label = A list of current Activities legend / labels
- order_label = A list of current Order legend / labels
- contact_label = A list of current Contact legend / labels
- cases_label = A list of current Cases legend / labels
- sales_team = A list of current sales teams
- price_bands = A list of all active price bands
- stock_location = A list of all active stock locations
- product_uom = A list of all UOM for products
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
name (optional) string = Returns the asset name
values (optional) array = Returns an array of items contained in the asset
Example HTTP GET Request
Only the asset name is required.
Example JSON Response
In this response we have returned the Orders Legend from within SalesSystemCRM. The returned data is how it would look if nobody had customised the Orders Legend in SalesSystemCRM.
getCart ( )
Description
Requests items or information in the customers shopping basket.
Parameters
session_id (required) string = Current session for the customer on the server
filter (optional) array = An array of fields to return.
- subtotal (optional) string = The subtotal of the items in the shopping basket
- tax (optional) string = The subtotal of the items in the shopping basket
- grandtotal (optional) string = The grand total of the items in the shopping basket
- currency (optional) string = The currency of the shopping basket
- currency_code (optional) string = The currency code of the shopping basket
- name (optional) string = Item Name
- price (optional) string = Item NET Price
- price_inc (optional) string = Item GROSS Price
- code (optional) string = Item Product Code
- category (optional) string = Item Category Code
- size (optional) string = Item Size
- quantity (optional) string = Item Quantity
- total_net (optional) string = Item NET Total
- total (optional) string = Item GROSS Total
- ref (optional) string = Item reference code (unique to SalesSystemAPI)
- last_viewed (optional) array = Array of products viewed by the customer
- contact_ref (optional) string = The customer id / number (if the customer is logged into the SalesSystemCRM API)
- contact_firstname (optional) string = The customer first name (if the customer is logged into the SalesSystemCRM API)
- contact_lastname (optional) string = The customer last name (if the customer is logged into the SalesSystemCRM API)
- contact_team (optional) string = The customers sales team (if the customer is logged into the SalesSystemCRM API)
- contact_priceband (optional) string = The customers price band (if the customer is logged into the SalesSystemCRM API)
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = Current session for the customer on the server
Example HTTP GET Request
The SalesSystemCRM API knows which customer you are requesting by sending over the 'session_id'. The 'filter' parameter specifies which fields you would like to return, and is useful when you only require certain elements of the shopping basket, for example displaying only the total in the shopping basket.
Example JSON Response
Here we have returned certain elements within the basket as well as the totals. Notice how we also have customer data in there - let's because the customer is logged into the API and therefore we can return their data as well.
getContact ( )
Description
Requests the contact details for the customer that is currently logged in. The filter parameter values are returned as name / value pairs.
Parameters
session_id (required) string = Current session for the customer on the server
filter (required) array = The reference name to the SalesSystemCRM asset.
- contact_ref (optional) string = The Contact id / number
- contact_title (optional) string = Title of the Contact.
- contact_firstname (optional) string = The First Name of the Contact.
- contact_lastname (optional) string = The Last Name of the Contact.
- contact_company (optional) string = The Company Name for the Contact.
- contact_address1 (optional) string = First Line of Contact Billing Addresses
- contact_address2 (optional) string = Second Line of Contact Billing Addresses
- contact_address3 (optional) string = Third Line of Contact Billing Addresses
- contact_state (optional) string = Used for US States in Contact Billing Addresses
- contact_postcode (optional) string = Postcode of Contact Billing Addresses
- contact_country_code (optional) string = ISO 3166-1 2-letter country codes
- contact_country (optional) string = Name of Contact Billing Country
- contact_phone (optional) string = Contact phone number
- contact_mobile (optional) string = Contact mobile number
- contact_email (optional) string = Contact Email Address
- contact_fax (optional) string = Contact fax number
- contact_newsletter (optional) string = (Y/N) as Yes or No
- contact_url (optional) string = Contact website address
- contact_url2 (optional) string = Secondary website address
- contact_newsletter (optional) string = (Y/N) as Yes or No
- contact_dataprotect (optional) string = Whether the Contact data can be sold. (Y/N) as Yes or No
- contact_taxable (optional) string = (Y/N/R) as Yes, No, Domestic Reverse Charge
- contact_team (optional) string = Code for the Staff Team
- contact_currency (optional) string = ISO 4217 3-letter Currency Codes
- contact_label (optional) string = Asset
- contact_dob (optional) date = Contacts Date of Birth (YYYY-MM-DD)
- contact_terms (optional) date = Date agreed to Terms and Conditions (YYYY-MM-DD 00:00:00)
- contact_timezone (optional) string = Contacts Timezone
- contact_agentname (optional) string = Name of agent
- contact_assistantname (optional) string = Name of Assistant
- contact_recommendedby (optional) string = Contact Recommended By
- contact_employeeno (optional) integer = No of employees
- contact_companyturnover (optional) integer = Company Turnover
- contact_jobposition (optional) string = Job Position
- contact_distributor (optional) string = Contacts Distrubutor
- contact_aim (optional) string = Contacts AOL Instant Messenger Account
- contact_jabber (optional) string = Contacts Jabber Messenger Account
- contact_skypename (optional) string = Contacts Skype Username
- contact_msn (optional) string = Contacts MSN Messenger Account
- contact_google (optional) string = Contacts Chat Account
- contact_yahoo (optional) string = Contacts YahooChat Account
- contact_gender (optional) string = Contacts gender (male|female)
- contact_blog (optional) string = Contacts blog feed
- contact_twitter (optional) string = Contacts Twitter Account
- contact_facebookuser (optional) string = Contacts Facebook User Account
- contact_facebookpage (optional) string = Contacts Facebook Page
- contact_facebookgroup (optional) string = Contacts Facebook Group
- contact_team (optional) string = Code for the current Staff Team
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = Current session for the customer on the server
Example HTTP GET Request
Our request states that we are after various fields from this customers data by using the 'filter' parameter.
Example JSON Response
Here our response contains all the contact details that we have requested. Although this includes the 'contact_ref' which is the unique customer number within SalesSystemCRM (i.e. 12345 in this case), the SalesSystemCRM API knows who the customer is through the 'session_id' passed in the request.
getInventoryFeed ( )
Description
Requests information on products in SalesSystemCRM. Its intended use is for providing information for XML and RSS product feeds and contains pricing and stock information, which is not available in the more fully featured getProducts method. This method will not initiate a session and does not group results by family.
Parameters
session_id (optional) string = Current session for the customer on the server
skip (optional) integer = Current skip records value
limit (optional) integer = Amount of records to return
sortorder (optional) string = The order in which to sort results (asc|desc)
sortby (optional) string = The filter field which to sort by.
filter (required) array = The reference name to the SalesSystemCRM asset.
- name (optional) string = The product name
- code (optional) string = The product code.
- comment (optional) string = The product comment.
- size (optional) string = The product size.
- category (optional) string = The product category
- category_slug (optional) string = The product category slug
- category_breadcrumb (optional) string = The product category breadcrumb (/ delimiter)
- sale (optional) string = The product sale flag (true|false)
- currency (optional) string = The product currency (ASCII representation)
- slug (optional) string = The slug / permalink for the product
- taxrate (optional) decimal = The default product tax rate (i.e. 0.175 for 17.5 percent tax)
- stock (optional) array = Available stock values at each location for each size
- prices (optional) array = Returns all other prices within the active price bands
- case_quantity (optional) decimal = Returns the case quantity for the item
- layer_quantity (optional) decimal = Returns the layer quantity for the item
- pallet_quantity (optional) decimal = Returns the pallet quantity for the item
- bulk_quantity (optional) decimal = Returns the bulk quantity for the item
- start (optional) string = The sales start date for the product
- end (optional) string = The sales end date for the product
- barcode (optional) string = The product barcode
- outerbarcode (optional) string = The product outer barcode
- feature (optional) string = Name of current feature
- brandname (optional) string = The product brand name
- palletweight (optional) string = The product pallet weight (kg)
- comment (optional) string = The product pallet weight
- shelflife (optional) integer = The product shelf life (days)
- warranty (optional) string = The product warranty (days)
- uom (optional) string = The product UOM Code (see getAsset)
- supplier (optional) string = The suppliers company name
- suppliers_name (optional) string = The suppliers product name
- suppliers_sku (optional) string = The suppliers product code
- imagepath (optional) string = URL to product image on SalesSystemCRM server
- imagealt (auto) string = Alt Text for product image (returned with imagepath)
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (optional) string = Current session for the customer on the server
Example HTTP GET Request
A request for products and their stock values and prices.
Example JSON Response
Our response contains the fields that we have requested through the 'filter' parameter. The 'stock' filter parameter returns an array of values from all locations and the codes for those locations. Similarly the 'prices' filter parameter returns an array of all the active prices and the codes for those price bands. You can the getAsset method to get the relational names of stock locations and price bands.
getOrders ( )
Description
Requests the customers orders. The customer must be logged in.
Parameters
session_id (required) string = Current session for the customer on the server
skip (optional) integer = Current skip records value
limit (optional) integer = Amount of records to return
filter (required) array = The reference name to the SalesSystemCRM asset.
- order_ref (optional) string = The Order id / number
- order_key (optional) string = The Order Key
- order_paid (optional) string = The paid state of the Order (Y/N).
- order_location_code (optional) string = The Location Code of the Order.
- order_location (optional) string = The Location of the Order.
- order_state (optional) string = The current state of the Order.
- order_currency_code (optional) string = The currency code of the Order
- order_currency (optional) string = The currency of the Order
- order_subtotal (optional) string = The subtotal of the Order
- order_taxtotal (optional) string = The taxtotal of the Order
- order_grandtotal (optional) string = The grandtotal of the Order
- order_created (optional) string = The date the order was created
- order_delivery_date (optional) string = The delivery date of the order (Y-m-d)
- order_team (optional) string = The current team of the order
- order_clientref (optional) string = The customers order reference
- order_delivery_address1 (optional) string = Delivery Address 1
- order_delivery_address2 (optional) string = Delivery Address 2
- order_delivery_address3 (optional) string = Delivery Address 3
- order_delivery_state (optional) string = Delivery State (US only)
- order_delivery_postcode (optional) string = Delivery Zip/Postcode
- order_delivery_country (optional) string = Delivery Country
- order_delivery_country_code (optional) string = ISO 3166-1 2-letter country code
- order_pallets (optional) decimal = Amount of Pallets
- order_notes (optional) string = Invoice Notes
- order_delivery_notes (optional) string = Delivery Notes
- order_warehouse_notes (optional) string = Warehouse Notes
- order_manifest_notes (optional) string = Manifest Notes
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = Current session for the customer on the server
found (required) integer = Amount of orders found
Example HTTP GET Request
Our request states that we are after various fields from this customers data by using the 'filter' parameter.
Example JSON Response
The response contains the orders for the customer if they are logged in.
getProduct ( )
Description
Requests product information from SalesSystemCRM inventory. It will return an array of items and an array of stock values for each item.
Parameters
session_id (optional) string = Current session for the customer on the server
sku (required) string = The product code to find
filter (required) array = The reference name to the SalesSystemCRM asset.
- name (optional) string = The product name
- code (optional) string = The product code.
- description (optional) string = The product description.
- size (optional) string = The product size.
- price (optional) string = The product NET price.
- price_inc (optional) string = The product price inc VAT.
- category (optional) string = The product category
- category_slug (optional) string = The product category slug
- sale (optional) string = The product sale flag (true|false)
- currency (optional) string = The product currency (ASCII representation)
- start (optional) string = The sales start date for the product.
- end (optional) string = The sales end date for the product.
- slug (optional) string = The slug / permalink for the product
- sizes (optional) array = All available product sizes within the same family
- stock (optional) array = Available stock values at each location for each size (requires 'sizes')
- prices (optional) array = Returns all other prices within the active price bands (requires 'sizes')
- imagepath (optional) string = URL to product image on SalesSystemCRM server
- imagealt (auto) string = Alt Text for product image (returned with imagepath)
- galleryimagepath (optional) string = URL to gallery image on SalesSystemCRM server
- galleryimagealt (auto) string = Alt Text for gallery image (returned with galleryimagepath)
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = Current session for the customer on the server
Example HTTP GET Request
A request for a product code and all it's available sizes. By specifying the 'sizes' parameter we request an array of all products in the same family and they're sizes and prices.
Example JSON Response
Our response contains the fields that we have requested through the 'filter' parameter and has the inclusion of the 'sizes' array so that other options are available for the customer for products that are within the same family in SalesSystemCRM. Further to this the 'filter' parameter contains the 'stock' parameter which returns an array of all available stock values for your locations. In this case we have in within location WH1 (default location) 10 x ExtraLarge (XL), 20 x Medium (M), 30 x Small (S) products. The 'stock' filter parameter currently returns values from all locations and the names of your locations (which relate to the codes) can be called through the getAsset method.
getProductCategories ( )
Description
Returns product categories containing products for active on a website from within SalesSystemCRM. Supports taxonomy with node and depth access to individual branches of your categories.
Parameters
node (optional) string = A category within a branch
depth (optional) integer = Depth of children from the current node (defaults to 1)
limit (optional) integer = Number of categories to return (defaults to 10)
filter (optional) array - Specified content to return.
- name (optional) string = product category name
- code (optional) string = product category code (used within SalesSystemCRM for assignment)
- slug (optional) string = the slug for the category
- found (optional) integer = sum of products within the category or within the children of the category
- category_description (optional) string = the Category description as specified in SalesSystemCRM Menus
Returns
items (required) array = An array of maps containing categories
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
Example HTTP GET Request
Requests the names and codes of the product categories.
Example JSON Response
Returns all the product categories
getProducts ( )
Description
Returns products from SalesSystemCRM. This method is generally used to provide a list of products for a website and will only return one item from a product family (i.e. not every size of products), please use getProduct to return all items within the products family.
Parameters
category (optional) string = Code for a category as specified in SalesSystemCRM.
feature (optional) string = Code for a feature as specified in SalesSystemCRM.
location (optional) string = Location code which products are sold in SalesSystemCRM (multiples separated by commas)
relatedto (optional) string = Related products.
skip (optional) integer = Current skip records value
limit (optional) integer = Amount of records to return
sortorder (optional) string = The order in which to sort results (asc|desc)
sortby (optional) string = The filter field which to sort by.
exclude_category (optional) string = Excludes category codes the results (delimited by commas)
filter (optional) array - Specified content to return.
- name (optional) string = The product name
- code (optional) string = The product code
- description (optional) string = The product description
- supplier (optional) string = Name of the Supplier
- comment (optional) string = The small product description
- size (optional) string = The product size
- tax (optional) decimal = Product tax rate
- price (optional) string = NET Price
- price_inc (optional) string = Price in VAT
- imagepath (optional) string = URL to image of product
- galleryimagepath (optional) string = URL to gallery image of product
- category (optional) string = The products category
- sale (optional) string = The product sale flag (true|false)
- currency (optional) string = The product currency (ASCII representation)
- start (optional) string = The sales start date for the product
- end (optional) string = The sales end date for the product
- slug (optional) string = The slug / permalink for the product
- location_description (optional) string = The page description for a location (location must be requested)
- meta_description (optional) string = Meta description related to a location (location must be requested)
- meta_keywords (optional) string = Meta keywords related to a location (location must be requested)
- location_slug (optional) string = The slug for the location (location must be requested)
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
found (required) integer = amount of products found
Example HTTP GET Request
Example A Requests products within a category with the code 'AAA', where as Example B requests products within the category by name. Example C requests the products within a feature, which can be defined in SalesSystemCRM Inventory. We are requesting 10 results, skipping the first 40 as the customer has already viewed them.
Example JSON Response
Returns products as defined in the request.
startSession ( )
Description
Starts a session with the SalesSystemCRM API
Parameters
session_id (optional) string = A string to use as a unique session id for the customer
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = The customers current session on the server
Example HTTP GET Request
Just call the method.
Example JSON Response
Returns your 'session_id' ready for use.
updateContact ( )
Description
Takes Client data from a website and updates a Contact in SalesSystemCRM. Customer data provided will always be prefixed with {client_}, whilst customer data returned will always be prefixed with {contact_}. The customer must be logged into the SalesSystemCRM API to will be treated as logged into the API when this method is called.
Parameters
session_id (required) string = Current session for the customer on the server
client_firstname (required) string = The First Name of the Contact.
client_lastname (required) string = The First Name of the Contact.
client_company (optional) string = The Company Name for the Contact.
client_email (required) string = Contact Email Address
client_password (required) string = A password for the client (min 6 chars, [A-Z|0-9])
client_title (optional) string = Mr, Mrs,
client_address1 (optional) string = First Line of Contact Billing Addresses
client_address2 (optional) string = Second Line of Contact Billing Addresses
client_address3 (optional) string = Third Line of Contact Billing Addresses
client_state (optional) string = Used for US States in Contact Billing Addresses
client_postcode (optional) string = Postcode of Contact Billing Addresses
client_country (optional) string = ISO 3166-1 2-letter country codes
client_phone (optional) string = Contact phone number
client_mobile (optional) string = Contact mobile number
client_fax (optional) string = Contact fax number
client_type (optional) string = Asset (defaults to SalesSystemCRM default Contact Type)
client_found (optional) string = Asset (defaults to SalesSystemCRM default Contact Found)
client_url (optional) string = Contact website address (only if valid url)
client_newsletter (optional) string = (Y/N) as Yes or No (defaults to N if unspecified)
client_dataprotect (optional) string = Whether the Contact data can be sold. (Y/N) as Yes or No (defaults to N if unspecified)
client_team (optional) string = Code for the Staff Team (Defaults to 'TM1' the first team within SalesSystemCRM)
client_currency (optional) string = ISO 4217 3-letter Currency Codes (defaults to the system default currency)
client_label (optional) string = Asset (defaults to none - Black)
Returns
error_code (required) integer = The error code (null if no error)
error_message (optional) string = The error message related to the error code
error_invalid (optional) array = Invalid fields and error messages
session_id (required) string = Current session for the customer on the server
contact_ref (required) integer = The customer number
contact_key (required) string = The unique client key returned if request is successful
Example HTTP GET Request
Let the SalesSystemCRM know the 'session_id' of the customer when they are logged in and you can update the Contact within SalesSystemCRM.
Example JSON Response
A successful response will also contain the customer number as the 'contact_ref' (i.e. 12345 in this case).
updateInCart ( )
Description
Updates an item in the shopping basket when provided a reference of the line item. References to line items are unique to the SalesSystemCRM API and can be retreived through the getCart method.
Parameters
ref (required) string = The reference for the line item (usually returned from the getCart method)
quantity (required) string = The quantity of product required
Returns
error_code (required) integer = The error code (null if no error)
error_message (required) string = The error message related to the error code
session_id (required) string = The customers current session on the server
update (required) boolean = (true|false) Item was updated
Example HTTP GET Request
Request to update a line item with a reference of '1234567890' setting the quantity to 12.
Example JSON Response
Returns a successful response with a boolean flag that denotes whether the update was sucessful. We recommend that you run the getCart method afterwards to return a refreshed shopping basket.
SalesSystemCRM API Error Codes
A list of all exception codes from the SalesSystemCRM API. These error codes and messages are returned in the "error_code" and "error_message" elements.
General Errors
- 9001 - Unauthenticated Request
- 9002 - Unregistered Method
- 9008 - Invalid API Key
- 9012 - Invalid Host
- 9015 - Invalid Referrer
- 9050 - Too many connections
User Errors
- 1501 - Client is not logged in.
- 1503 - Client is logged in.
- 1507 - Contact has empty basket.
- 1511 - Username and Password do not match.
- 1515 - Username not found.
Database Related Errors
- 1001 - Not found.
- 1011 - Data input was invalid. ("error_invalid" is also returned)
- 1051 - Not found when adding to Shopping Basket.
- 1061 - Sales Order could not be added.
- 1067 - Line Items could not be added.
- 1071 - Data Invalid Payment could not be processed. ("error_invalid" is also returned)
- 1083 - Payment could not be processed.
- 1092 - Paperwork generation exception.
Payment Errors
- 2000 - The Authorisation was Declined by the bank.
- 2001 - The Authorisation was Rejected by the vendor rule-base.
- 2003 - An ERROR has occurred on the System.
- 2005 - The Void was Successful.
- 2006 - The Abort was Successful.
- 2007 - Please redirect your customer to the ACSURL, passing the MD
- 2008 - The Transaction timed-out.
- 2009 - The network connection to the bank is currently unavailable.
- 2010 - The Authentication was Successful.
- 2011 - The Transaction has been Registered.
- 2012 - The Cancel was Successful.
- 2013 - The Transaction was cancelled by the customer.
- 2014 - The Transaction was Registered Successfully.
- 3002 - The VPSTxId is invalid.
- 3003 - The Currency is invalid.
- 3004 - The Amount is invalid
- 3005 - The Amount is outside the mininum and maximum limits.
- 3006 - The fractional part of the Amount is invalid for the specifi...
- 3007 - The RelatedSecurityKey format invalid.
- 3008 - The Vendor or Vendorname format is invalid.
- 3010 - The RelatedVPSTxId is invalid.
- 3011 - The NotificationURL format is invalid.
- 3012 - The RelatedVendorTxCode format invalid.
- 3013 - The Description is missing.
- 3014 - The TxType or PaymentType is invalid.
- 3015 - The BillingAddress value is too long.
- 3016 - The BillingPostCode value is too long.
- 3018 - The GiftAid flag is invalid. If a value is supplied, should ...
- 3022 - The CustomerEMail is too long.
- 3023 - The Contact Fax is too long.
- 3024 - The ContactNumber is too long.
- 3025 - The DeliveryPostCode is too long.
- 3026 - The DeliveryAddress is too long.
- 3027 - The BillingPostCode is too long.
- 3028 - The BillingAddress is too long.
- 3029 - The FailureURL is missing.
- 3030 - The SuccessURL is missing.
- 3031 - The Amount value is required.
- 3032 - The Amount format is invalid.
- 3033 - The RelatedSecurityKey is required.
- 3034 - The Vendor or VendorName value is required.
- 3037 - The NotificationURL is too long.
- 3039 - The TxType or PaymentType is missing.
- 3041 - The Basket field is too long.
- 3042 - The CustomerName field is too long.
- 3044 - The VendorEMail is too long.
- 3045 - The Currency field is missing.
- 3055 - The CardType field is required.
- 3069 - The PaymentSystem is not supported on the account.
- 3080 - The VendorTxCode value is too long.
- 4025 - The Card Issue Number is invalid.
- 4046 - 3D-Authentication required. Cannot authorise this card.
- 4048 - The Card Number length is invalid.
- 5010 - The CardNumber is required.
- 5012 - The CardHolder name is required.
- 5013 - The card has expired.
- 5014 - The card expiry date is required.
- 5017 - The Security Code is required.
- 5018 - The Security Code length is invalid.
- 5019 - The Security Code is not a number.
- 5020 - The Card Address is required.
- 5021 - The Card Address is too long.
- 5022 - The Post Code value is required.
- 5023 - The Post Code value is too long.
- 5024 - The CardHolder value is too long.
- 5026 - The Card Number is not numeric.
- 5027 - The Card Start Date is invalid.
- 5028 - The Card Expiry Date is invalid.
- 5030 - Unable to decrypt the request message.