This page documents the REST resources available in Accelerate, including the HTTP response codes and example requests and responses. These documents are intended for your web\app developers.
Note: If you are new to developing with Accelerate? Request a Sandbox\Development client.
For Multi-Tenant clients please raise a support request to get a sandbox client setup
For Dedicated clients please test on your UAT environment before moving to production
Caution: The API supports the GET (for reading), POST (for inserting) and PUT (for updating) HTTP verbs. It is not possible to delete objects using the API.
Info: QV Systems does not keep a record of your requests into the API. Like all systems - at times the API may be unavailable. Therefore you must always record the data you wish to send to the API in the database of the calling application, and implement functionality to periodically resend any failed requests to the API.
To ensure that API performance and/or availability does not impact your application’s user experience, write your user’s input into the database of the calling application, and then send it to Accelerate using an asynchronous mechanism, including the ability to periodically resend any failed requests to the API.
Authentication and access
In order to access the Accelerate API, we must be sure that the request is coming from an authorised application. This is achieved by only granting access to applications which can present a key that could only have been created by an application administrator.
Info: As an application developer wishing to authenticate with Accelerate you must supply the API Key that has been provided to you in each call by populating it into an HTTP header named API-key.
Generating API key
Each application or website you want to connect to Accelerate should have its own, separate API Application. If the application you want to connect has different environments (e.g. development, UAT and production) then each of these environments should again have its own API Application.
API Keys can only be generated by Accelerate system administrators.
Creating an API Application and generating the API key is simple :
Navigate to the ‘Settings’ section in the menu.
Scroll down to the API Applications area.
Click ‘Add Application’
Enter your API application details
Expand to view the fields and their meanings
Expand to view the fields and their meanings
Description | A name for the application you want to connect. e.g. Main Website (Development Environment) |
API Key | This will be created by the system when you press save. |
Error Email Address | This email will be notified whenever the data passed by the application to the Accelerate API is invalid. |
Outbound Email Address | This email will be used whenever a record created by the API causes an email to be sent from the system (for instance if your website passes enquiries into Accelerate, and you have actions set up in Accelerate to automatically email the prospect). |
Read Allowed | This controls whether this API Application will be able to read from the API, or only write. Leaving this unchecked provides maximum data security for applications that only need to push data in (e.g. enquiry forms). |
Click Save and confirm, this will generate the key, which can then be found in your list of API Applications
Note: You must supply the API Key that has been provided to you in each call by populating it into an HTTP header named api-key
Please contact the support help desk via LiveChat to revoke your API Key.
Ping your client
To test that you have the necessary connectivity, attempt the following call using an HTTP or HTTPS GET :
https://{{subdomain}}.quotevineapp.com/qvine/quotevine/api/v2/ping
You should receive an HTTP 200 OK with a body confirming all is well.
You can use ping to schedule in API health checks, or to test all is well before you make a transactional call.
Additional points to note:
It is up to the client application to call the Search API (with multiple flags set to true) to check whether a match already exists in the database before creating a new Relationship. We will return all matching records - it's up to your application to decide how to choose between them when you get multiples back.
SETTING MULTIPLE FLAG TO FALSE IS UNSUPPORTED
A call to the API will always result in either a 200/201 or a 4xx. If you get a 4xx then you will also get an email to the email address specified in your API application.
If you are building an integration to an Accelerate instance that already contains live data, we strongly recommend that a sandbox instance is purchased for the duration of development, to eliminate the risk of damage to the live database.
If you are updating an object via the API you must pass ALL populated fields back to the PUT call, not just the field you want to update.
{
"relationship_id":357232341,
"external_reference":"357232341",
"account_manager":"[email protected]",
"legal_form":"Limited Company",
"display_name":"QV Systems",
"business_description":"SaaS Software Design"
...
}
If you update the external_reference field. You must pass the following into the PUT call
{
"external_reference":"ABCDEFGH",
"account_manager":"[email protected]",
"legal_form":"Limited Company",
"display_name":"QV Systems",
"business_description":"SaaS Software Design"
...
}Note: Relationship_id is deliberately omitted as IDs are not passed in for POST or PUT
Failure to pass all populated fields will result in data loss for your client. As an example, say the following relationship is read from the API:
Dates
For all requests dates must be supplied in ISO format
Example of date without time: 2013-06-28
If a time is relevant then 2013-06-28 02:17:26
Enquiry Flow: Automotive Finance
The usual workflow is:
Search for an existing relationship. If necessary, create a new one.
Create a new opportunity. Naming these opportunities well is key to usability so be sure to ask your client how they would like them named! Also, if a website user makes multiple enquiries in a short period of time your client might want them to all be attached to the same opportunity, so be sure to ask that question too.
Create any opportunity notes (e.g. to pass on comments entered into a web form)
Create a quote (if the customer is enquiring on a specific vehicle and you have CAP data in your website)
Create any quote options (if the customer is enquiring on a specific vehicle and you have CAP data in your website).
Webhooks
A webhook is a method of posting information (in our case JSON) to an HTTPS endpoint when an event happens in the source system.
Accelerate has the ability to trigger the following types of webhooks:
Quote/Proposal
Opportunity
Order
Contract
In order for the Webhook actions to fire successfully you will need to create an API Application record via Settings > API Applications, making sure that the description is set to Webhooks and the Read Allowed checkbox is ticked.
In each case the JSON payload is the same as per the GET of the relevant Objects.