openapi: 3.0.0
info:
  title: 'ZOHO CRM Integration'
  description: 'API handling for modules specific to  Zoho Books - Zoho CRM integration.'
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://www.zohoapis.com/books/v3'
    description: 'API Endpoint'
tags:
  -
    name: integration
    description: 'integration Module'
paths:
  '/crm/account/{crm_account_id}/import':
    post:
      tags:
        - integration
      summary: 'Import a customer using the CRM account ID'
      description: 'Zoho Books must be integrated with Zoho CRM using Accounts and Contacts sync or using Accounts only sync to import a customer from CRM with its CRM account ID. <br> Note: You can get a contact by CRM account ID by using this <a href=/books/api/v3/contacts/#list-contacts/zcrm_account_id>API Endpoint</a>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/import-a-customer-using-the-crm-account-id-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.CREATE
    parameters:
      -
        name: crm_account_id
        in: path
        required: true
        schema:
          type: string
        example: ""
      -
        $ref: '#/components/parameters/organization_id'
  '/crm/contact/{crm_contact_id}/import':
    post:
      tags:
        - integration
      summary: 'Import a customer using CRM contact ID'
      description: 'Zoho Books must be integrated with Zoho CRM using Contacts only sync to import a customer from CRM with its CRM contact ID. <br> Note: You can get a contact by CRM contact ID by using this <a href=/books/api/v3/contacts/#list-contacts/zcrm_contact_id>API Endpoint</a>'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/import-a-customer-using-crm-contact-id-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.CREATE
    parameters:
      -
        name: crm_contact_id
        in: path
        required: true
        schema:
          type: string
        example: ""
      -
        $ref: '#/components/parameters/organization_id'
  '/crm/vendor/{crm_vendor_id}/import':
    post:
      tags:
        - integration
      summary: 'Import a vendor using the CRM vendor ID'
      description: 'Zoho Books must be integrated with Zoho CRM using Vendor only sync to import a vendor from CRM with its CRM vendor ID.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/import-a-vendor-using-the-crm-vendor-id-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.CREATE
    parameters:
      -
        name: crm_vendor_id
        in: path
        required: true
        schema:
          type: string
        example: ""
      -
        $ref: '#/components/parameters/organization_id'
