Working with Contacts in Zoho Books

Overview

The following operations allow you to work with contacts. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with contacts, see Sample configuration.

Operation	Description
createContact	Creates a contact.
getContact	Retrieves details of a contact.
listContacts	Retrieves all contacts with pagination.

Operation details

This section provides further details on the operations related to contacts.

Creating a contact

The createContact operation creates a contact with the given information.

createContact

<zohobooks.createContact>
    <creditnoteEmailTemplateId>{$ctx:creditnoteEmailTemplateId}</creditnoteEmailTemplateId>
    <estimateEmailTemplateId>{$ctx:estimateEmailTemplateId}</estimateEmailTemplateId>
    <invoiceEmailTemplateId>{$ctx:invoiceEmailTemplateId}</invoiceEmailTemplateId>
    <creditnoteTemplateId>{$ctx:creditnoteTemplateId}</creditnoteTemplateId>
    <estimateTemplateId>{$ctx:estimateTemplateId}</estimateTemplateId>
    <invoiceTemplateId>{$ctx:invoiceTemplateId}</invoiceTemplateId>
    <vatRegNo>{$ctx:vatRegNo}</vatRegNo>
    <countryCode>{$ctx:countryCode}</countryCode>
    <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode>
    <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId>
    <vatTreatment>{$ctx:vatTreatment}</vatTreatment>
    <avataxExemptNo>{$ctx:avataxExemptNo}</avataxExemptNo>
    <taxAuthorityId>{$ctx:taxAuthorityId}</taxAuthorityId>
    <taxId>{$ctx:taxId}</taxId>
    <taxIdValue>{$ctx:taxIdValue}</taxIdValue>
    <taxIdType>{$ctx:taxIdType}</taxIdType>
    <track1099>{$ctx:track1099}</track1099>
    <isPrimaryContact>{$ctx:isPrimaryContact}</isPrimaryContact>
    <email>{$ctx:email}</email>
    <contactPersons>{$ctx:contactPersons}</contactPersons>
    <shippingAddress>{$ctx:shippingAddress}</shippingAddress>
   	<billingAddress>{$ctx:billingAddress}</billingAddress>
    <customFields>{$ctx:customFields}</customFields>
    <website>{$ctx:website}</website>
    <companyName>{$ctx:companyName}</companyName>
    <contactName>{$ctx:contactName}</contactName>
    <isTaxable>{$ctx:isTaxable}</isTaxable>
    <defaultTemplates>{$ctx:defaultTemplates}</defaultTemplates>
    <notes>{$ctx:notes}</notes>
	<paymentTerms>{$ctx:paymentTerms}</paymentTerms>
    <paymentTermsLabel>{$ctx:paymentTermsLabel}</paymentTermsLabel>
	<currencyId>{$ctx:currencyId}</currencyId>
</zohobooks.createContact>

Properties

creditnoteEmailTemplateId: The default credit note e-mail template ID used for this contact while sending credit notes.
estimateEmailTemplateId: The default estimate e-mail template ID used for this contact while sending estimates.
invoiceEmailTemplateId: The default invoice e-mail template ID used for this contact while sending invoices.
creditnoteTemplateId: The default credit note template ID used for this contact while creating a credit note.
estimateTemplateId: The default estimate template ID used for this contact while creating an estimate.
invoiceTemplateId: The default invoice template ID used for this contact while creating an invoice.
vatRegNo: The VAT registration number of a contact with VAT treatment as "eu_vat_registered".
countryCode: For UK Edition: The two-letter country code of a contact with VAT treatment as "eu_vat_registered". For Avalara: Two letter country code for the customer country, if your customer is not in US.
avataxUseCode: Groups similar customers for exemption purposes. It is a custom value that links customers to a tax rule. Select from Avalara standard codes or enter a custom code.
taxExemptionId: The ID of the tax exemption (US Edition only).
vatTreatment: The VAT treatment of the contact. Allowed values: "uk", "eu_vat_not_registered", "eu_vat_registered" and "non_eu" (UK Edition only).
avataxExemptNo: The exemption certificate number of the customer (Avalara integration only).
taxAuthorityId: The ID of the tax authority. The tax authority depends on the location of the customer. For example, if the customer is located in NY, the tax authority is the NY tax authority (US Edition only).
taxId: The ID of the tax or tax group that can be collected from the contact. Tax can be given only if "is_taxable" is "true" (US Edition only).
taxIdValue: The tax ID of the contact. (This node is only available when the organization's country is U.S.A.)
taxIdType: The tax ID type of the contact; it can be SSN, ATIN, ITIN or EIN. (This node is only available when the organization's country is U.S.A.)
track1099: The Boolean value to track a contact for 1099 reporting. (This node is only available when the organization's country is U.S.A.)
isPrimaryContact: Marks the contact person as the primary contact. The allowed value is "true".
email: The e-mail address of the contact person.
contactPersons: The contact persons of a contact.
shippingAddress: The shipping address of the contact.
billingAddress: The billing address of the contact.
customFields: Custom fields of the contact.
website: The website of the contact.
companyName: The company name of the contact.
contactName: The display name of the contact.
isTaxable: The Boolean value to track the taxability of the customer (US Edition only).
defaultTemplates: The default templates for the contact.
notes: Notes to be added to the contact.
paymentTerms: Payment terms for a contact.
paymentTermsLabel: The payment terms label for a contact.
currencyId: The currency ID of a contact.

Sample request

Following is a sample REST/JSON request that can be handled by the createContact operation.

Sample Request for createContact

{
    "apiUrl": "https://books.zoho.com",
    "authToken": "594cb85213f98ce15dfa9fe92330658a",
    "organizationId": "46892166",
    "contactName": "Rohitha",
    "contactPersons": [
        {
            "salutation": "Mr.",
            "first_name": "Will",
            "last_name": "Smith",
            "email": "willsmith@bowmanfurniture.com",
            "phone": "+1-925-921-9201",
            "mobile": "+1-4054439562",
            "is_primary_contact": true
        },
        {
            "salutation": "Mr.",
            "first_name": "Peter",
            "last_name": "Parker",
            "email": "peterparker@bowmanfurniture.com",
            "phone": "+1-925-929-7211",
            "mobile": "+1-4054439760"
        }
    ],
    "taxIdValue": "119406000000049001",
    "isTaxable": true,
    "estimateEmailTemplateId": "119406000000017003",
    "invoiceEmailTemplateId": "119406000000035014",
    "estimateTemplateId": "119406000000017003",
    "taxIdType": "SSN",
    "creditnoteEmailTemplateId": "119406000000017005",
    "vatTreatment": "234",
    "taxExemptionId": "234",
    "invoiceTemplateId": "119406000000035014",
    "avataxUseCode": "234",
    "defaultTemplates": {
        "invoice_template_id": "119406000000017001",
        "estimate_template_id": "119406000000035014",
        "creditnote_template_id": "119406000000035014",
        "invoice_email_template_id": "119406000000035014",
        "estimate_email_template_id": "119406000000035014",
        "creditnote_email_template_id": "119406000000035014"
    },
    "track1099": true,
    "shippingAddress": {
        "address": "Suite 125, McMillan Avenue",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94134",
        "country": "USA",
        "fax": "+1-925-924-9600"
    },
    "website": "www.virtusa.com",
    "customFields": [
        {
            "index": 1,
            "value": "GBGD078"
        },
        {
            "index": 2,
            "value": "F6JSD86KH7G"
        },
        {
            "index": 3,
            "value": "www.bowman.in"
        }
    ],
    "countryCode": "01",
    "companyName": "Virtusa",
    "creditnoteTemplateId": "119406000000035014",
    "isPrimaryContact": true,
    "avataxExemptNo": "3453",
    "taxId": "119406000000049001",
    "email": "rohitha@gmail.com",
    "vatRegNo": "1231",
    "billingAddress": {
        "address": "4900 Hopyard Rd, Suite 310",
        "city": "Pleasanton",
        "state": "CA",
        "zip": "94588",
        "country": "USA",
        "fax": "+1-925-924-9600"
    },
    "notes": "Payment option Through check",
    "taxAuthorityId": "435"
}

Retrieving details of a contact

The getContact operation retrieves details of a contact.

getContact

<zohobooks.getContact>
	<contactId>{$ctx:contactId}</contactId>
</zohobooks.getContact>

Properties

contactId: The ID of the contact to retrieve.

Sample request

Following is a sample REST/JSON request that can be handled by the getContact operation.

Sample Request for getContact

{
    "contactId": "",
    "authToken": "594cb85213f98ce15dfa9fe92330658a",
    "apiUrl": "https://books.zoho.com",
    "organizationId": "46892166"
}

Retrieving all contacts

The listContacts operation retrieves all contacts with pagination.

listContacts

 <zohobooks.listContacts>
    <page>{$ctx:page}</page>
    <perPage>{$ctx:perPage}</perPage>
    <appliedFilter>{$ctx:appliedFilter}</appliedFilter>
    <sortOrder>{$ctx:sortOrder}</sortOrder>
    <sortColumn>{$ctx:sortColumn}</sortColumn>
    <searchText>{$ctx:searchText}</searchText>
    <filterBy>{$ctx:filterBy}</filterBy>
    <phoneStartsWith>{$ctx:phoneStartsWith}</phoneStartsWith>
    <companyNameStartsWith>{$ctx:companyNameStartsWith}</companyNameStartsWith>
    <phone>{$ctx:phone}</phone>
    <firstNameContains>{$ctx:firstNameContains}</firstNameContains>
    <lastNameContains>{$ctx:lastNameContains}</lastNameContains>
    <emailContains>{$ctx:emailContains}</emailContains>
    <phoneContains>{$ctx:phoneContains}</phoneContains>
    <companyNameContains>{$ctx:companyNameContains}</companyNameContains>
    <contactNameStartsWith>{$ctx:contactNameStartsWith}</contactNameStartsWith>
    <contactNameContains>{$ctx:contactNameContains}</contactNameContains>
    <lastName>{$ctx:lastName}</lastName>
    <email>{$ctx:email}</email>
    <companyName>{$ctx:companyName}</companyName>
    <lastNameStartsWith>{$ctx:lastNameStartsWith}</lastNameStartsWith>
    <firstNameStartsWith>{$ctx:firstNameStartsWith}</firstNameStartsWith>
    <emailStartsWith>{$ctx:emailStartsWith}</emailStartsWith>
    <address>{$ctx:address}</address>
    <addressStartsWith>{$ctx:addressStartsWith}</addressStartsWith>
   	<addressContains>{$ctx:addressContains}</addressContains>
    <contactName>{$ctx:contactName}</contactName>
	<firstName>{$ctx:firstName}</firstName>
</zohobooks.listContacts>

Properties

page: The number of the page to be returned - pagination value.
perPage: Specifies how many entries should be returned in the response.
appliedFilter: Filters to be applied while querying.
sortOrder: The order of sorting - "ascending" or "descending".
sortColumn: Sort contacts. Allowed values: "contact_name", "first_name", "last_name", "email", "outstanding_receivable_amount", "outstanding_payable_amount", "created_time", and "last_modified_time".
searchText: Searches contacts by contact name or notes.
filterBy: Filters contacts by status. Allowed values: "Status.All", "Status.Active", "Status.Inactive", "Status.Duplicate", "Status.Customers", "Status.Vendors" and "Status".
phoneStartsWith: Searches contacts by the contact telephone number starting with this value.
companyNameStartsWith: Searches contacts by the company name starting with this value.
phone: Searches contacts by the telephone number of the contact person.
firstNameContains: Searches contacts by the first name of the contact person containing this value.
lastNameContains: Searches contacts by the last name of the contact person containing this value.
emailContains: Searches contacts by the e-mail of the contact person containing this value.
phoneContains: Searches contacts by the telephone number of the contact person containing this value.
companyNameContains: Searches contacts by the company name containing this value.
contactNameStartsWith: Searches contacts by the contact name starting with this value.
contactNameContains: Searches contacts by the company name containing this value.
lastName: Searches contacts by the last name of the contact person.
email: Searches contacts by the e-mail of the contact person.
companyName: Searches contacts by the company name.
lastNameStartsWith: Searches contacts by the contact's last name starting with this value.
firstNameStartsWith: Searches contacts by the contact's first name starting with this value.
emailStartsWith: Searches contacts by the contact's e-mail address starting with this value.
address: Searches contacts by any of the address fields.
addressStartsWith: Searches contacts by any of the address fields.
addressContains: Searches contacts by the address of the contact person containing this value.
contactName: Searches contacts by the contact name.
firstName: Searches contacts by the first name of the contact person.

Sample request

Following is a sample REST/JSON request that can be handled by the listContacts operation.

Sample Request for listContacts

{
    "lastName": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    },
    "phone": {
        "equals": "",
        "contains": ""
    },
    "authToken": "594cb85213f98ce15dfa9fe92330658a",
    "organizationId": "46892166",
    "companyName": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    },
    "phoneStartsWith": "",
    "sortColumn": "contact_name",
    "perPage": 20,
    "page": 1,
    "appliedFilter": "",
    "sortOrder": "D",
    "address": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    },
    "email": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    },
    "contactName": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    },
    "apiUrl": "https://books.zoho.com",
    "searchText": "",
    "filterBy": "Status.All",
    "firstName": {
        "startsWith": "",
        "equals": "",
        "contains": ""
    }
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to Zoho Books with the init operation and use the createContact operation. The sample request for this proxy can be found in the createContact sample request. You can use this sample as a template for using other operations in this category.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="zohobooks_createContact" startOnLoad="true" statistics="disable" trace="disable" transports="https,http" xmlns="http://ws.apache.org/ns/synapse">
   <target>
      <inSequence>
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="authToken" expression="json-eval($.authToken)"/>
         <property name="organizationId" expression="json-eval($.organizationId)"/>
         <property name="creditnoteEmailTemplateId" expression="json-eval($.creditnoteEmailTemplateId)"/>
         <property name="estimateEmailTemplateId" expression="json-eval($.estimateEmailTemplateId)"/>
         <property name="invoiceEmailTemplateId" expression="json-eval($.invoiceEmailTemplateId)"/>
         <property name="creditnoteTemplateId" expression="json-eval($.creditnoteTemplateId)"/>
         <property name="estimateTemplateId" expression="json-eval($.estimateTemplateId)"/>
         <property name="invoiceTemplateId" expression="json-eval($.invoiceTemplateId)"/>
         <property name="vatRegNo" expression="json-eval($.vatRegNo)"/>
         <property name="countryCode" expression="json-eval($.countryCode)"/>
         <property name="avataxUseCode" expression="json-eval($.avataxUseCode)"/>
         <property name="taxExemptionId" expression="json-eval($.taxExemptionId)"/>
         <property name="vatTreatment" expression="json-eval($.vatTreatment)"/>
         <property name="avataxExemptNo" expression="json-eval($.avataxExemptNo)"/>
         <property name="taxAuthorityId" expression="json-eval($.taxAuthorityId)"/>
         <property name="taxId" expression="json-eval($.taxId)"/>
         <property name="taxIdValue" expression="json-eval($.taxIdValue)"/>
         <property name="taxIdType" expression="json-eval($.taxIdType)"/>
         <property name="track1099" expression="json-eval($.track1099)"/>
         <property name="isPrimaryContact" expression="json-eval($.isPrimaryContact)"/>
         <property name="email" expression="json-eval($.email)"/>
         <property name="contactPersons" expression="json-eval($.contactPersons)"/>
         <property name="shippingAddress" expression="json-eval($.shippingAddress)"/>
         <property name="billingAddress" expression="json-eval($.billingAddress)"/>
         <property name="customFields" expression="json-eval($.customFields)"/>
         <property name="website" expression="json-eval($.website)"/>
         <property name="companyName" expression="json-eval($.companyName)"/>
         <property name="contactName" expression="json-eval($.contactName)"/>
         <property name="isTaxable" expression="json-eval($.isTaxable)"/>
         <property name="defaultTemplates" expression="json-eval($.defaultTemplates)"/>
         <property name="notes" expression="json-eval($.notes)"/>
		 <property name="paymentTerms" expression="json-eval($.paymentTerms)"/>
         <property name="paymentTermsLabel" expression="json-eval($.paymentTermsLabel)"/>
         <property name="currencyId" expression="json-eval($.currencyId)"/>
         <zohobooks.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <authToken>{$ctx:authToken}</authToken>
            <organizationId>{$ctx:organizationId}</organizationId>
         </zohobooks.init>
         <zohobooks.createContact>
            <creditnoteEmailTemplateId>{$ctx:creditnoteEmailTemplateId}</creditnoteEmailTemplateId>
            <estimateEmailTemplateId>{$ctx:estimateEmailTemplateId}</estimateEmailTemplateId>
            <invoiceEmailTemplateId>{$ctx:invoiceEmailTemplateId}</invoiceEmailTemplateId>
            <creditnoteTemplateId>{$ctx:creditnoteTemplateId}</creditnoteTemplateId>
            <estimateTemplateId>{$ctx:estimateTemplateId}</estimateTemplateId>
            <invoiceTemplateId>{$ctx:invoiceTemplateId}</invoiceTemplateId>
            <vatRegNo>{$ctx:vatRegNo}</vatRegNo>
            <countryCode>{$ctx:countryCode}</countryCode>
            <avataxUseCode>{$ctx:avataxUseCode}</avataxUseCode>
            <taxExemptionId>{$ctx:taxExemptionId}</taxExemptionId>
            <vatTreatment>{$ctx:vatTreatment}</vatTreatment>
            <avataxExemptNo>{$ctx:avataxExemptNo}</avataxExemptNo>
            <taxAuthorityId>{$ctx:taxAuthorityId}</taxAuthorityId>
            <taxId>{$ctx:taxId}</taxId>
            <taxIdValue>{$ctx:taxIdValue}</taxIdValue>
            <taxIdType>{$ctx:taxIdType}</taxIdType>
            <track1099>{$ctx:track1099}</track1099>
            <isPrimaryContact>{$ctx:isPrimaryContact}</isPrimaryContact>
            <email>{$ctx:email}</email>
            <contactPersons>{$ctx:contactPersons}</contactPersons>
            <shippingAddress>{$ctx:shippingAddress}</shippingAddress>
            <billingAddress>{$ctx:billingAddress}</billingAddress>
            <customFields>{$ctx:customFields}</customFields>
            <website>{$ctx:website}</website>
            <companyName>{$ctx:companyName}</companyName>
            <contactName>{$ctx:contactName}</contactName>
            <isTaxable>{$ctx:isTaxable}</isTaxable>
            <defaultTemplates>{$ctx:defaultTemplates}</defaultTemplates>
            <notes>{$ctx:notes}</notes>
	    <paymentTerms>{$ctx:paymentTerms}</paymentTerms>
            <paymentTermsLabel>{$ctx:paymentTermsLabel}</paymentTermsLabel>
            <currencyId>{$ctx:currencyId}</currencyId>
         </zohobooks.createContact>
         <respond/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

WSO2 ESB Connectors Documentation

Working with Contacts in Zoho Books

Overview

Operation details

Creating a contact

Properties

Sample request

Related Zoho Books documentation

Retrieving details of a contact

Properties

Sample request

Related Zoho Books documentation

Retrieving all contacts

Properties

Sample request

Related Zoho Books documentation

Sample configuration