Relationship

Relationship is the key object in the Quotevine API. It represents a lead, prospect or customer and can be set up for a private individual, sole trader or corporate body (Ltd company, LLP, charity, etc).

Searching

Note: BEFORE you create a new relationship always call the following to see if any matching relationships are already in the database.

Verb	URL Suffix
POST	/relationships/search

If matching relationship(s) are found it is your responsibility as the API client to decide if you want to accept any of these matches or create a new relationship. If you want to accept an existing relationship, you can of course call the PUT operation to update any fields you need to (although note the requirements around updating as explained in Getting Started With the API).

If nothing is found an empty JSON object (an empty list if you have return_multiple_flag set) is returned and you can proceed to create a new relationship.

Search Attributes

Name	Type	Mandatory	Comments
relationship_name	String	N*	Pass in the forename + surname separated with a space, or if searching for a company the company name
email_address	String	N*
mobile_number	String	N*	Remove all spaces from the number - can also be a landline number
external_reference	String	N*	If searching for a registered company, it is good practice to pass in the company registration number here, as the only parameter.
updated_since	Date	N*	If updated_since is passed, all other parameters are ignored. The minimum date is seven days prior to the current date.
return_multiple_flag	String	Y	Must be set to Y. The API will return any matching relationships it finds (limited to 20 records, sorted most recently created last).

*at least one parameter must be specified

Multiple Return Attributes

The API will only return a subset of the possible relationship fields as only certain data will be useful in evaluating whether an existing relationship is the same logical information as the new relationship you are attempting to add. The fields returned are:

Name	Comments
relationship_id
legal_form
display_name
relationship_status
telephone_number	If legal_form != Private Individual or Sole Trader this will be the telephone_number of the primary contact
telephone_number_2	If legal_form != Private Individual or Sole Trader this will be the telephone_number_2 of the primary contact
mobile_number	If legal_form != Private Individual or Sole Trader this will be the mobile_number of the primary contact
email_address	If legal_form != Private Individual or Sole Trader this will be the email_address of the primary contact
date_of_birth	If legal_form != Private Individual or Sole Trader this will be the date_of_birth of the primary contact
registration_number	Not relevant unless legal_form != Private Individual or Sole Trader
vat_registration_number	Not relevant unless legal_form != Private Individual or Sole Trader
postcode
creation_date	YYYY-MM-DD
last_update_date	YYYY-MM-DD

Core Operations

Verb	URL Suffix	Comments
GET	/relationships/{id}/
POST	/relationships/	relationship_id and display_name must be null or not supplied.
PUT	/relationships/{id}/	Note that you cannot update the following: display_name,relationship_id, sic_2007_description

Relationship Attributes

