What are Custom Accounts/ERP Integrations?
Custom Account integrations refer to the process where third-party developers create tailored integrations between an ERP (Enterprise Resource Planning) or Inventory Management System and another software or platform. These custom integrations allow for the customisation of the integration name and provide a custom order confirmation REST API endpoint, making the integration appear more native and seamless to the user.
How do I use a Custom Accounts/ERP Integration?
If you want to get started with one of these integrations please let us know by emailing help@prospectsoft.com. Or speaking to a member of the team.
Getting Started
This section will cover getting some very basic data flowing between the ERP System and your CRM. This will not be enough to get a working integration completed, but it will get you familiar with our API and prepare you to move on to the MVP working integration.
Useful Links
To interact with our API, you will need a PAT (Personal Access Token). More information on how to obtain one can be found in this document.
We have also created a handy article which contains an overview of the OData API so that you can get started efficiently.
A list of all the GET/POST Endpoints available in our API can be found on this page.
Operating Company
In the CRM, the Operating Company is the connection to the ERP system. It is possible to have multiple Operating Companies if a customer has multiple ERP systems. When importing information into the CRM, you'll need to pass the Operating Company Code.
If you look at the /HomeCurrencies Endpoint, you can find the list of Operating Companies your Workspace has setup and see the Operating Company Code – it is a Single Character Code.
Product Item Import
If you look at the /ProductItems Endpoint, you can find the list of Product Item Imports your Workspace has setup and see the Product Item Import code. Visit our API Docs with details about the POST request for Product Items.
Required fields
Below is the list of the required fields for the creation of a Product Item Record:
{
"OperatingCompanyCode": "",
"ProductItemId": "",
"Description": "",
"CategoryId": "",
“SellingPrice”:
}
Note: The "CategoryID" needs to match the ID of a Product Category that exists in the CRM. For the purpose of the Quick Start, use Code CATEGORY-A
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"ProductItemId": "TESTITEM",
"Description": "Test Product Item",
"CategoryId" : "CATEGORY-A",
"SellingPrice": 1234
}
Note: We store values such as SellingPrice as INTEGER values; by default, the system treats prices to 2 decimal places. However, this article will explain how to amend this later so, before importing a Sell Price, you need to multiply it by 100 e.g. £12.34 should be imported as 1234.
Sales Ledger Import
If you look at the /SalesLedgers Endpoint, you can find the list of Sales Ledger Imports your Workspace has setup and see the Sales Ledger Import code. Visit our API Docs with details about the POST request for Sales Ledgers.
Required fields
Below is a list of the required fields for the creation of a Sales Ledger Record:
{
"OperatingCompanyCode": "",
"SalesLedgerId": "",
"Name": “”
}
OPTIONAL FIELDS – The following fields are not required to add a Sales Ledger but would add some useful data to the CRM.
{
"AddressLine1": "",
"AddressLine2": "",
"AddressLine3": "",
"AddressLine4": "",
"AddressLine5": "",
"Postcode":"",
"Country":"",
"Telephone":"",
"Fax":"",
"Email":"",
”Website":""
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"SalesLedgerId": "TEST000123",
"Name": "Test Sales Ledger",
"AddressLine1": "Test Line 1",
"AddressLine2": "Test Line 2",
"AddressLine3": "Test Line 3",
"AddressLine4": "Test Line 4",
"AddressLine5": "Test Line 5",
"Postcode": "AA11 2BB",
"Country": "United Kingdom",
"Telephone":"12345 678901",
"Fax":"98765 432100",
"Email":"Test@example.com",
”Website":"www.example.com"
}
Customer Creation
You should now log in to the Test Drive and Manually Create a record, assigning it a Sales Ledger you have just imported.
This guide will walk you through how to create a new record, ensuring you enter the Sales Ledger ID:
Order Creation
Now that you have a Product Item, Sales Ledger and a Customer Record, you can start creating a Quote in the system that can be converted into an Order.
Creating a quote
This guide will walk you through how to create a Quote.
Confirming an Order
Depending on how you are writing your integration, order confirmation can be done in one of two ways:
2) You poll thE CRM for Orders Waiting to be Confirmed
We would recommend Method 1 as the preferred way to manage Order Confirmation, but Method 2 will also enable you to confirm orders.
Method 1 – The CRM calls an Endpoint
When a user clicks the Confirm button against a quote, a request will be made to your Endpoint along with the Quote ID that is being confirmed and Endpoint details for Confirming or Rejecting the order:
{
"quoteId": 1294,
"confirmEndpoint": {
"endpoint":"http://integration.prospect365.com/quote/1234/confirm",
"token":"eas:m1/j8tR4D4s+...."
},
"rejectEndpoint": {
"endpoint":"http://integration.prospect365.com/quote/1234/reject",
"token":"eas:m1/j8tR4D4s+...."
}
}
Next, you will need to set up the Endpoint you want it to call, in the CRM Settings:
Select System Settings, then Integrations from the navigation menu. Under "Operating Companies, Inventory Management, Accounts & ERP Integrations”, click on "Click to Configure":
To open a detailed record of an operating company, click on the company name under the Description.
Click on the pencil on the right hand side to open up the integration pop-up window. Select "Other":
You can enter a name for your Integration, the Authentication Scheme, Key or Token and the Order Confirmation Endpoint.
Order Confirmation Response
Upon receiving a call to confirm an order, the endpoint should return immediately to acknowledge that the request has been received. This is expected to be done before the order has been processed and the response to the order confirmation call should reflect that the request has been received and understood, not whether the order was confirmed successfully into the third party system.
You will receive one of the two following messages:
Successful
{
“success”: “true”
}
Unsuccessful
{
“success”: “false”,
“message”: “failure message”
}
Once you have the Quote ID of the quote that has been confirmed, you can then retrieve the details of the customer and the lines on the quote.
Obtaining Quote Header Details
If you look at the /Quotes Endpoint, you can find the list of Quote Imports your Workspace has setup and see the Quote Import code. Visit our API Docs with details about the POST request for Quotes.
Below is an example GET Request that can be used to retrieve details of from the Quote Header:
/Quotes?
$select=Orderedby,SalesLedgerOrderPlacedOnId,Description,DeliveryName,DeliveryAddressLine1,DeliveryAddressLine2,DeliveryAddressLine3,DeliveryAddressLine4,DeliveryAddressLine5,DeliveryPostcode,DeliveryCountry,DeliveryNotes1,DeliveryNotes2,CustomerOrderReference,DecimalForeignNetValue&$filter=StatusFlag ne 'D' and QuoteId eq ????
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
Orderedby – The usercode of the user who confirmed the order
SalesLedgerOrderPlacedOnId – The Sales Ledger ID the order was placed on
Description – The description of the quote entered by the user (this could be blank)
DeliveryName – Delivery Name
DeliveryAddressLine1 – Delivery Address Line 1
DeliveryAddressLine2 – Delivery Address Line 2
DeliveryAddressLine3 – Delivery Address Line 3
DeliveryAddressLine4 – Delivery Address Line 4
DeliveryAddressLine5 – Delivery Address Line 5
DeliveryPostcode – Delivery Postcode
DeliveryCountry – Delivery Country
DeliveryNotes1 – Delivery Notes Line 1
DeliveryNotes2 – Delivery Notes Line 2
CustomerOrderReference – Customer PO Reference
DecimalForeignNetValue – Total Net Order Value
This GET retrieves a lot of the information you may require when creating an order in your ERP system. If you require further information, please use the docs to find the field names and add them as required.
Obtaining Quote Line Details
If you look at the /QuoteLines Endpoint, you can find the list of QuoteLine Imports your Workspace has setup. Visit our API Docs with details about the POST request for QuoteLines.
Below is an example GET Request that can be used to retrieve details of the lines on the Quote:
/QuoteLines?$select=DecimalForeignNetValue,DecimalForeignPrice,DecimalQuantity,Description,ProductItemId,Quote,Sequence&$filter=StatusFlag ne 'D' and Quote/QuoteId eq ????&$orderby=Sequence asc
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
DecimalForeignPrice – This is the price of the item before any line discount has been applied
DecimalForeignNetValue – This is the Net Total Line Value
DecimalQuantity – This is the Quantity for the Line
ProductItemId – This is the Product Code for the Line
Description – This is the Product Description on the Line
This GET retrieves a lot of the information you may require when creating an order in your ERP system. If you require further information, please use the docs to find the field names and add them as required.
Once you have processed the order into the ERP system, you then need to let us know if this was successful or unsuccessful. The original post contains 'Confirm' and 'Reject' links that can be used to update the order in the CRM.
Confirm Order
The Endpoint for a confirmed order is as follows: https://integration.prospect365.com/quote/????/confirm
Where ???? is the Quote ID.
When posting to the Endpoint you will need to send a "success" and Order Number value. For confirming orders, "success" will always be true, and the order number will be the order number from your ERP system.
{
“success”: true,
“ordernumber”: “”
}
Example Body of a POST Request
{
“success”: “true”,
“ordernumber”: “ORD001234”
}
Reject Order
The Endpoint for a confirmed order is as follows: https://integration.prospect365.com/quote/????/reject
Where ???? is the Quote ID.
When posting to the Endpoint you will need to send a "success" and message for rejecting. For rejecting orders, "success" will always be false, and the message should be something useful to the user e.g. Sales Ledger Invalid, Product Code incorrect. The message will therefore be something the user can correct and re-try.
{
“success”: false,
“message”: “”
}
Example Body of a POST Request
{
“success”: “false”,
“messsage”: “Order failed to confirm because the account is on stop”
}
Method 2 – Polling the CRM for Orders
If it is not possible to setup an Endpoint for the CRM to call when an Order is placed, you can poll the CRM for orders that are Waiting to be Confirmed instead.
On Hold
Within the CRM it is possible to place a Quote or Order as On Hold. If this is the case the Quote should not be confirmed into the ERP System until it is taken off hold.
Retrieve Orders Waiting to be Confirm
Below is an example GET Request for all quotes that are in a status of Waiting to be Confirmed and currently not On Hold:
/Quotes?$select=QuoteId&$filter=StatusFlag eq 'A' and StatusId eq 1 and OperatingCompanyCode eq 'A' and OnHold eq 0
Once you have a list of the Quotes that needs to be processed, you can then loop through them one at a time and create the orders.
Obtaining Quote Header Details
If you look at the /Quotes Endpoint, you can find the list of Quote Imports your Workspace has setup and see the Quote Import code. Visit our API Docs with details about the POST request for Quotes.
Below is an example GET Request that can be used to retrieve details from the Quote Header:
/Quotes?$select=Orderedby,SalesLedgerOrderPlacedOnId,Description,DeliveryName,DeliveryAddressLine1,DeliveryAddressLine2,DeliveryAddressLine3,DeliveryAddressLine4,DeliveryAddressLine5,DeliveryPostcode,DeliveryCountry,DeliveryNotes1,DeliveryNotes2,CustomerOrderReference,DecimalForeignNetValue&$filter=StatusFlag ne 'D' and QuoteId eq ????
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
Orderedby – The usercode of the user who confirmed the order
SalesLedgerOrderPlacedOnId – The Sales Ledger ID the order was placed on
Description – The description of the quote entered by the user (this could be blank)
DeliveryName – Delivery Name
DeliveryAddressLine1 – Delivery Address Line 1
DeliveryAddressLine2 – Delivery Address Line 2
DeliveryAddressLine3 – Delivery Address Line 3
DeliveryAddressLine4 – Delivery Address Line 4
DeliveryAddressLine5 – Delivery Address Line 5
DeliveryPostcode – Delivery Postcode
DeliveryCountry – Delivery Country
DeliveryNotes1 – Delivery Notes Line 1
DeliveryNotes2 – Delivery Notes Line 2
CustomerOrderReference – Customer PO Reference
DecimalForeignNetValue – Total Net Order Value
We believe this GET retrieves a lot of the information you may require when creating an order in your ERP system. If you require further information, please use the docs to find the field names and add them as required.
Obtaining Quote Line Details
If you look at the /QuoteLines Endpoint, you can find the list of QuoteLine Imports your Workspace has setup. Visit our API Docs with details about the POST request for QuoteLines.
Below is an example GET Request that can be used to retrieve details of the lines on the Quote:
/QuoteLines?$select=DecimalForeignNetValue,DecimalForeignPrice,DecimalQuantity,Description,ProductItemId,Quote,Sequence&$filter=StatusFlag ne 'D' and Quote/QuoteId eq ????&$orderby=Sequence asc
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
DecimalForeignPrice – This is the price of the item before any line discount has been applied
DecimalForeignNetValue – This is the Net Total Line Value
DecimalQuantity – This is the Quantity for the Line
ProductItemId – This is the Product Code for the Line
Description – This is the Product Description on the Line
We believe this GET retrieves a lot of the information you may require when creating an order in your ERP system. If you require further information, please use the docs to find the field names and add them as required.
Once you have processed the order into the ERP system you then need to let us know if this was successful or unsuccessful. The original post contains Confirm and Reject links that can be used to update the order in the CRM.
Confirm Order
The Endpoint for a confirmed order is as follows: https://integration.prospect365.com/quote/????/confirm
Note: ???? is the Quote ID
When posting to the Endpoint you will need to send a "success" and Order Number value. For confirming orders "success" will always be true, and the order number will be the order number from your ERP system.
{
“success”: true,
“ordernumber”: “”
}
Example Body of a POST Request
{
“success”: “true”,
“ordernumber”: “ORD001234”
}
Reject Order
The Endpoint for a confirmed order is as follows: https://integration.prospect365.com/quote/????/reject
Note: ???? is the Quote ID
When posting to the Endpoint you will need to send a "success" and message for rejecting. For rejecting orders, "success" will always be false, and the message should be something useful to the user e.g. Sales Ledger Invalid, Product Code incorrect. The message will therefore be something the user can correct and re-try.
{
“success”: false,
“message”: “”
}
Example Body of a POST Request
{
“success”: “false”,
“messsage”: “Order failed to confirm because the account is on stop”
}
Upon completing this Quick Start section, you should be comfortable importing data and posting it to the CRM.
You should now have the following items working:
A Product Item Import
A Sales Ledger Import
Order Confirmation using Either:
An Endpoint for Order Confirmation
A polling routine looking for Waiting to be Confirmed Quotes
Confirmation of Orders in the CRM
MVP – Minimum Viable Product
Now that you have a basic flow of data between your ERP and CRM systems, we can now begin to build on this basic integration and start turning it into an MVP version.
For an MVP version, we think the following should be included:
Import of VAT Rates
Import of Currencies
Import of Product Categories
Import of Product Items
Import of Sales Ledgers
Creation of a Customer Record (Missing Customer Import)
Creation of an Order in the 3rd Party System
Updating the CRM with the Order Number
Sales Order Header Import
Sales Orders Import
Sales Invoices Import
Sales Credits
Sales Invoice Header
Some of these we have already touched on in the Quick Start section, but we are going to revisit and add some extra details.
VAT Rate Import
VAT is a complex topic, and there will be a more detailed section on VAT later in this document. For MVP purposes we are going to keep it simple and assume that all sales are taking place in the Home Country.
In a later section we will cover Import of VAT Rates for EC Registered Companies, or other countries you are VAT registered in.
If you look at the /VatRates Endpoint, you can find the list of VatRates Imports your Workspace has setup. Visit our API Docs with details about the POST request for VatRates.
Below is the list of the required fields for the creation of a VAT Rate Record:
{
“OperatingCompanyCode": "",
"CountryType": "H", "TransactionType": "S",
"TaxCode": "",
"Description": "",
"Rate1":
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"CountryType": "H",
"TransactionType": "S",
"TaxCode": "S",
"Description": "Standard",
"Rate1": 20.0000
}
Note: For the moment S will represent Home Sale
Note: For the moment H will represent Home Country
In later imports we can Assign these Tax Codes to Products and Customers to say how they should have their VAT applied.
Currency Import
If you look at the /ForeignCurrencies Endpoint, you can find the list of ForeignCurrencies Imports your Workspace has setup. Visit our API Docs with details about the POST request for ForeignCurrencies.
Below is the list of the required fields for the creation of a Currency Record:
REQUIRED FIELDS
{
"OperatingCompanyCode": "",
"Description": "",
"CurrencyCode": "",
"Decimals": , Note: How many decimal places does the Currency have, default is 2
"CurrencyRate": , Note: Exchange Rate * 10000 to go from your Home Currency to this currency
"Multiply": , Note: Do you need to multiple (1) or divide (0) by the CurrencyRate to convert a value in home currency to this Currency,
“IsoCode”: “” Note: If the currency code is the IsoCode of the Currency this will be set automatically, if it is not this should be set to the IsoCode of the currency e.g. Euro = EUR
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"Description": "EUR",
"CurrencyCode": "EUR",
"Decimals": 2,
"CurrencyRate": 7100,
"Multiply": 1,
“IsoCode”: “EUR”
}
Product Category Import
In the quick start section, we briefly mentioned Product Category when we imported Product Items. In the CRM, you can import your ERPs full stock tree structure if you would like it for reporting.
If you look at the /ProductCategories Endpoint, you can find the list of ProductCategories Imports your Workspace has setup. Visit our API Docs with details about the POST request for ProductCategories.
Below is the list of the required fields for the creation of a Product Category Record:
REQUIRED FIELDS
{
"OperatingCompanyCode": "",
“CategoryId": "",
"Description": "",
“ParentCategory”: “” * This should be set for child Category’s, this should match the Parent Category’s ID and needs to exist
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A”,
"CategoryId" : "TEST",
"Description": "Test Category"
}
Product Item Import
If you look at the /ProductItems Endpoint, you can find the list of ProductItems Imports your Workspace has setup. Visit our API Docs with details about the POST request for ProductItems.
Building on what was covered in the Quick Start section, within our Product Item table there are more fields you may want to consider importing:
ADDITIONAL FIELDS
{
“VatCode”: “”, Note: This ID Needs to Match the ID of a VAT Rate Imported Earlier
“CostPrice”: ,
“ExtendedDescription: “”,
“Sku”: “”,
“Obsolete”: Note: This field can be a 1 or 0, 0 for Active Products, 1 for Discontinued / Dormant Products. If the product is active this can be skipped as the default is 0
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"ProductItemId": "TESTITEM",
“VatCode”: “S”,
“CostPrice”: 789,
“ExtendedDescription”: “Test Extended Description”,
“Sku”: “Test Sku”,
“Obsolete”: 0
}
Note on CostPrice: We store values such as CostPrice as INTEGER values. By default the system treats prices to 2 decimal places. In a later chapter we will talk about amending this, but by default it is set to 2 Decimal Places. For example, before importing a Cost Price you need to multiple it by 100 e.g. £12.34 should be imported as 1234.
Sales Ledger Import
If you look at the /SalesLedgers Endpoint, you can find the list of SalesLedgers Imports your Workspace has setup. Visit our API Docs with details about the POST request for SalesLedgers.
Building on what was covered in the Quick Start section, within our Sales Ledger table there are more fields you may want to consider importing:
ADDITIONAL FIELDS
{
“TaxCode”: “”, Note: This ID Needs to Match the ID of a VAT Rate Imported Earlier
“OnStop”: ,
“Balance”: ,
“CreditLimit”: ,
“CurrencyCode”: “”, Note: This needs to match a code from the Currency Import
“VatRegistrationCode”: “”,
“InvoiceTo”: “”, Note: This ID Needs to Match the ID of an existing Sales Ledger
“Closed”: , Note: This field can be a 1 or 0, 0 For Open, 1 for Closed, If the Ledger is Open this can be skipped as the default is 0
“DisplayDescription”: “”, Note: If you ERP system has GUIDs for the Primary Key of a ledger, we recommend this being stored in SledgerId and the friendly code being stored here e.g. ABC123 or Customer Name e.g. Test Sales Ledger.
}
Example Body of a POST Request:
{
"OperatingCompanyCode": "A",
"SalesLedgerId": "TEST000123",
“TaxCode”: “S”,
“OnStop”: 0,
“Balance”: 1000,
“CreditLimit”: 100000.
“CurrencyCode”: “GBP”,
“VatRegistrationCode”: “GB1234”,
“InvoiceTo”: “INV0000123”,
“Closed”: 0,
“DisplayDescription”: “ABC123”
}
Order Creation
Now we are importing more information from the ERP system, we can add additional fields to our queries. Obtaining more information from the Quote in the CRM such as VAT Codes, VAT Amounts, and Currency Codes.
Obtaining Quote Header Details
If you look at the /Quotes Endpoint, you can find the list of Quotes Imports your Workspace has setup. Visit our API Docs with details about the POST request for Quotes.
Below is an example GET Request that can be used to retrieve details of from the Quote Header:
/Quotes?$select=CurrencyCode,Orderedby,SalesLedgerOrderPlacedOnId,Description,DeliveryName,DeliveryAddressLine1,DeliveryAddressLine2,DeliveryAddressLine3,DeliveryAddressLine4,DeliveryAddressLine5,DeliveryPostcode,DeliveryCountry,DeliveryNotes1,DeliveryNotes2,CustomerOrderReference,DecimalForeignNetValue,DecimalForeignGrossValue,DecimalForeignTaxValue&$filter=StatusFlag ne 'D' and QuoteId eq ????
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
CurrencyCode – The Currency the Quote was made in
Orderedby – The usercode of the user who confirmed the order
SalesLedgerOrderPlacedOnId – The Sales Ledger ID the order was placed on
Description – The description of the quote entered by the user (this could be blank)
DeliveryName – Delivery Name
DeliveryAddressLine1 – Delivery Address Line 1
DeliveryAddressLine2 – Delivery Address Line 2
DeliveryAddressLine3 – Delivery Address Line 3
DeliveryAddressLine4 – Delivery Address Line 4
DeliveryAddressLine5 – Delivery Address Line 5
DeliveryPostcode – Delivery Postcode
DeliveryCountry – Delivery Country
DeliveryNotes1 – Delivery Notes Line 1
DeliveryNotes2 – Delivery Notes Line 2
CustomerOrderReference – Customer PO Reference
DecimalForeignNetValue – Total Net Order Value
DecimalForeignGrossValue – Total Gross Order Value
DecimalForeignTaxValue – Total Tax Value for the Order
We believe this GET retrieves a lot of the information you may require when creating an order in your ERP system. If you require further information, please use the docs to find the field names and add them as required.
Obtaining Quote Line Details
If you look at the /QuoteLines Endpoint, you can find the list of QuoteLine Imports your Workspace has setup. Visit our API Docs with details about the POST request for QuoteLines.
Below is an example GET Request that can be used to retrieve details of the lines on the Quote:
/QuoteLines?$select=DecimalForeignDiscountPrice,DecimalForeignNetValue,DecimalForeignPrice,DecimalGrossValue,DecimalTaxValue,DecimalQuantity,DecimalDiscountPerUnit,DecimalDiscountNetValue,DecimalDiscountPercentage,Description,ProductItemId,Quote,Sequence,TaxCode&$filter=StatusFlag ne 'D' and Quote/QuoteId eq ????&$orderby=Sequence asc
Note: ???? is the Quote ID
Below is a list defining each of the terms used in the GET Request:
DecimalForeignPrice – This is the price of the item before any line discount has been applied
DecimalForeignDiscountPrice – This is the price of the item after the line discount has been applied
DecimalDiscountPerUnit – This is the Discount Amount Per Item
DecimalDiscountNetValue – This is the Discount Amount For the Line
DecimalDiscountPercentage – This is the Discount Percentage Applied to the Line
DecimalForeignNetValue – This is the Net Total Line Value
DecimalGrossValue – This is the Gross Total Line Value
DecimalTaxValue – This is the Total Tax for the Line
DecimalQuantity – This is the Quantity for the Line
ProductItemId – This is the Product Code for the Line
Description – This is the Product Description on the Line
TaxCode – The tax code applied to the Line