openapi: 3.0.0
info:
title: batches contacts API
description: Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.
contact: {}
version: 1.0.0
servers:
- url: https://www.zohoapis.com/inventory/v1
description: API Endpoint
tags:
- name: contacts
description: Contacts Module
paths:
/contacts:
x-mcp-group:
- Contacts
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- contacts
operationId: create_contact
summary: Create a Contact
description: Create a contact with given information.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-contact-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-contact-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.CREATE
get:
tags:
- contacts
operationId: list_contacts
summary: List contacts
description: List all contacts with pagination.
parameters:
- name: contact_name
in: query
description: 'Search contacts by contact name. Maximum length [100] Variants: <code>contact_name_startswith</code> and <code>contact_name_contains</code>. Maximum length [100]'
required: false
schema:
type: string
example: Bowman and Co
- name: company_name
in: query
description: 'Search contacts by company name. Maximum length [100] Variants: <code>company_name_startswith</code> and <code>company_name_contains</code>'
required: false
schema:
type: string
example: Bowman and Co
- name: first_name
in: query
description: 'Search contacts by first name of the contact person. Maximum length [100] Variants: <code>first_name_startswith</code> and <code>first_name_contains</code>'
required: false
schema:
type: string
example: Will
- name: last_name
in: query
description: 'Search contacts by last name of the contact person. Maximum length [100] Variants: <code>last_name_startswith</code> and <code>last_name_contains</code>'
required: false
schema:
type: string
example: Smith
- name: address
in: query
description: 'Search contacts by any of the address fields. Maximum length [100] Variants: <code>address_startswith</code> and <code>address_contains</code>'
required: false
schema:
type: string
example: 4900 Hopyard Rd
- name: email
in: query
description: 'Search contacts by email of the contact person. Maximum length [100] Variants: <code>email_startswith</code> and <code>email_contains</code>'
required: false
schema:
type: string
example: willsmith@bowmanfurniture.com
- name: phone
in: query
description: 'Search contacts by phone number of the contact person. Maximum length [100] Variants: <code>phone_startswith</code> and <code>phone_contains</code>'
required: false
schema:
type: string
example: +1-925-921-9201
- name: filter_by
in: query
description: 'Filter contacts by status. Allowed Values: <code>Status.All, Status.Active, Status.Inactive, Status.Duplicate and Status.Crm</code>'
required: false
schema:
type: string
example: ''
- name: search_text
in: query
description: Search contacts by contact name or notes. Maximum length [100]
required: false
schema:
type: string
example: ''
- name: sort_column
in: query
description: 'Sort contacts. Allowed Values: <code>contact_name, first_name, last_name, email, outstanding_receivable_amount, created_time and last_modified_time</code>'
required: false
schema:
type: string
example: contact_name
- name: page
in: query
description: Page number to be fetched. Default value is 1.
required: false
schema:
type: integer
default: 1
example: 1
- name: per_page
in: query
description: Number of records to be fetched per page. Default value is 200.
required: false
schema:
type: integer
default: 200
example: 200
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-contacts-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.READ
/contacts/{contact_id}:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
schema:
type: string
required: true
description: Unique identifier of the contact.
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
put:
tags:
- contacts
operationId: update_contact
summary: Update a contact
description: Update an existing contact. To delete a contact person remove it from the contact_persons list.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-contact-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-contact-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.UPDATE
get:
tags:
- contacts
operationId: get_contact
summary: Get contact
description: Get details of a contact.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-contact-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.READ
delete:
tags:
- contacts
operationId: delete_contact
summary: Delete a contact
description: Delete an existing contact.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-contact-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.DELETE
/contacts/{contact_id}/address:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
schema:
type: string
required: true
description: Unique identifier of the contact.
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
get:
tags:
- contacts
operationId: get_contact_address
summary: Get contact address
description: Get the billing and shipping address of an existing contact
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-contact-address-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.READ
/contacts/{contact_id}/active:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
required: true
description: Unique identifier of the contact.
schema:
type: string
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
post:
tags:
- contacts
operationId: mark_contact_as_active
summary: Mark as active
description: Mark a contact as active.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-active-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.CREATE
/contacts/{contact_id}/inactive:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
required: true
description: Unique identifier of the contact.
schema:
type: string
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
post:
tags:
- contacts
operationId: mark_contact_as_inactive
summary: Mark as Inactive
description: Mark a contact as inactive.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mark-as-inactive-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.CREATE
/contacts/{contact_id}/statements/email:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
required: true
description: Unique identifier of the contact.
schema:
type: string
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
post:
tags:
- contacts
operationId: email_statement
summary: Email statement
description: Email statement to the contact. If JSONString is not inputted, mail will be sent with the default mail content.
parameters:
- name: start_date
in: query
description: If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
required: false
schema:
type: string
example: ''
- name: end_date
in: query
description: End date for the statement. Date format [yyyy-mm-dd]
required: false
schema:
type: string
example: ''
- name: multipart_or_formdata
in: query
description: Files to be attached along with the statement.
required: false
schema:
type: string
example: file
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/email-statement-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/email-statement-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.CREATE
get:
tags:
- contacts
operationId: get_statement_mail_content
summary: Get Statement mail content
description: Get the mail content of a contacts billing statement.
parameters:
- name: start_date
in: query
description: If start_date and end_date are not given, current month's statement will be sent to contact. Date format [yyyy-mm-dd]
required: false
schema:
type: string
example: ''
- name: end_date
in: query
description: End date for the statement. Date format [yyyy-mm-dd]
required: false
schema:
type: string
example: ''
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/get-statement-mail-content-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.READ
/contacts/{contact_id}/email:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
required: true
description: Unique identifier of the contact.
schema:
type: string
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
post:
tags:
- contacts
operationId: email_contact
summary: Email contact
description: Send email to contact.
parameters:
- name: send_customer_statement
in: query
description: Send customer statement pdf with email.
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/email-contact-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/email-contact-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.CREATE
/contacts/{contact_id}/comments:
x-mcp-group:
- Contacts
parameters:
- name: contact_id
in: path
required: true
description: Unique identifier of the contact.
schema:
type: string
example: 460000000026049
- $ref: '#/components/parameters/organization_id'
get:
tags:
- contacts
operationId: list_contact_comments
summary: List Comments
description: List recent activities of a contact.
parameters:
- name: page
in: query
description: Page number to be fetched. Default value is 1.
required: false
schema:
type: integer
default: 1
example: 1
- name: per_page
in: query
description: Number of records to be fetched per page. Default value is 200.
required: false
schema:
type: integer
default: 200
example: 200
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-comments-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.contacts.READ
components:
schemas:
estimate_email_template_id:
description: ID of the estimate email template used
type: string
example: 460000000052073
transaction_id:
description: The ID of the transaction made
type: string
example: 460000000053123
email-statement-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Statement has been sent to the customer.
readOnly: true
unused_credits_receivable_amount_bcy:
description: receivable unused credits in base currency
type: integer
example: 1369.66
outstanding_receivable_amount_bcy:
description: outstanding receivable in base currency
type: integer
example: 250
is_primary_contact:
description: To mark contact person as primary for contact. Allowed value is true only.
type: boolean
example: true
zip:
description: Zip code of the customer's billing address.
type: string
example: 94588
mark-as-active-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The contact has been marked as active.
readOnly: true
user_name:
description: The appropriate user name who is sending the email
type: string
example: John Smith
get-contact-address-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
addresses:
type: array
items:
type: object
properties:
address_id:
$ref: '#/components/schemas/address_id'
attention:
$ref: '#/components/schemas/attention'
address:
$ref: '#/components/schemas/address'
street2:
$ref: '#/components/schemas/street2'
city:
$ref: '#/components/schemas/city'
state:
$ref: '#/components/schemas/state'
state_code:
$ref: '#/components/schemas/state_code'
zip:
$ref: '#/components/schemas/zip'
country:
$ref: '#/components/schemas/country'
country_code:
$ref: '#/components/schemas/country_code'
phone:
$ref: '#/components/schemas/phone'
fax:
$ref: '#/components/schemas/fax'
avatax_exempt_no:
description: Exemption certificate number of the customer.
type: string
x-node_available_in:
- Avalara Integration
x-node_unavailable_in: []
is_sms_enabled:
description: Used to check if SMS communication preference is enabled for the contact person.
type: boolean
example: true
x-node_available_in:
- SMS integration
date:
description: Date when the credit note was created
type: string
example: '2013-11-19'
custom_fields:
description: Custom fields or Additional of the contact which we can create to add more information.
type: array
items:
type: object
properties:
value:
$ref: '#/components/schemas/value'
index:
$ref: '#/components/schemas/index'
label:
$ref: '#/components/schemas/label'
creditnote_template_name:
description: Name of the credit note template used
type: string
example: Fixed Cost - Professional
contact_comments:
description: Comments added by a contact
type: array
items:
type: object
properties:
comment_id:
$ref: '#/components/schemas/comment_id'
contact_id:
$ref: '#/components/schemas/contact_id'
contact_name:
$ref: '#/components/schemas/contact_name'
description:
$ref: '#/components/schemas/description'
commented_by_id:
$ref: '#/components/schemas/commented_by_id'
commented_by:
$ref: '#/components/schemas/commented_by'
date:
$ref: '#/components/schemas/date'
date_description:
$ref: '#/components/schemas/date_description'
time:
$ref: '#/components/schemas/time'
transaction_id:
$ref: '#/components/schemas/transaction_id'
transaction_type:
$ref: '#/components/schemas/transaction_type'
is_entity_deleted:
$ref: '#/components/schemas/is_entity_deleted'
operation_type:
$ref: '#/components/schemas/operation_type'
list-contacts-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
contacts:
type: array
items:
type: object
properties:
contact_id:
$ref: '#/components/schemas/contact_id'
contact_name:
$ref: '#/components/schemas/contact_name'
company_name:
$ref: '#/components/schemas/company_name'
contact_type:
$ref: '#/components/schemas/contact_type'
status:
$ref: '#/components/schemas/status'
payment_terms:
$ref: '#/components/schemas/payment_terms'
payment_terms_label:
$ref: '#/components/schemas/payment_terms_label'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
outstanding_receivable_amount:
$ref: '#/components/schemas/outstanding_receivable_amount'
unused_credits_receivable_amount:
$ref: '#/components/schemas/unused_credits_receivable_amount'
first_name:
$ref: '#/components/schemas/first_name'
last_name:
$ref: '#/components/schemas/last_name'
email:
$ref: '#/components/schemas/email'
phone:
$ref: '#/components/schemas/phone'
mobile:
$ref: '#/components/schemas/mobile'
created_time:
$ref: '#/components/schemas/created_time'
last_modified_time:
$ref: '#/components/schemas/last_modified_time'
value:
description: Value of the custom field.
type: string
example: GBGD078
to_mail_ids:
description: Array of email addresses of the recipients.
type: array
items:
type: string
example:
- willsmith@bowmanfurniture.com
currency_symbol:
description: Symbol of the currency of the contact_type
type: string
example: $
language_code:
description: language of a contact. allowed values <code>de,en,es,fr,it,ja,nl,pt,sv,zh</code>
type: string
example: en
to_contacts:
description: Recepients of the mail
type: array
items:
type: object
properties:
first_name:
$ref: '#/components/schemas/first_name'
selected:
$ref: '#/components/schemas/selected'
phone:
$ref: '#/components/schemas/phone'
email:
$ref: '#/components/schemas/email'
contact_person_id:
$ref: '#/components/schemas/contact_person_id'
last_name:
$ref: '#/components/schemas/last_name'
salutation:
$ref: '#/components/schemas/salutation'
mobile:
$ref: '#/components/schemas/mobile'
list-comments-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
contact_comments:
$ref: '#/components/schemas/contact_comments'
payment_terms:
description: Net payment term for the customer.
type: integer
example: 15
body:
description: Body/content of the email to be sent. Maximum length [5000]
type: string
example: Dear Customer, <br/>We have attached with this email a list of all your transactions with us for the period 01 Sep 2013 to 30 Sep 2013. You can write to us or call us if you need any assistance or clarifications. <br/>Thanks for your business.<br/>Regards<br/>Zillium Inc
tax_regime:
description: 'Tax Regime of the contact.Allowed Values: <code>general_legal_person</code>, <code>legal_entities_non_profit</code>, <code>resident_abroad</code>, <code>production_cooperative_societies</code>, <code>agricultural_livestock</code>, <code>optional_group_of_companies</code>, <code>coordinated</code>, <code>simplified_trust</code>, <code>wages_salaries_income</code>, <code>lease</code>, <code>property_disposal_acquisition</code>, <code>other_income</code>, <code>resident_abroad</code>, <code>divident_income</code>, <code>individual_business_professional</code>, <code>interest_income</code>, <code>income_obtaining_price</code>, <code>no_tax_obligation</code>, <code>tax_incorporation</code>, <code>income_through_technology_platform</code>, <code>simplified_trust</code>.'
type: string
example: general_legal_person
x-node_available_in:
- mx
x-node_unavailable_in: []
update-a-contact-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Contact has been updated successfully
readOnly: true
contact:
type: object
properties:
contact_id:
$ref: '#/components/schemas/contact_id'
contact_name:
$ref: '#/components/schemas/contact_name'
company_name:
$ref: '#/components/schemas/company_name'
has_transaction:
$ref: '#/components/schemas/has_transaction'
contact_type:
$ref: '#/components/schemas/contact_type'
is_linked_with_zohocrm:
$ref: '#/components/schemas/is_linked_with_zohocrm'
website:
$ref: '#/components/schemas/website'
primary_contact_id:
$ref: '#/components/schemas/primary_contact_id'
payment_terms:
$ref: '#/components/schemas/payment_terms'
payment_terms_label:
$ref: '#/components/schemas/payment_terms_label'
opening_balances:
$ref: '#/components/schemas/opening_balances'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
language_code:
$ref: '#/components/schemas/language_code'
outstanding_receivable_amount:
$ref: '#/components/schemas/outstanding_receivable_amount'
outstanding_receivable_amount_bcy:
$ref: '#/components/schemas/outstanding_receivable_amount_bcy'
unused_credits_receivable_amount:
$ref: '#/components/schemas/unused_credits_receivable_amount'
unused_credits_receivable_amount_bcy:
$ref: '#/components/schemas/unused_credits_receivable_amount_bcy'
status:
$ref: '#/components/schemas/status'
payment_reminder_enabled:
$ref: '#/components/schemas/payment_reminder_enabled'
custom_fields:
$ref: '#/components/schemas/custom_fields'
billing_address:
$ref: '#/components/schemas/billing_address'
shipping_address:
$ref: '#/components/schemas/shipping_address'
facebook:
$ref: '#/components/schemas/facebook'
twitter:
$ref: '#/components/schemas/twitter'
contact_persons:
$ref: '#/components/schemas/contact_persons'
default_templates:
$ref: '#/components/schemas/default_templates'
notes:
$ref: '#/components/schemas/notes'
created_time:
$ref: '#/components/schemas/created_time'
last_modified_time:
$ref: '#/components/schemas/last_modified_time'
is_taxable:
$ref: '#/components/schemas/is_taxable'
tax_id:
$ref: '#/components/schemas/tax_id'
tax_name:
$ref: '#/components/schemas/tax_name'
tax_percentage:
$ref: '#/components/schemas/tax_percentage'
tax_authority_id:
$ref: '#/components/schemas/tax_authority_id'
tax_exemption_id:
$ref: '#/components/schemas/tax_exemption_id'
tax_authority_name:
$ref: '#/components/schemas/tax_authority_name'
tax_exemption_code:
$ref: '#/components/schemas/tax_exemption_code'
place_of_contact:
$ref: '#/components/schemas/place_of_contact'
gst_no:
$ref: '#/components/schemas/gst_no'
tax_treatment:
$ref: '#/components/schemas/tax_treatment'
tax_regime:
$ref: '#/components/schemas/tax_regime'
legal_name:
$ref: '#/components/schemas/legal_name'
is_tds_registered:
$ref: '#/components/schemas/is_tds_registered'
vat_treatment:
$ref: '#/components/schemas/vat_treatment'
gst_treatment:
$ref: '#/components/schemas/gst_treatment'
email-contact-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Email has been sent.
readOnly: true
mark-as-inactive-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The contact has been marked as inactive.
readOnly: true
email-statement-request:
required:
- to_mail_ids
- subject
- body
type: object
properties:
send_from_org_email_id:
$ref: '#/components/schemas/send_from_org_email_id'
to_mail_ids:
$ref: '#/components/schemas/to_mail_ids'
cc_mail_ids:
$ref: '#/components/schemas/cc_mail_ids'
subject:
$ref: '#/components/schemas/subject'
body:
$ref: '#/components/schemas/body'
attachments:
description: Files to be attached to the email. It has to be sent in multipart/formdata
type: string
format: binary
country:
description: Country of the customer's billing address.
type: string
example: U.S.A
vat_treatment:
description: 'VAT treatment of the contact.Allowed Values: <br/><code>uk</code> (A business that is located in the UK.),<br/><code>eu_vat_registered</code> (A business that is reg for VAT and trade goods between Northern Ireland and EU. This node is available only for organizations enabled for NI protocal in VAT Settings.) and<br/><code>overseas</code> (A business that is located outside UK. Pre Brexit, this was split as <code>eu_vat_registered</code>, <code>eu_vat_not_registered</code> and <code>non_eu</code> ).'
type: string
x-node_available_in:
- uk
x-node_unavailable_in: []
tax_reg_no:
description: '12 digit Tax Registration number of a contact with Tax treatment as </br> <code>home_country_mexico</code>, <code>border_region_mexico</code>, <code>non_mexico</code>.</br> Consumers generic RFC: <code>XAXX010101000</code>, Overseas generic RFC: <code>XEXX010101000</code>'
type: string
example: 12345678912345
x-node_available_in:
- mx
x-node_unavailable_in: []
cc_mail_ids:
description: Array of email addresses of the recipients to be CC'd.
type: array
items:
type: string
example:
- peterparker@bowmanfurniture.com
status:
description: The status of the contact.
type: string
example: active
label:
description: Label of the custom field.
type: string
example: VAT ID
phone:
description: 'Search contacts by phone number of the contact person. Variants: <code>phone_startswith</code> and <code>phone_contains</code>'
type: string
example: +1-925-921-9201
payment_terms_label:
description: Label for the paymet due details.
type: string
example: Net 15
transaction_type:
description: The type of the trasnaction made
type: string
example: customer_payment
contact_id:
description: Contact ID of the contact
type: string
example: 460000000026049
attention:
description: Intended recipient at given address
type: string
example: Mr.John
contact-response:
type: object
properties:
contact_id:
$ref: '#/components/schemas/contact_id'
contact_name:
$ref: '#/components/schemas/contact_name'
company_name:
$ref: '#/components/schemas/company_name'
has_transaction:
$ref: '#/components/schemas/has_transaction'
contact_type:
$ref: '#/components/schemas/contact_type'
is_linked_with_zohocrm:
$ref: '#/components/schemas/is_linked_with_zohocrm'
website:
$ref: '#/components/schemas/website'
pr
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-inventory/refs/heads/main/openapi/zoho-inventory-contacts-api-openapi.yml