Name	Type	Mandatory	Comments
relationship_id	Number	n/a	Must not be supplied when using POST or PUT.
external_reference	String	N
account_manager	String	N	Supply email address when using POST or PUT. Must be a valid Quotevine user. If you have round robin groups set up that you want to use for auto-assignment, do not pass anything here when creating a new relationship.
legal_form	String	Y	Must be one of Private Individual, Sole Trader, Limited Company, LLP or Registered Charity. Note that when a Relationship is read from the database, the following are the possible values for this field: LLP Limited Company Micro Enterprise Partnership 4+ Partnership <4 Private Individual Registered Charity Sole Trader
display_name	String	n/a	Must not be supplied when using POST or PUT.
kyc_flag	String	N	Y or N
customer_since	Date	N
last_contact_date	Date	N
email_marketing_flag	String	N	Deprecated. Use the Marketing Permissions Object instead (see related articles, below).
postal_marketing_flag	String	N	Deprecated. Use the Marketing Permissions Object instead (see related articles, below).
phone_marketing_flag	String	N	Deprecated. Use the Marketing Permissions Object instead (see related articles, below).
third_party_marketing_flag	String	N	Deprecated. Use the Marketing Permissions Object instead (see related articles, below).
quality	String	N
source	String	N
relationship_status	String	N	Must be one of Lead, Prospect: Cold, Prospect: Warm, Prospect: Hot, Active, Retention, Lost.
title	String	N	Must be one of Miss, Ms, Doctor, Reverend, Professor, Captain, Major, Sir, Lady, Father, Lieutenant, Lieut Col, Lieut Com, Flight Lt, Lord, Honourable, Judge, Bishop, Brigadier, Canon, Colonel, Commander, Corporal, Count, Countess, Group Capn, Major Genl, Pastor, Rabbi, Prince, Princess, Rev Canon, Rev Doctor, Sergeant, Sister, Mr, Mrs.
forename	String	if legal_form = Individual
middle_name	String	N
surname	String	if legal_form = Individual
telephone_number	String	N	Only use if legal_form = Individual or Sole Trader
telephone_number_2	String	N	Only use if legal_form = Individual or Sole Trader
mobile_number	String	N	Only use if legal_form = Individual or Sole Trader
fax_number	String	N	Only use if legal_form = Individual or Sole Trader
email_address	String	N	Only use if legal_form = Individual or Sole Trader
date_of_birth	Date	N	Only use if legal_form = Individual
nationality	String	N	Only use if legal_form = Individual
residential_status	String	N	Only use if legal_form = Individual. Must be one of Living with Parents, Mortgaged Owner, Outright Owner, Renting
marital_status	String	N	Only use if legal_form = Individual. Must be one of Civil Partnership, Divorced, In Relationship, Living with Partner, Married, Separated, Single, Widowed
occupation	String	N	Only use if legal_form = Individual
occupation_position	String	N	Only use if legal_form = Individual. Must be one of Business Owner, Executive Management, Junior Management, Middle Management, Professional, Skilled Manual, Unemployed, Unskilled Manual
employment_type	String	N	Only use if legal_form = Individual. Must be one of Agency (Full Time), Agency (Part Time), Home Maker, Permanent (Full Time), Permanent (Part Time), Retired, Self Employed, Student, Subcontractor, Temporary (Full Time), Temporary (Part Time), Unable to Work, Unemployed
dependents	Number	N	Only use if legal_form = Individual
right_to_work_flag	String	N	Y or N, only use if legal_form = Individual
criminal_conviction_flag	String	N	Y or N, only use if legal_form = Individual
wage_payment_frequency	String	N	Must be one of Weekly, Fortnightly, Four-weekly,Monthly, only use if legal_form = Individual
wage_payment_day	Number	N	Must be between 1 and 31, only use if legal_form = Individual
preferred_payment_day	Number	N	Must be between 1 and 31, only use if legal_form = Individual
driving_licence_number	String	N	Must be a valid UK driving licence number, only use if legal_form = Individual
driving_licence_type	String	N	Only use if legal_form = Individual. Must be one of Full Other, Full UK, Provisional
driving_licence_expiry	Date	N	Only use if legal_form = Individual
passport_type	String	N	Only use if legal_form = Individual. Must be United Kingdom
payday_loan_flag	String	N	Y or N, only use if legal_form = Individual
wage_salary	Number	N	Only use if legal_form = Individual
gross_annual_salary	Number	N	Only use if legal_form = Individual
facebook_username	String	N	Only use if legal_form = Individual
twitter_username	String	N	Only use if legal_form = Individual
mis_renewal_month	Number	N	Must be between 1 and 12, only use if legal_form = Individual
registered_name	String	if legal_form = Company	Only use if legal_form != Individual
trading_name	String	N	Only use if legal_form != Individual. Only populate this where the Trading Name is different from the Registered Name, or the Relationship is a Sole Trader.
subdomain	String	n/a	Must not be supplied when using POST or PUT.
registration_number	String	N	Only use if legal_form != IndividualMust be a valid UK company registration number format
vat_registration_number	String	N	Only use if legal_form != Individual
establishment_date	Date	N	Only use if legal_form != Individual
annual_turnover	Number	N	Only use if legal_form != Individual
business_description	String	N	Only use if legal_form != Individual
sic_2007	String	N	Only use if legal_form != Individual
sic_2007_description	String	n/a	Must not be supplied when using POST or PUT.
short_term_hire_flag	String	N	Y or N, only use if legal_form != Individual
pooled_mileage_flag	String	N	Y or N, only use if legal_form != Individual
fleet_mgmt_only_flag	String	N	Y or N, only use if legal_form != Individual
system_access_flag	String	n/a	Must not be supplied when using POST or PUT.
mileage_logging_flag	String	N	Y or N, only use if legal_form != Individual
fleet_size_car	Number	N	Only use if legal_form != Individual
fleet_size_lcv	Number	N	Only use if legal_form != Individual
future_fleet_size_car	Number	N	Only use if legal_form != Individual
future_fleet_size_lcv	Number	N	Only use if legal_form != Individual
future_fleet_size_date	Date	N	Only use if legal_form != Individual
payroll_shutoff_day	Number	N	Must be between 1 and 31, only use if legal_form != Individual and mileage_logging_flag = Y
primary_lender	String	N	Only use if legal_form != Individual
primary_lender_contract_expiry	Date	N	Only use if legal_form != Individual
proposal_url	String	N	QV Apply URL unique for this relationship. Only populated of client is set up with QV Apply.