components:
  parameters:
    organization_id:
      name: organization_id
      description: 'ID of the organization'
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/data'
    contact_id:
      description: 'Contact ID of the contact'
      type: string
      example: 460000000026049
    estimate_id:
      description: 'The  unique id of a particular estimate'
      type: string
      example: 982000000567011
    data:
      type: object
      properties:
        contact_id:
          $ref: '#/components/schemas/contact_id'
    contact_type:
      description: 'Type of the contact. Whether he is a customer or vendor'
      type: string
      example: customer
    status:
      description: 'The status of the contact.'
      type: string
      example: active
    contact_name:
      description: 'Name of the contact. This can be the name of an organisation or the name of an individual. <code>Maximum length [200]</code>'
      type: string
      example: 'Bowman and Co'
    company_name:
      description: 'Name of the conact''s company. <code>Maximum length [200]</code>'
      type: string
      example: 'Bowman and Co'
    email:
      description: 'The Email ID of the contact person.'
      type: string
      example: willsmith@bowmanfurniture.com
    phone:
      description: 'Phone number of the contact person.'
      type: string
      example: +1-925-921-9201
    payment_terms:
      description: 'Net payment term for the customer.'
      type: integer
      example: 15
    payment_terms_label:
      description: 'Label for the paymet due details.'
      type: string
      example: 'Net 15'
    currency_id:
      description: 'Currency ID of the customer''s currency.'
      type: string
      example: 460000000000097
    selected:
      description: 'Boolean to check for selection'
      type: boolean
      example: true
    currency_code:
      description: 'Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing. currency_id and currency_symbol are set automatically in accordance to the currency_code.'
      type: string
      example: USD
    outstanding_receivable_amount:
      description: 'Outsatnding amount with the contact, which is due for receipt'
      type: integer
      example: 250
    unused_credits_receivable_amount:
      description: 'Our Unused credits with the vendor which is receivable'
      type: integer
      example: 1369.66
    first_name:
      description: 'First name of the contact. <code>Maximum length [100]</code>'
      type: string
      example: Will
    last_name:
      description: 'Last name of the contact. <code>Maximum length [100]</code>'
      type: string
      example: Smith
    mobile:
      description: 'Mobile number of the contact person.'
      type: string
      example: +1-4054439562
    created_time:
      description: 'Time at which the contact was created.'
      type: string
      example: '2013-10-07T12:06:10+0530'
    last_modified_time:
      description: 'Time at which the contact was last modified'
      type: string
      example: '2013-11-08T18:24:51+0530'
    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'
    index:
      description: 'Index of the custom field. It can hold any value from 1 to 10.'
      type: integer
      example: 1
    label:
      description: 'Label of the custom field.'
      type: string
      example: 'VAT ID'
    value:
      description: 'Value of the custom field.'
      type: string
      example: GBGD078
    website:
      description: 'Website of the contact.'
      type: string
      example: www.bowmanfurniture.com
    facebook:
      description: 'Facebook profile account of the contact. <code>Maximum length [100]</code>'
      type: string
      example: zoho
    twitter:
      description: 'Twitter account of the contact. <code>Maximum length [100]</code>'
      type: string
      example: zoho
    is_linked_with_zohocrm:
      description: 'To check if the customer account is linked to the crm'
      type: boolean
      example: false
    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
    gst_treatment:
      description: 'Choose whether the contact is GST registered/unregistered/consumer/overseas. Allowed values are <code> business_gst </code> , <code> business_none </code> , <code> overseas </code> , <code> consumer </code>.'
      type: string
      example: business_gst
      x-node_available_in:
        - in
      x-node_unavailable_in: []
    gst_no:
      description: '15 digit GST identification number of the customer/vendor.'
      type: string
      example: 22AAAAA0000A1Z5
      x-node_available_in:
        - in
      x-node_unavailable_in: []
    place_of_contact:
      description: 'Location of the contact. (This node identifies the place of supply and source of supply when invoices/bills are raised for the customer/vendor respectively. This is not applicable for Overseas contacts)'
      type: string
      example: TN
      x-node_available_in:
        - in
      x-node_unavailable_in: []
    zcrm_account_id:
      description: 'CRM Account ID for the contact.'
      type: string
      example: 460000000026049
    zcrm_contact_id:
      description: 'CRM Contact ID for the contact.'
      type: string
      example: 460000000026049
    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'
        contact_type:
          $ref: '#/components/schemas/contact_type'
        language_code:
          $ref: '#/components/schemas/language_code'
        status:
          $ref: '#/components/schemas/status'
        payment_terms:
          $ref: '#/components/schemas/payment_terms'
        payment_terms_label:
          $ref: '#/components/schemas/payment_terms_label'
        gst_treatment:
          $ref: '#/components/schemas/gst_treatment'
        gst_no:
          $ref: '#/components/schemas/gst_no'
        is_linked_with_zohocrm:
          $ref: '#/components/schemas/is_linked_with_zohocrm'
        website:
          $ref: '#/components/schemas/website'
        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'
        facebook:
          $ref: '#/components/schemas/facebook'
        twitter:
          $ref: '#/components/schemas/twitter'
        place_of_contact:
          $ref: '#/components/schemas/place_of_contact'
        created_time:
          $ref: '#/components/schemas/created_time'
        last_modified_time:
          $ref: '#/components/schemas/last_modified_time'
    invoice_id:
      description: 'The id of the invoice'
      type: string
      example: 982000000567114
    ach_payment_initiated:
      type: boolean
      example: false
    customer_name:
      description: 'The name of the customer. Max-length [100]'
      type: string
      example: 'Bowman & Co'
    customer_id:
      description: 'ID of the customer the invoice has to be created.'
      type: string
      example: 982000000567001
    date:
      description: 'Search invoices by invoice date. Default date format is yyyy-mm-dd.<code> Variants: due_date_start, due_date_end, due_date_before and due_date_after</code>.'
      type: string
      example: '2013-11-17'
    due_date:
      description: 'Search invoices by due date. Default date format is yyyy-mm-dd. <code> Variants: due_date_start, due_date_end, due_date_before and due_date_after </code>'
      type: string
      example: '2013-12-03'
    due_days:
      description: 'Specifies the number of day in which the invoice would become overdue'
      type: string
      example: 'Due in 14 day(s)'
    schedule_time:
      type: string
      example: ""
    is_viewed_by_client:
      type: boolean
      example: false
    has_attachment:
      type: boolean
      example: false
    client_viewed_time:
      type: string
      example: ""
    balance:
      description: 'The unpaid amount'
      type: string
      example: 40.6
    is_emailed:
      description: 'Boolean check to if the email was sent'
      type: string
      example: false
    total:
      description: 'The total amount to be paid'
      type: string
      example: 40.6
    reminders_sent:
      description: 'The no of reminders sent'
      type: integer
      example: 1
    last_reminder_sent_date:
      description: 'The date the last email was sent'
      type: string
      example: ' '
    payment_expected_date:
      description: 'The expected date of payment'
      type: string
      example: ' '
    last_payment_date:
      description: 'The last payment date of the invoice'
      type: string
      example: ' '
    documents:
      type: string
      example: ""
    salesperson_id:
      type: string
      example: ' '
    salesperson_name:
      description: 'Name of the salesperson. Max-length [200]'
      type: string
      example: ' '
    shipping_charge:
      description: 'Shipping charges applied to the invoice. Max-length [100]'
      type: string
      example: 0
    adjustment:
      description: 'Adjustments made to the invoice.'
      type: number
      format: double
      example: 0
    write_off_amount:
      description: 'The write off amount'
      type: number
      format: float
      example: 0
    invoice_number:
      description: 'Search invoices by invoice number. Variants: <code>invoice_number_startswith</code> and <code>invoice_number_contains</code>. Max-length [100]'
      type: string
      example: INV-00003
    salesorder_id:
      description: 'ID of the Sales Order'
      type: string
      example: '460000000039129'
    reference_number:
      description: 'The reference number of the invoice'
      type: string
      example: ' '
    applied_filter:
      description: 'The filer applied for sorting'
      type: string
      example: Status.All
    page:
      description: 'Number of pages'
      type: integer
      example: 1
    per_page:
      description: 'Per page values'
      type: integer
      example: 200
    report_name:
      description: 'The report name'
      type: string
      example: Invoices
    has_more_page:
      description: 'Check if has more pages'
      type: boolean
      example: false
    sort_order:
      description: 'The order for sorting'
      type: string
      example: D
    sort_column:
      description: 'Sort invoices.Allowed Values: <code>customer_name</code>, <code>invoice_number</code>, <code>date</code>, <code> due_date</code>, <code>total</code>, <code>balance</code> and  <code>created_time</code>'
      type: string
      example: created_time
    exchange_rate:
      description: 'Exchange rate of the currency.'
      type: number
      format: float
      example: 1
    estimate_number:
      description: 'Search estimates by estimate number.Variants<code>estimate_number_startswith</code> and <code>estimate_number_contains</code>'
      type: string
      example: EST-00002
    accepted_date:
      description: 'The date of acceptance of the estimates'
      type: string
      example: ' '
    declined_date:
      description: 'The date of declination of the estimates'
      type: string
      example: ' '
    expiry_date:
      description: 'The date of expiration of the estimates'
      type: string
      example: '2013-11-30'
    zcrm_potential_id:
      description: 'Potential ID of a Deal in CRM.'
      type: integer
      format: int64
      example: 460000000026049
    zcrm_potential_name:
      type: string
    page_context:
      type: array
      items:
        type: object
        properties:
          page:
            $ref: '#/components/schemas/page'
          per_page:
            $ref: '#/components/schemas/per_page'
          has_more_page:
            $ref: '#/components/schemas/has_more_page'
          report_name:
            $ref: '#/components/schemas/report_name'
          applied_filter:
            $ref: '#/components/schemas/applied_filter'
          sort_column:
            $ref: '#/components/schemas/sort_column'
          sort_order:
            $ref: '#/components/schemas/sort_order'
    shipment_date:
      description: 'Search sales order by sales order shipment date. Variants: <code>shipment_date_start</code>, <code>shipment_date_end</code>, <code>shipment_date_before</code> and <code>shipment_date_after</code>. Default date format : <code>yyyy-mm-dd</code>'
      type: string
    sub_total:
      description: 'Sub Total of the Sales Order'
      type: number
      format: double
      example: 11800
    salesorder_number:
      description: 'Search Sales Order by Sales Order Number. Variants: <code>salesorder_number_startswith</code>, <code>salesorder_number_contains</code>. <code>Maximum Length : 100 </code>'
      type: string
      example: SO-001
    bcy_total:
      description: 'Total of Sales Order in Base Currency.'
      type: number
      format: double
      example: 400
    shipment_days:
      description: 'Days of Shipment for the Order'
      type: integer
      example: 2
    estimates:
      type: array
      items:
        type: object
        properties:
          estimate_id:
            $ref: '#/components/schemas/estimate_id'
          customer_name:
            $ref: '#/components/schemas/customer_name'
          customer_id:
            $ref: '#/components/schemas/customer_id'
          status:
            $ref: '#/components/schemas/status'
          estimate_number:
            $ref: '#/components/schemas/estimate_number'
          reference_number:
            $ref: '#/components/schemas/reference_number'
          date:
            $ref: '#/components/schemas/date'
          currency_id:
            $ref: '#/components/schemas/currency_id'
          currency_code:
            $ref: '#/components/schemas/currency_code'
          total:
            $ref: '#/components/schemas/total'
          created_time:
            $ref: '#/components/schemas/created_time'
          last_modified_time:
            $ref: '#/components/schemas/last_modified_time'
          accepted_date:
            $ref: '#/components/schemas/accepted_date'
          declined_date:
            $ref: '#/components/schemas/declined_date'
          expiry_date:
            $ref: '#/components/schemas/expiry_date'
          has_attachment:
            $ref: '#/components/schemas/has_attachment'
          is_viewed_by_client:
            $ref: '#/components/schemas/is_viewed_by_client'
          client_viewed_time:
            $ref: '#/components/schemas/client_viewed_time'
    invoices:
      type: array
      items:
        type: object
        properties:
          invoice_id:
            $ref: '#/components/schemas/invoice_id'
          ach_payment_initiated:
            $ref: '#/components/schemas/ach_payment_initiated'
          customer_name:
            $ref: '#/components/schemas/customer_name'
          customer_id:
            $ref: '#/components/schemas/customer_id'
          status:
            $ref: '#/components/schemas/status'
          invoice_number:
            $ref: '#/components/schemas/invoice_number'
          reference_number:
            $ref: '#/components/schemas/reference_number'
          date:
            $ref: '#/components/schemas/date'
          due_date:
            $ref: '#/components/schemas/due_date'
          due_days:
            $ref: '#/components/schemas/due_days'
          currency_id:
            $ref: '#/components/schemas/currency_id'
          schedule_time:
            $ref: '#/components/schemas/schedule_time'
          currency_code:
            $ref: '#/components/schemas/currency_code'
          is_viewed_by_client:
            $ref: '#/components/schemas/is_viewed_by_client'
          has_attachment:
            $ref: '#/components/schemas/has_attachment'
          client_viewed_time:
            $ref: '#/components/schemas/client_viewed_time'
          total:
            $ref: '#/components/schemas/total'
          balance:
            $ref: '#/components/schemas/balance'
          created_time:
            $ref: '#/components/schemas/created_time'
          last_modified_time:
            $ref: '#/components/schemas/last_modified_time'
          is_emailed:
            $ref: '#/components/schemas/is_emailed'
          reminders_sent:
            $ref: '#/components/schemas/reminders_sent'
          last_reminder_sent_date:
            $ref: '#/components/schemas/last_reminder_sent_date'
          payment_expected_date:
            $ref: '#/components/schemas/payment_expected_date'
          last_payment_date:
            $ref: '#/components/schemas/last_payment_date'
          custom_fields:
            $ref: '#/components/schemas/custom_fields'
          documents:
            $ref: '#/components/schemas/documents'
          salesperson_id:
            $ref: '#/components/schemas/salesperson_id'
          salesperson_name:
            $ref: '#/components/schemas/salesperson_name'
          shipping_charge:
            $ref: '#/components/schemas/shipping_charge'
          adjustment:
            $ref: '#/components/schemas/adjustment'
          write_off_amount:
            $ref: '#/components/schemas/write_off_amount'
          exchange_rate:
            $ref: '#/components/schemas/exchange_rate'
    get-a-contact-by-crm-contact-id-crm-account-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        contact:
          $ref: '#/components/schemas/contact'
    import-a-customer-using-the-crm-account-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        data:
          $ref: '#/components/schemas/data'
    import-a-customer-using-crm-contact-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        data:
          $ref: '#/components/schemas/data'
    import-a-vendor-using-the-crm-vendor-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        data:
          $ref: '#/components/schemas/data'
    get-the-list-of-invoices-using-crm-potential-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        invoices:
          $ref: '#/components/schemas/invoices'
        page_context:
          $ref: '#/components/schemas/page_context'
    get-the-list-of-estimates-using-crm-potential-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        estimates:
          type: array
          items:
            type: object
            properties:
              estimate_id:
                $ref: '#/components/schemas/estimate_id'
              customer_name:
                $ref: '#/components/schemas/customer_name'
              customer_id:
                $ref: '#/components/schemas/customer_id'
              status:
                $ref: '#/components/schemas/status'
              estimate_number:
                $ref: '#/components/schemas/estimate_number'
              reference_number:
                $ref: '#/components/schemas/reference_number'
              date:
                $ref: '#/components/schemas/date'
              currency_id:
                $ref: '#/components/schemas/currency_id'
              currency_code:
                $ref: '#/components/schemas/currency_code'
              total:
                $ref: '#/components/schemas/total'
              created_time:
                $ref: '#/components/schemas/created_time'
              last_modified_time:
                $ref: '#/components/schemas/last_modified_time'
              accepted_date:
                $ref: '#/components/schemas/accepted_date'
              declined_date:
                $ref: '#/components/schemas/declined_date'
              expiry_date:
                $ref: '#/components/schemas/expiry_date'
              has_attachment:
                $ref: '#/components/schemas/has_attachment'
              is_viewed_by_client:
                $ref: '#/components/schemas/is_viewed_by_client'
              client_viewed_time:
                $ref: '#/components/schemas/client_viewed_time'
        page_context:
          $ref: '#/components/schemas/page_context'
    get-the-list-of-salesorder-using-crm-potential-id-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        salesorders:
          type: array
          items:
            type: object
            properties:
              salesorder_id:
                $ref: '#/components/schemas/salesorder_id'
              zcrm_potential_id:
                $ref: '#/components/schemas/zcrm_potential_id'
              zcrm_potential_name:
                $ref: '#/components/schemas/zcrm_potential_name'
              customer_name:
                $ref: '#/components/schemas/customer_name'
              customer_id:
                $ref: '#/components/schemas/customer_id'
              status:
                $ref: '#/components/schemas/status'
              salesorder_number:
                $ref: '#/components/schemas/salesorder_number'
              reference_number:
                $ref: '#/components/schemas/reference_number'
              date:
                $ref: '#/components/schemas/date'
              shipment_date:
                $ref: '#/components/schemas/shipment_date'
              shipment_days:
                $ref: '#/components/schemas/shipment_days'
              currency_id:
                $ref: '#/components/schemas/currency_id'
              currency_code:
                $ref: '#/components/schemas/currency_code'
              total:
                $ref: '#/components/schemas/total'
              sub_total:
                $ref: '#/components/schemas/sub_total'
              bcy_total:
                $ref: '#/components/schemas/bcy_total'
              created_time:
                $ref: '#/components/schemas/created_time'
              last_modified_time:
                $ref: '#/components/schemas/last_modified_time'
              is_emailed:
                $ref: '#/components/schemas/is_emailed'
              has_attachment:
                $ref: '#/components/schemas/has_attachment'
              custom_fields:
                $ref: '#/components/schemas/custom_fields'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            ZohoBooks.contacts.READ: 'Read Contacts'
            ZohoBooks.contacts.CREATE: 'Create Contacts'
            ZohoBooks.estimates.READ: 'Read Estimates'
            ZohoBooks.salesorders.READ: 'Read Salesorders'