Zoho Contact Deduplication API

openapi: 3.2.0
info:
  title: Helpcenter Contact Deduplication API
  version: 1.0.0
tags:
- name: ContactDeduplication
paths:
  /api/v1/groupContactDuplicateValues:
    get:
      tags:
      - ContactDeduplication
      summary: List duplicate contacts
      description: This API lists the duplicate entries of a contact.The _fieldName_ parameters is mandatory in the API request <br/></br/>_Note:_<br/> If you encounter a 202 status code while executing this API request, it means there are 100,000 or more contacts in the help desk portal. Matching the records and finding duplicates will be time-consuming in such a scenario. Therefore, the deduplication request will be accepted, and after the process is completed, an automated report will be sent to the user who initiated the deduplication.
      operationId: getDuplicateContactFieldValueCounts
      parameters:
      - $ref: '#/components/parameters/fieldName'
      - name: swFieldValue
        in: query
        description: Key that specifies the letter with which the field values must start
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: Key that specifies the letter with which the field values must start
          maxLength: 100
          minLength: 0
          pattern: ^([a-z0-9*#])$
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/from'
      - name: sortBy
        in: query
        description: 'Key that sorts the contacts by a specific attribute: @count@ or @fieldValue@. The default sorting order is ascending. A @-@ prefix denotes descending order of sorting'
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: 'Key that sorts the contacts by a specific attribute: @count@ or @fieldValue@. The default sorting order is ascending. A @-@ prefix denotes descending order of sorting'
          enum:
          - count
          - fieldValue
          maxLength: 100
          minLength: 0
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '200':
          $ref: '#/components/responses/listDuplicateContactCountResponse'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '202':
          $ref: ./Common.json#/components/responses/emptyResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
      x-audience:
      - external-public
  /api/v1/contactsDeduplication/defaultFieldName:
    get:
      tags:
      - ContactDeduplication
      summary: Get name of default field
      description: This API fetches the name of the field set as the default field for contact deduplication.
      operationId: getDefaultFieldNameForContactDeduplication
      parameters:
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/getDefaultField'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
      x-audience:
      - external-public
    post:
      tags:
      - ContactDeduplication
      summary: Set default field for contact deduplication
      description: This API sets the field you specify as the default field for deduplicating contacts.
      operationId: setDefaultFieldNameForContactDeduplication
      parameters:
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/setDefaultField'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '404':
          $ref: ./errors.json#/components/responses/commonErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
      x-audience:
      - external-public
  /api/v1/groupContacts:
    get:
      tags:
      - ContactDeduplication
      summary: List details of duplicate contacts
      description: This API lists all the details of duplicate contacts.The _fieldName_ and _fieldValues_ parameters are mandatory in the API request
      operationId: listGroupedDuplicateContacts
      parameters:
      - name: include
        in: query
        description: 'Secondary information related to the contact. Value allowed is: @accounts@'
        required: false
        style: simple
        explode: true
        schema:
          type:
          - 'null'
          - array
          description: 'Secondary information related to the contact. Value allowed is: @accounts@'
          items:
            type:
            - string
            - 'null'
            enum:
            - accounts
            maxLength: 100
            minLength: 0
          uniqueItems: true
      - $ref: '#/components/parameters/fieldName'
      - $ref: '#/components/parameters/limit'
      - name: sortBy
        in: query
        description: Key that sorts the contacts by a specific attribute:  !@firstName,@! !@lastName,@! !@fullName,@! !@phone,@! !@email,@! !@account,@! !@createdTime,@! !@modifiedTime@!
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: Key that sorts the contacts by a specific attribute:  !@firstName,@! !@lastName,@! !@fullName,@! !@phone,@! !@email,@! !@account,@! !@createdTime,@! !@modifiedTime@!
          enum:
          - firstName
          - lastName
          - fullName
          - phone
          - email
          - createdTime
          - modifiedTime
          maxLength: 100
          minLength: 0
      - $ref: '#/components/parameters/from'
      - name: fieldValues
        in: query
        description: Actual values in each field related to the contact
        required: true
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: Actual values in each field related to the contact
          maxLength: 100
          minLength: 0
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '200':
          $ref: '#/components/responses/listDuplicateContactResponse'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
      x-audience:
      - external-public
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Number of contacts to fetch
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: Number of contacts to fetch
        maximum: 100
        minimum: 1
        pattern: ([0-9]+)
    fieldName:
      name: fieldName
      in: query
      description: 'Name of the field whose values must be matched for deduplication.Values allowed are: !@firstName,@! !@lastName,@! !@email,@! !@secondaryEmail,@! !@phone,@! !@fullName,@! and !@bothEmail.@!'
      required: true
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        description: 'Name of the field whose values must be matched for deduplication.Values allowed are: !@firstName,@! !@lastName,@! !@email,@! !@secondaryEmail,@! !@phone,@! !@fullName,@! and !@bothEmail.@!'
        enum:
        - firstName
        - lastName
        - email
        - secondaryEmail
        - phone
        - fullName
        - bothEmail
        maxLength: 100
        minLength: 0
    from:
      name: from
      in: query
      description: Index number starting from which the contacts must be fetched
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: Index number starting from which the contacts must be fetched
        minimum: 0
        pattern: ([0-9]+)
  requestBodies:
    setDefaultField:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              fieldName:
                type:
                - string
                - 'null'
                enum:
                - firstName
                - lastName
                - email
                - secondaryEmail
                - phone
                - fullName
                - bothEmail
                maxLength: 100
                minLength: 0
              markDefault:
                type:
                - boolean
                - 'null'
            required:
            - fieldName
            - markDefault
          examples:
            Valid requestBody Definitions:
              value:
                fieldName: email
                markDefault: true
  responses:
    listDuplicateContactCountResponse:
      description: listDuplicateContactCountResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: ./ContactDeduplication.json#/components/schemas/counts
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - count: 16
                  fieldValue: Jade
                - count: 2
                  fieldValue: saran
    getDefaultField:
      description: getDefaultField template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              fieldName:
                type:
                - string
                - 'null'
                enum:
                - firstName
                - lastName
                - email
                - secondaryEmail
                - phone
                - fullName
                - bothEmail
                - null
            required:
            - fieldName
          examples:
            Valid responses Definitions:
              value:
                fieldName: email
    listDuplicateContactResponse:
      description: listDuplicateContactResponse template definitions
      content:
        application/json:
          schema:
            allOf:
            - type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      account:
                        type:
                        - 'null'
                        - object
                        additionalProperties: false
                        maxProperties: 3
                        minProperties: 3
                        properties:
                          website:
                            type:
                            - string
                            - 'null'
                            maxLength: 120
                            minLength: 0
                          accountName:
                            type:
                            - string
                            - 'null'
                            maxLength: 200
                            minLength: 0
                          id:
                            type:
                            - string
                            - 'null'
                            - integer
                            format: int64
                            pattern: ([0-9]+)
                        required:
                        - accountName
                        - id
                        - website
            - type:
              - 'null'
              - object
              additionalProperties: false
              properties:
                data:
                  $ref: ./ContactDeduplication.json#/components/schemas/duplicateResponseData
              required:
              - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - fieldValue: Jade
                  contacts:
                  - lastName: Jade
                    secondaryEmail: null
                    ownerId: null
                    type: null
                    accountId: '1892000000091433'
                    firstName: Jonathan
                    photoURL: https://desk.zoho.com/api/v1/contacts/1892000000772003/photo
                    phone: '555555'
                    webUrl: https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38
                    createdTime: 1507813910000
                    zohoCRMContact: null
                    id: '1892000000772003'
                    isSpam: false
                    customerHappiness:
                      badPercentage: '0'
                      okPercentage: '0'
                      goodPercentage: '0'
                    email: case@zylker.com
                  - lastName: Jade
                    secondaryEmail: null
                    ownerId: null
                    type: null
                    accountId: '1892000000052077'
                    firstName: Christ
                    photoURL: null
                    phone: null
                    webUrl: https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38
                    createdTime: 1507813910000
                    zohoCRMContact:
                      id: '1892000000772030'
                      type: contacts_leads
                    id: '1892000000772001'
                    isSpam: false
                    customerHappiness:
                      badPercentage: '22'
                      okPercentage: '31'
                      goodPercentage: '47'
                    email: jade@zylker.com
                - fieldValue: Christ
                  contacts:
                  - lastName: Jade
                    secondaryEmail: null
                    ownerId: null
                    type: null
                    accountId: '1892000000091433'
                    firstName: Christ
                    photoURL: https://desk.zoho.com/api/v1/contacts/1892000000772003/photo
                    phone: '555555'
                    webUrl: https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38
                    createdTime: 1507813910000
                    zohoCRMContact: null
                    id: '1892000000772003'
                    isSpam: false
                    customerHappiness:
                      badPercentage: '0'
                      okPercentage: '0'
                      goodPercentage: '0'
                    email: case@zylker.com
                  - lastName: Jade
                    secondaryEmail: null
                    ownerId: null
                    type: null
                    accountId: '1892000000052077'
                    firstName: Christ
                    photoURL: null
                    phone: null
                    webUrl: https://desk.zoho.com/support/zylker/ShowHomePage.do#Contacts/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38
                    createdTime: 1507813910000
                    zohoCRMContact:
                      id: '1892000000772030'
                      type: contacts_leads
                    id: '1892000000772001'
                    isSpam: false
                    customerHappiness:
                      badPercentage: '22'
                      okPercentage: '31'
                      goodPercentage: '47'
                    email: jade@zylker.com
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter