CreateQuoteWebService

Setup

Go to Setup / Reference Data > gb_controls and find the "api_web_services_wrapper_login" control.

Populate this control with a 'web_services' user login and password. This user will be used to run the API from within code.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / APIs and check on WebServices.

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL

https://api.test.catch-e.com/web-services/qt/salesforce/createQuote

Body (JSON)

Contract

Field	Format	Notes	Mandatory
deal_type	string	Deal Type field in Salesforce	No
annual_kilometres	integer	Non-zero positive number	Yes
state_registered	string	State codes: VIC, NSW, ACT, NT, TAS, WA, SA, QLD, NZ. When 'AUS' then must be one of the Australian states. When 'NZ' then must be 'NZ'.	Yes
term	integer	1 - 60	Yes

Client Details

Field	Format	Notes	Mandatory
client_code	string	Catch-e client_code, a short text string identifying the client	Yes
user_id_client_manager	int	Active Catch-e user_id (not at 'deleted' status)	Yes

Driver Details

Field	Format	Notes	Mandatory
create_new_driver_flag	string	Set to 'yes' to create new Driver. Requires driver_external_code if set to 'yes'.	No
driver_external_code	string	Pacman Unique reference used to identify this driver	No
driver_id	string	Alternative to driver_external_code. If driver_id=100000, update existing Driver. If driver_id=0 or not passed, do not create new Driver. If create_new_driver_flag=yes, create new Driver.	No
driver_surname	string	Surname of the driver	Yes
driver_given_name	string	Given name	No
driver_salutation	string	enum: 'Mr', 'Mrs', 'Ms', 'Miss', 'Dr', 'Prof', 'Rev', 'Capt'	No
driver_gender	string	enum: 'Male', 'Female', 'Other'	No
driver_address_1	string	Postal / Home address line 1 e.g. 'Level 1, 30 Coora Road'	No
driver_address_2	string	Postal / Home address line 2	No
driver_area	string	Postal / Home area e.g. 'Oakleigh South'	No
driver_state	string	Postal / Home state	No
driver_postcode	string	Postal / Home postcode	No
driver_home_email	string	Home email	No
driver_phone	string	Home phone number for Driver	No
driver_work_phone	string	Work phone number	No
driver_date_of_birth	string	Date of Birth	No
driver_annual_salary	decimal	Annual gross salary	Yes
employer_fbt_type	string	Choose: 'full-fbt-payable', 'concessional-30000-exempt', 'concessional-17000-exempt', 'rebatable', 'not-applicable'. Must conform to Employer FBT Type business rules.	No
fbt_benefit_type	string	Choose: 'statutory', 'operating', 'exempt'. If Clients / Quote Defaults "Allow Operating FBT Type" unchecked, 'operating' not valid.	No
fbt_business_use	string	Bus. Use %	No
driver_driver_licence	string	Driver's "Licence No" if Driver found or created	No
driver_driver_licence_state	string	Driver's "Licence State" if Driver found or created	No
driver_mobile	string	Driver's "Mobile" if Driver found or created	No

Other

