openapi: 3.0.0
info:
  title: 'Contact Persons'
  description: 'The list of contacts created.'
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://www.zohoapis.com/books/v3'
    description: 'API Endpoint'
tags:
  -
    name: contact-persons
    description: 'Contact-Persons Module'
paths:
  /contacts/contactpersons:
    post:
      tags:
        - contact-persons
      operationId: 'create_contact_person'
      summary: 'Create a contact person'
      description: 'Create a contact person for contact.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-contact-person-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-contact-person-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.CREATE
    parameters:
      -
        $ref: '#/components/parameters/organization_id'
  '/contacts/contactpersons/{contact_person_id}':
    put:
      tags:
        - contact-persons
      operationId: 'update_contact_person'
      summary: 'Update a contact person'
      description: 'Update an existing contact person.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-a-contact-person-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-a-contact-person-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.UPDATE
    delete:
      tags:
        - contact-persons
      operationId: 'delete_contact_person'
      summary: 'Delete a contact person'
      description: 'Delete an existing contact person.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-contact-person-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.DELETE
    parameters:
      -
        name: contact_person_id
        in: path
        required: true
        description: 'Unique identifier of the contact person.'
        schema:
          type: string
        example: 460000000026051
      -
        $ref: '#/components/parameters/organization_id'
  '/contacts/{contact_id}/contactpersons':
    get:
      tags:
        - contact-persons
      operationId: 'list_contact_persons'
      summary: 'List contact persons'
      description: 'List all contacts with pagination.'
      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-contact-persons-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.READ
    parameters:
      -
        name: contact_id
        in: path
        required: true
        description: 'Unique identifier of the contact.'
        schema:
          type: string
        example: 460000000026049
      -
        $ref: '#/components/parameters/organization_id'
  '/contacts/{contact_id}/contactpersons/{contact_person_id}':
    get:
      tags:
        - contact-persons
      operationId: 'get_contact_person'
      summary: 'Get a contact person'
      description: 'Get the contact person details.'
      parameters:
        -
          name: contact_person_id
          in: path
          required: true
          description: 'Unique identifier of the contact person.'
          schema:
            type: string
          example: 460000000026051
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-a-contact-person-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.READ
    parameters:
      -
        name: contact_id
        in: path
        required: true
        description: 'Unique identifier of the contact.'
        schema:
          type: string
        example: 460000000026049
      -
        $ref: '#/components/parameters/organization_id'
  '/contacts/contactpersons/{contact_person_id}/primary':
    post:
      tags:
        - contact-persons
      operationId: 'mark_contact_person_primary'
      summary: 'Mark as primary contact person'
      description: 'Mark a contact person as primary for the contact.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mark-as-primary-contact-person-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.contacts.CREATE
    parameters:
      -
        name: contact_person_id
        in: path
        required: true
        description: 'Unique identifier of the contact person.'
        schema:
          type: string
        example: 460000000026051
      -
        $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/contact_person-response'
    contact_person-response:
      type: object
      properties:
        contact_id:
          $ref: '#/components/schemas/contact_id'
        contact_person_id:
          $ref: '#/components/schemas/contact_person_id'
        salutation:
          $ref: '#/components/schemas/salutation'
        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'
        is_primary_contact:
          $ref: '#/components/schemas/is_primary_contact'
        skype:
          $ref: '#/components/schemas/skype'
        designation:
          $ref: '#/components/schemas/designation'
        department:
          $ref: '#/components/schemas/department'
        is_added_in_portal:
          $ref: '#/components/schemas/is_added_in_portal'
        communication_preference:
          $ref: '#/components/schemas/communication_preference'
    salutation:
      description: 'Salutation for the contact. Max-length [25]'
      type: string
      example: Mr
    contact_id:
      description: 'Contact id of the contact'
      type: string
      example: 460000000026049
    page_context:
      description: 'The context of a particular page.'
      type: object
      properties:
        page:
          $ref: '#/components/schemas/page'
        per_page:
          $ref: '#/components/schemas/per_page'
        has_more_page:
          $ref: '#/components/schemas/has_more_page'
        sort_column:
          $ref: '#/components/schemas/sort_column'
        sort_order:
          $ref: '#/components/schemas/sort_order'
    page:
      description: 'Number of pages'
      type: integer
      example: 1
    per_page:
      description: 'Per page values'
      type: integer
      example: 200
    has_more_page:
      description: 'Check if has more pages'
      type: boolean
      example: false
    sort_order:
      description: 'The order for sorting'
      type: string
      example: A
    sort_column:
      description: 'Param Description.Allowed Values: <code>contact_person_id</code>'
      type: string
      example: contact_person_id
    contact_person_id:
      description: 'The id of the contact person'
      type: string
      example: 460000000026051
    first_name:
      description: 'First name of the contact person. Max-length [100]'
      type: string
      example: Will
    last_name:
      description: 'Last name of the contact person. Max-length [100]'
      type: string
      example: Smith
    is_primary_contact:
      description: 'To mark contact person as primary for contact'
      type: boolean
      example: true
    email:
      description: 'Email address of the contact person.  Max-length [100]'
      type: string
      example: willsmith@bowmanfurniture.com
    phone:
      description: 'Max-length [50]'
      type: string
      example: +1-925-921-9201
    mobile:
      description: 'Max-length [50]'
      type: string
      example: +1-4054439562
    skype:
      description: 'skype address. Max-length [50]'
      type: string
      example: zoho
    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'
    is_whatsapp_enabled:
      description: 'Used to check if WhatsApp communication preference is enabled for the contact person.'
      type: boolean
      example: true
      x-node_available_in:
        - 'WhatsApp integration'
    communication_preference:
      description: 'Preferred modes of communication for the contact person.'
      type: object
      properties:
        is_sms_enabled:
          $ref: '#/components/schemas/is_sms_enabled'
        is_whatsapp_enabled:
          $ref: '#/components/schemas/is_whatsapp_enabled'
    designation:
      description: 'designation of a person. Max-length [50]'
      type: string
      example: 'Sales Engineer'
    department:
      description: 'department on which a person belongs. Max-length [50]'
      type: string
      example: Sales
    enable_portal:
      description: 'option to enable the portal access. allowed values <code>true</code>,<code>false</code>'
      type: boolean
      example: true
    is_added_in_portal:
      description: 'tells whether the contact person has portal access/not'
      type: boolean
      example: true
    contact_persons:
      description: 'Contact persons of a contact.'
      type: object
      properties:
        salutation:
          $ref: '#/components/schemas/salutation'
        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'
        is_primary_contact:
          description: 'To mark contact person as primary for contact'
          type: boolean
          example: true
        communication_preference:
          $ref: '#/components/schemas/communication_preference'
    create-a-contact-person-request:
      required:
        - first_name
      type: object
      properties:
        contact_id:
          $ref: '#/components/schemas/contact_id'
        salutation:
          $ref: '#/components/schemas/salutation'
        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'
        skype:
          $ref: '#/components/schemas/skype'
        designation:
          $ref: '#/components/schemas/designation'
        department:
          $ref: '#/components/schemas/department'
        enable_portal:
          $ref: '#/components/schemas/enable_portal'
        communication_preference:
          $ref: '#/components/schemas/communication_preference'
    create-a-contact-person-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The contactperson has been Created'
          readOnly: true
        contact_person:
          type: array
          items:
            $ref: '#/components/schemas/contact_person-response'
    update-a-contact-person-request:
      required:
        - contact_id
        - first_name
      type: object
      properties:
        contact_id:
          $ref: '#/components/schemas/contact_id'
        salutation:
          $ref: '#/components/schemas/salutation'
        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'
        skype:
          $ref: '#/components/schemas/skype'
        designation:
          $ref: '#/components/schemas/designation'
        department:
          $ref: '#/components/schemas/department'
        enable_portal:
          $ref: '#/components/schemas/enable_portal'
        is_primary_contact:
          $ref: '#/components/schemas/is_primary_contact'
        communication_preference:
          $ref: '#/components/schemas/communication_preference'
    update-a-contact-person-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The contactperson details has been updated.'
          readOnly: true
        contact_person:
          type: array
          items:
            type: object
            properties:
              contact_id:
                $ref: '#/components/schemas/contact_id'
              contact_person_id:
                $ref: '#/components/schemas/contact_person_id'
              salutation:
                $ref: '#/components/schemas/salutation'
              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'
              is_primary_contact:
                $ref: '#/components/schemas/is_primary_contact'
              skype:
                $ref: '#/components/schemas/skype'
              designation:
                $ref: '#/components/schemas/designation'
              department:
                $ref: '#/components/schemas/department'
              is_added_in_portal:
                $ref: '#/components/schemas/is_added_in_portal'
              communication_preference:
                $ref: '#/components/schemas/communication_preference'
    delete-a-contact-person-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The contact person has been deleted.'
          readOnly: true
    list-contact-persons-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        contact_persons:
          description: 'Contact persons of a contact.'
          type: array
          items:
            type: object
            properties:
              contact_person_id:
                $ref: '#/components/schemas/contact_person_id'
              salutation:
                $ref: '#/components/schemas/salutation'
              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'
              is_primary_contact:
                $ref: '#/components/schemas/is_primary_contact'
              skype:
                $ref: '#/components/schemas/skype'
              designation:
                $ref: '#/components/schemas/designation'
              department:
                $ref: '#/components/schemas/department'
              is_added_in_portal:
                $ref: '#/components/schemas/is_added_in_portal'
              communication_preference:
                $ref: '#/components/schemas/communication_preference'
        page_context:
          description: 'The context of a particular page.'
          type: object
          properties:
            page:
              $ref: '#/components/schemas/page'
            per_page:
              $ref: '#/components/schemas/per_page'
            has_more_page:
              $ref: '#/components/schemas/has_more_page'
            sort_column:
              $ref: '#/components/schemas/sort_column'
            sort_order:
              $ref: '#/components/schemas/sort_order'
    get-a-contact-person-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        contact_person:
          type: object
          properties:
            contact_id:
              $ref: '#/components/schemas/contact_id'
            contact_person_id:
              $ref: '#/components/schemas/contact_person_id'
            salutation:
              $ref: '#/components/schemas/salutation'
            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'
            is_primary_contact:
              $ref: '#/components/schemas/is_primary_contact'
            skype:
              $ref: '#/components/schemas/skype'
            designation:
              $ref: '#/components/schemas/designation'
            department:
              $ref: '#/components/schemas/department'
            is_added_in_portal:
              $ref: '#/components/schemas/is_added_in_portal'
            communication_preference:
              $ref: '#/components/schemas/communication_preference'
    mark-as-primary-contact-person-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'This contact person has been marked as your primary contact person.'
          readOnly: true
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          scopes:
            ZohoBooks.contacts.CREATE: 'Create Contacts'
            ZohoBooks.contacts.UPDATE: 'Update Contacts'
            ZohoBooks.contacts.READ: 'Read Contacts'
            ZohoBooks.contacts.DELETE: 'Delete Contacts'