Field	Format	Notes	Mandatory
variant_id	int	Catch-e variant identifier	Yes
aftermarket_requested_flag	string	Override default Aftermarket inclusion flag: 'yes' or 'no'	No
colour_preference	string	Set the colour preference	No
fbt_value	decimal	Sets FBT Value and turn on lock_fbt_value_flag	No
inclusions	string	Adds one or more Lease Inclusion Plans (different from legacy approach)	No
insurance_loading_type_driver_restriction	string	One of: nodriverslessthan26yo, alldrivers, nodriverslessthan22yo	No
insurance_loading_type_licence	string	One of: noloss, lossin2to5years, lossin0to2years	No
insurance_loading_type_past_claims	string	One of: noclaims0to5years, 1claimin12months, 1claimin1to3years, 2+claims0to3years, 3+claimsin0to5years	No
insurer_location_postcode	integer	Use if insurance configured by postcode. Must be valid for state_registered. If not passed, default from Global Controls used.	No
list_price_gross	decimal	Numeric dollar value; takes precedence over list_price_net	No
list_price_gst	decimal	Numeric dollar value	No
list_price_net	decimal	Numeric dollar value	No
location_name	string	Set Insurance location. Displays on Quotes > Contract tab.	No
new_used	string	Indicates vehicle status: 'new', 'used', 'demonstrator'. Defaults to 'new'.	No
odometer	string	If new_used is 'used' or 'demonstrator', must be non-zero integer	No
opportunity_id	string	Salesforce opportunity id	No
opportunity_number	string	Salesforce opportunity #	No
parent_quote_id	int	Quote ID to use as parent of new quote	No
pay_cycle_code	string	Allows setting Pay Cycle. If not passed, Client Pay Cycle used.	No
posting_map_code	string	Contract type code	No
procurement_flag	string	Sets quote vehicle procurement flag	No
product_carbon_emissions_offset_flag	string	Override default Carbon Emissions flag: 'yes' or 'no'	No
product_comprehensive_insurance_flag	string	Override default Comprehensive Insurance flag: 'yes' or 'no'	No
product_extended_warranty_flag	string	Override default Extended Warranty flag: 'yes' or 'no'	No
product_lti_top_up_benefit_name	string	If multiple Top Up Benefits exist, specify which one	No
product_nlpi_flag	string	Override default NLPI inclusion flag: 'yes' or 'no'	No
product_roadside_assistance_flag	string	Override default Roadside Assistance flag: 'yes' or 'no'	No
product_rveh_amount_net	string	Add Relief Vehicle monthly cost to Profile	No
product_rveh_flag	string	Override default Relief Vehicle flag: 'yes' or 'no'	No
product_small_damage_repairs_flag	string	Override default Small Damage Repairs flag: 'yes' or 'no'	No
product_tyre_and_rim_flag	string	Override default Tyre and Rim flag: 'yes' or 'no'	No
product_vehicle_maintenance_program_flag	string	Override default Vehicle Maintenance flag: 'yes' or 'no'	No
product_walkaway_flag	string	Override default Walkaway flag: 'yes' or 'no'	No
purchase_stamp_duty	decimal	Sets Purchase Stamp Duty and turn on lock_purchase_stamp_duty_flag	No
supplier_code_financier	string	Set alternative Financier. Must map to Supplier with 'Supplier Type'='Financier'.	No
user_id_assigned	int	Set Quote 'Assigned' user. Must be active Catch-e user_id.	No
previous_fbt_value	integer	Optional; must be positive number	No
previous_lease_start	integer	User can provide previous lease start date	No
product_lti_flag	string	'yes' or 'no'; pre-populates Plan and Top Up Benefit if only one found	No
product_lti_plan_code	string	If only one active Top Up Benefit for plan, pre-populate it	No
status_flag	string	Must be valid value; default stored in config	No
cost_centre	string	Must be valid value	No
division	string	Must be valid value	No
plate_year	string	Specify Plate Year (1900-2099); default used if not passed	No

Vehicle

Field	Format	Notes	Mandatory
date_first_held	string	date (yyyy-mm-dd). See also FBT Treatment Type.	No
luxury_car_tax_paid_flag	string	yes or no. See also FBT Treatment Type.	No

Input Example

{ "variant_id": "167317", "user_id_client_manager": "10000", "term": "36", "annual_kilometres": "10000", "state_registered": "VIC", "client_code": "MATT", "driver_annual_salary": "77777.77", "driver_surname": "TestSurname", "inclusions": [ { "inclusion_code": "IC1", "inclusion_plan_code": "IPC1" }, { "inclusion_code": "IC2", "inclusion_plan_code": "IPC2" } ], "insurance_loading_type_driver_restriction": "all_drivers", "insurance_loading_type_licence": "loss_in_0_to_3_years", "insurance_loading_type_past_claims": "3_or_more_claims_in_0_to_5_years", "insurer_location_postcode": "3000", "product_lti_plan_code": "LTIMP", "status_flag": "draft" }

Response Details

200 OK

The request was successful.

{ "quote_id": 132657 }

401 Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

You have not authenticated before running this API, or the token_timeout of the current session has passed. You need to authenticate again.

403 Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

You do not have permissions for this request. Go to System Roles and enter 'web_services'. Navigate to the Roles / APIs tab to make sure the permission is checked.

418 Invalid Credentials

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Invalid Credentials", "status": 418, "detail": "Web services API wrapper credentials have not been configured" }

You need to enable Web Services. Go to Setup / Reference Data > gb_controls and find the "api_web_services_wrapper_login" control. Populate with 'web_services' user login and password.

422 Unprocessable Entity

Missing annual_kilometres:

{ "annual_kilometres": { "isEmpty": "Value is required and can't be empty" } }

Input field annual_kilometres is missing.

Missing or invalid variant_id:

{ "variant_id": { "isEmpty": "Value is required and can't be empty", "noRecordFound": "No record matching the input was found" } }

Variant ID is missing from request.

Invalid employer_fbt_type:

{ "employer_fbt_type": { "notInArray": "The input was not found in the haystack" } }

Unknown input. This error may be returned for various fields.

Invalid fbt_benefit_type:

{ "web_service_error": { "CATCH_E_ERROR_FBT_BENEFIT_TYPE_INVALID": "" } }

Invalid benefit type.

Missing fields:

Error Code	Notes
CATCHEERROR_OPPORTUNITY_ID_MISSING	Input field missing
CATCHEERROR_OPPORTUNITY_NUMBER_MISSING	Input field missing
CATCHEERROR_VARIANT_ID_MISSING	Input field missing
CATCHEERROR_USER_ID_CLIENT_MANAGER_MISSING	Input field missing
CATCHEERROR_MISSING_FIELD_LEASE_PERIOD	Input field missing
CATCHEERROR_MISSING_FIELD_ANNUAL_KILOMETRES	Input field missing
CATCHEERROR_TERM_MISSING	Input field missing
CATCHEERROR_ANNUAL_KILOMETRES_MISSING	Input field missing
CATCHEERROR_STATE_REGISTERED_MISSING	Input field missing
CATCHEERROR_INSURER_LOCATION_POSTCODE_MISSING	Input field missing
CATCHEERROR_CLIENT_CODE_MISSING	Input field missing
CATCHEERROR_DRIVER_ANNUAL_SALARY_MISSING	Input field missing
CATCHEERROR_DRIVER_EXTERNAL_CODE_MISSING	Input field missing
CATCHEERROR_DRIVER_SURNAME_MISSING	Input field missing
CATCHEERROR_DEAL_TYPE_MISSING	Input field missing
CATCHEERROR_LIST_PRICE_NET_MISSING	Missing when list_price_gst included
CATCHEERROR_LIST_PRICE_GST_MISSING	Missing when list_price_net included
CATCHEERROR_ODOMETER_MISSING	Missing if NEW_USED is not 'new'

Invalid values:

Error Code	Notes
CATCHEERROR_DEAL_TYPE_INVALID	Must be: 'dealer-non-sourced', 'dealer-sourced', 'private-sale', 'refinance', 'sale-and-leaseback', 'generic-quote'
CATCHEERROR_OPPORTUNITY_ID_INVALID	Input field is empty
CATCHEERROR_OPPORTUNITY_NUMBER_INVALID	Input field is empty
CATCHEERROR_VARIANT_ID_INVALID	Record not found
CATCHEERROR_LIST_PRICE_GROSS_INVALID	Evaluates to zero
CATCHEERROR_LIST_PRICE_NET_INVALID	Evaluates to zero
CATCHEERROR_ANNUAL_KILOMETRES_INVALID	Evaluates to zero
CATCHEERROR_STATE_REGISTERED_INVALID	Must be valid state code
CATCHEERROR_TERM_INVALID	Evaluates to zero
CATCHEERROR_USER_ID_CLIENT_MANAGER_INVALID	Unknown account manager
CATCHEERROR_DRIVER_ANNUAL_SALARY_INVALID	Evaluates to zero
CATCHEERROR_NEW_USED_INVALID	Invalid value
CATCHEERROR_ODOMETER_INVALID	Evaluates to zero if NEW_USED not 'new'

Setup issues:

Error Code	Notes
CATCHEERROR_BAD_QUOTE_TEMPLATE	Data setup issue
CATCHEERROR_CLIENT_CODE_INVALID	Client cannot be read
CATCHEERROR_DRIVER_EXTERNAL_CODE_INVALID	Input field is blank
CATCHEERROR_DRIVER_SURNAME_INVALID	Input field is blank
CATCHEERROR_PARENT_QUOTE_ID_INVALID	Quote cannot be read
CATCHEERROR_FAILED_CREATING_DRIVER	Driver record insert failed
CATCHEERROR_FAILED_UPDATING_DRIVER	Driver record update failed
CATCHEERROR_INSURER_LOCATION_POSTCODE_INVALID	Not an integer
CATCHEERROR_READING_ENCRYPTED_FIELDS	Error reading encrypted fields on callback
CATCHEERROR_POSTING_MAP_CODE_INVALID	Invalid contract type
CATCHEERROR_FBT_VALUE_INVALID	Must be non-zero currency value
CATCHEERROR_UPDATING_OPPORTUNITY	Failed to update Salesforce database
CATCHEERROR_QUOTE_SAVE_FAILED	Failed saving quote in Catch-e database
CATCHEERROR_BAD_CONTRACT_TYPE_DEFAULT	Contract Type 'Status' may be inactive
CATCHEERROR_LOADING_TYPE_PAST_CLAIMS_INVALID	Input field invalid
CATCHEERROR_LOADING_TYPE_LICENCE_INVALID	Input field invalid
CATCHEERROR_LOADING_TYPE_DRIVER_RESTRICTION_INVALID	Input field invalid
CATCHEERROR_PROCUREMENT_FLAG_INVALID	Input field invalid
CATCHEERROR_FINANCIER_CODE_INVALID	Must map to Supplier with 'Supplier Type'='Financier'
CATCHEERROR_PAY_CYCLE_CODE_INVALID	Pay Cycle Code invalid
CATCHEERROR_LTI_PLAN_CODE_MISSING	Required if multiple active Plans found
CATCHEERROR_LTI_PLAN_CODE_INVALID	Plan code not found
CATCHEERROR_LTI_TOP_UP_BENEFIT_NAME_MISSING	Required if multiple Top Up Benefits found
CATCHEERROR_LTI_TOP_UP_BENEFIT_NAME_INVALID	Top Up Benefit name not found
CATCHEERROR_INCLUSION_PLAN_{CODE}_INVALID	No match for nominated Inclusion Plan Code
CATCHEERROR_INCLUSION_SELECTION_INVALID	No match for nominated plans

Quote validation failures:

Term must be greater than months deferred:

{ "web_service_error": { "CATCH_E_ERROR_QUOTE_VALIDATION_FAILED": "Validation failed due to the following error(s): 1. Term must be greater than Months Deferred." } }

Procurement fee setup issue:

{ "web_service_error": { "CATCH_E_ERROR_QUOTE_VALIDATION_FAILED": "Validation failed due to the following error(s): 1. Procurement fee must contain a value." } }

There is a data setup issue for procurement. The default='0' but procurement_flag='no'. To fix, update to contain a value or set procurement_flag='no' or remove from call.

Missing insurance postcode:

{ "web_service_error": { "CATCH_E_ERROR_QUOTE_VALIDATION_FAILED": "Validation failed due to the following error(s): 1. A valid Insurance Postcode is required!" } }

Data setup issue. The qt_insurer_locations_by_postcode table should be populated with all locations. Insurance Type may not be set for variant.

Missing insurance location:

{ "web_service_error": { "CATCH_E_ERROR_QUOTE_VALIDATION_FAILED": "Validation failed due to the following error(s): 1. Insurance Location is required!" } }

Data setup issue. When product_comprehensive_insurance_flag='yes', the qt_insurer_location table MUST be populated with minimum dataset for each Australian State/Territory.

Invalid cost_centre:

{ "cost_centre": { "noRecordFound": "No record matching the input was found" } }

The cost_centre is not stored for the Client.

Invalid division:

{ "division": { "noRecordFound": "No record matching the input was found" } }

The division is not stored for the Client.

Invalid plate_year:

{ "plate_year": { "invalidPlateYear": "Not within valid range 1900-2099" } }

The plate_year is invalid.

Invalid employer_fbt_type:

{ "client_code": { "quoteException": "Quote employer_fbt_type must be 'concessional-30000-exempt' or 'full-fbt-payable'" } }

The employer_fbt_type is not valid. The validation message returns the types valid for this client. Visit the Employer FBT Type page for required conditions.

Operating FBT type not allowed:

{ "fbt_benefit_type": { "operatingFbtTypeNotAllowed": "Operating FBT type is not allowed due to client configuration" } }

If Clients / Quote Defaults "Allow Operating FBT Type" unchecked, 'operating' not valid. Choose different FBT type or update client settings.

424 Failed Dependency

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Failed Dependency", "status": 424, "detail": "Upstream service temporarily unavailable. Please retry." }

The API cannot run at this time. This can happen for various reasons: service resource limits exceeded, system in maintenance mode.

Troubleshooting

The Financier used for this service will default from the Clients / Quote Defaults "Financier" record.

This Financier must have all of the following table records present (if not the Financier will be blank):

Populated when creating a new Suppliers record.
Populated when creating a new Suppliers record and the Supplier Type is 'Financier'.
Go to Reference Data screen to create/edit these records.