Zoho CRM Contact Roles API

openapi: 3.2.0
info:
  title: Deal Contact Roles API
  description: API for managing contact roles in Deal records. Track and manage which contacts are associated with deals and their specific roles (e.g., Decision Maker, Influencer). Supports full CRUD operations to maintain accurate relationship data between contacts and deal opportunities.
  version: '8.0'
servers:
- url: https://zohoapis.{dc}/crm/{version}
  description: API Server URL
  variables:
    dc:
      enum:
      - com
      - eu
      - in
      - cn
      - au
      default: com
      description: API Server URL TLD
    version:
      default: v8
      description: API Version
tags:
- name: Contact Roles
paths:
  /{module}/{dealId}/Contact_Roles:
    get:
      summary: Get Associated Contact Roles
      description: Retrieve contact roles associated with a deal
      operationId: getAssociatedContactRoles
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Successfully retrieved contact roles associated with the deal
          content:
            application/json:
              schema:
                type: object
                description: Response containing contact roles data and pagination info
                properties:
                  data:
                    type: array
                    maxItems: 100
                    description: Array of contact role records with fields specified in the query parameter
                    items:
                      type: object
                      description: Contact role record with dynamic fields based on the 'fields' query parameter
                      properties:
                        Owner:
                          type: object
                          description: Owner information for the contact role
                          properties:
                            name:
                              type: string
                              description: Owner's display name
                              maxLength: 255
                            id:
                              type: string
                              description: Owner's unique identifier
                              format: int64
                            email:
                              type: string
                              description: Owner's email address
                              format: email
                          additionalProperties: false
                        Department:
                          type:
                          - string
                          - 'null'
                          description: Department of the contact
                        Contact_Role:
                          type: object
                          description: Contact role information
                          properties:
                            name:
                              type: string
                              description: Role name (e.g., Developer/Evaluator)
                              maxLength: 255
                            id:
                              type: string
                              description: Role's unique identifier
                              format: int64
                          required:
                          - name
                          - id
                          additionalProperties: false
                      additionalProperties: true
                  info:
                    type: object
                    description: Pagination and response metadata
                    properties:
                      per_page:
                        type: integer
                        description: Number of records per page
                        format: int32
                      next_page_token:
                        type:
                        - string
                        - 'null'
                        description: Token for retrieving the next page of results
                      count:
                        type: integer
                        format: int32
                        description: Number of records in the current response
                      page:
                        type: integer
                        format: int32
                        description: Current page number
                      previous_page_token:
                        type:
                        - string
                        - 'null'
                        description: Token for retrieving the previous page of results
                      page_token_expiry:
                        type:
                        - string
                        - 'null'
                        description: Expiry timestamp for page tokens
                      more_records:
                        type: boolean
                        description: Indicates if more records are available
                    required:
                    - per_page
                    - count
                    - page
                    - more_records
                    additionalProperties: false
                required:
                - data
                - info
                additionalProperties: false
        '204':
          description: No content - No contact roles found for the specified deal
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
    put:
      summary: Add Or Update Contact Role Relations
      description: Add contact roles to a deal or update existing contact role relations in bulk
      operationId: upsertContactRoleRelations
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertRelationsRequest'
      responses:
        '200':
          description: Successfully added or updated the specified contact role relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertRelationsSuccessResponse'
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
    delete:
      summary: Delete Contact Role Relations
      description: Remove one or more contact role associations from a deal using their relation IDs
      operationId: deleteContactRoleRelations
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      - $ref: '#/components/parameters/Ids'
      responses:
        '200':
          description: Successfully removed the specified contact role relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRelationsSuccessResponse'
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
  /{module}/{dealId}/Contact_Roles/{contactId}:
    get:
      summary: Get Contact Role For Contact
      description: Retrieve the contact role relation for a specific contact associated with a deal.
      operationId: getDealContactRoleForContact
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      - $ref: '#/components/parameters/Contact'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Successfully retrieved the contact role relation for the given contact
          content:
            application/json:
              schema:
                type: object
                description: Response containing the contact role relation for the specified contact
                properties:
                  data:
                    type: array
                    maxItems: 1
                    description: Array containing the contact role record for the specified contact
                    items:
                      type: object
                      description: Contact role record with dynamic fields based on the 'fields' query parameter
                      properties:
                        Owner:
                          type: object
                          description: Owner information for the contact role
                          properties:
                            name:
                              type: string
                              description: Owner's display name
                              maxLength: 255
                            id:
                              type: string
                              description: Owner's unique identifier
                              format: int64
                            email:
                              type: string
                              description: Owner's email address
                              format: email
                          additionalProperties: false
                        Department:
                          type:
                          - string
                          - 'null'
                          description: Department of the contact
                        Contact_Role:
                          type: object
                          description: Contact role information
                          properties:
                            name:
                              type: string
                              description: Role name (e.g., Developer/Evaluator)
                              maxLength: 255
                            id:
                              type: string
                              description: Role's unique identifier
                              format: int64
                          required:
                          - name
                          - id
                          additionalProperties: false
                      additionalProperties: true
                    minItems: 1
                required:
                - data
                additionalProperties: false
        '204':
          description: No contact role relation exists for the specified contact on this deal
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
    put:
      summary: Associate Contact Role To Deal
      description: Assign or update a contact role for a specific contact on a deal.
      operationId: associateContactRoleToDeal
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      - $ref: '#/components/parameters/Contact'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Payload containing the contact role assignment to apply
              properties:
                data:
                  type: array
                  description: Single contact role relation definition
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    description: Contact role configuration for the specified contact
                    properties:
                      Contact_Role:
                        type: object
                        description: Contact role details to associate
                        properties:
                          name:
                            type: string
                            description: Contact role display name
                            maxLength: 255
                          id:
                            type: string
                            format: int64
                            description: Unique identifier of the contact role
                        additionalProperties: false
                    required:
                    - Contact_Role
                    additionalProperties: false
              required:
              - data
              additionalProperties: false
      responses:
        '200':
          description: Successfully associated the contact role with the deal
          content:
            application/json:
              schema:
                type: object
                description: Result of updating the contact role relation
                properties:
                  data:
                    type: array
                    description: Status entries for the processed contact relation
                    minItems: 1
                    maxItems: 1
                    items:
                      type: object
                      description: Operation result for the contact relation
                      properties:
                        code:
                          type: string
                          description: Operation status code
                          const: SUCCESS
                        details:
                          type: object
                          description: Details about the processed relation
                          properties:
                            id:
                              type: string
                              format: int64
                              description: Identifier of the contact-deal relation
                          required:
                          - id
                          additionalProperties: false
                        message:
                          type: string
                          description: Result message
                          const: relation updated
                        status:
                          type: string
                          description: Operation status
                          const: success
                      required:
                      - code
                      - details
                      - message
                      - status
                      additionalProperties: false
                required:
                - data
                additionalProperties: false
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
    delete:
      summary: Delete Contact Role Relation
      description: Remove a specific contact-deal relation using the contact identifier in the path.
      operationId: deleteContactRoleRelation
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/DealId'
      - $ref: '#/components/parameters/Contact'
      responses:
        '200':
          description: Successfully removed the specified contact relation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRelationsSuccessResponse'
        '400':
          description: Bad Request - Invalid data, invalid module, field limit exceeded, or required parameter missing
          content:
            application/json:
              schema:
                description: Error response for a bad request, which can be one of several specific error types.
                oneOf:
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
                - $ref: '#/components/schemas/InvalidRelationNameError'
        '403':
          description: Forbidden - No permission to access deals or contacts
          content:
            application/json:
              schema:
                description: Error response for when the user lacks permission to access deals or contacts.
                oneOf:
                - $ref: '#/components/schemas/NoPermissionDealsError'
                - $ref: '#/components/schemas/NoPermissionContactsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.CONTACTS.VIEW
        - ZohoCRM.modules.DEALS.VIEW
      tags:
      - Contact Roles
components:
  parameters:
    Contact:
      name: contactId
      in: path
      required: true
      description: The unique identifier of the contact record
      schema:
        type: string
        format: int64
    DealId:
      name: dealId
      in: path
      required: true
      description: The unique identifier of the deal record
      schema:
        type: string
        format: int64
    Fields:
      name: fields
      in: query
      required: true
      description: Comma-separated list of field names to include in the response. Field names must follow API naming conventions.
      schema:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_]*(?:,[A-Za-z_][A-Za-z0-9_]*)*$
        minLength: 1
        maxLength: 1000
    Ids:
      name: ids
      in: query
      required: false
      description: Comma-separated list of contact role relation IDs to delete
      schema:
        type: string
        format: int64
    Module:
      name: module
      in: path
      required: true
      description: The module name for the deal record
      schema:
        type: string
        enum:
        - Deals
  schemas:
    InvalidModuleError:
      type: object
      description: Invalid module name error
      properties:
        code:
          type: string
          description: Error code indicating invalid module name
          const: INVALID_MODULE
        details:
          type: object
          description: Error details containing the path index
          properties:
            resource_path_index:
              type: integer
              format: int32
              description: Index of the path parameter that is invalid (0 for module)
              const: 0
          required:
          - resource_path_index
          additionalProperties: false
        message:
          type: string
          description: Error message indicating the module name is invalid
          const: the module name given seems to be invalid
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    UpsertRelationsRequest:
      type: object
      description: Payload for adding or updating contact role relations on a deal
      properties:
        data:
          type: array
          description: List of contact role relations to upsert
          minItems: 1
          maxItems: 100
          items:
            type: object
            description: Contact role relation definition
            properties:
              Contact_Role:
                type: object
                description: Contact role to associate with the relation
                properties:
                  name:
                    type: string
                    description: Contact role display name
                    maxLength: 255
                  id:
                    type: string
                    format: int64
                    description: Contact role identifier
                required:
                - id
                additionalProperties: false
              id:
                type: string
                format: int64
                description: Identifier of the contact relation for the deal
            required:
            - Contact_Role
            - id
            additionalProperties: false
      required:
      - data
      additionalProperties: false
    UpsertRelationsSuccessResponse:
      type: object
      description: Response returned after adding or updating contact role relations
      properties:
        data:
          type: array
          description: Status entries for each processed relation
          minItems: 1
          maxItems: 100
          items:
            type: object
            description: Result for processing a single relation
            properties:
              code:
                type: string
                description: Operation status code
                const: SUCCESS
              details:
                type: object
                description: Details about the processed relation
                properties:
                  id:
                    type: string
                    format: int64
                    description: Identifier of the processed relation
                required:
                - id
                additionalProperties: false
              message:
                type: string
                description: Result message describing the action performed
                enum:
                - relation updated
                - relation added
              status:
                type: string
                description: Operation status
                const: success
            required:
            - code
            - details
            - message
            - status
            additionalProperties: false
      required:
      - data
      additionalProperties: false
    RequiredParamMissingError:
      type: object
      description: Required parameter missing error
      properties:
        code:
          type: string
          description: Error code indicating a required parameter is missing
          const: REQUIRED_PARAM_MISSING
        details:
          type: object
          description: Error details containing the missing parameter name
          properties:
            param_name:
              type: string
              description: Name of the missing required parameter
              const: fields
          required:
          - param_name
          additionalProperties: false
        message:
          type: string
          description: Error message indicating a parameter is missing
          const: One of the expected parameter is missing
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    InvalidRelationNameError:
      type: object
      description: Invalid relation name error
      properties:
        code:
          type: string
          description: Error code indicating invalid relation name
          const: INVALID_DATA
        details:
          type: object
          description: Error details containing the path index
          properties:
            resource_path_index:
              type: integer
              format: int32
              description: Index of the path parameter that is invalid (2 for relation name)
              const: 2
          required:
          - resource_path_index
          additionalProperties: false
        message:
          type: string
          description: Error message indicating the relation name is invalid
          const: the relation name given seems to be invalid
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    NoPermissionDealsError:
      type: object
      description: No permission to view deals
      properties:
        code:
          type: string
          description: Error code indicating lack of permission
          const: NO_PERMISSION
        details:
          type: object
          description: Details about the missing permissions
          properties:
            permissions:
              type: array
              description: List of required permissions that are missing
              items:
                type: string
                description: Permission identifier for viewing deals
                const: Crm_Implied_View_Potentials
              maxItems: 1
          required:
          - permissions
          additionalProperties: false
        message:
          type: string
          description: Error message indicating permission denial
          const: permission denied
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    InvalidDataError:
      type: object
      description: Invalid related ID error
      properties:
        code:
          type: string
          description: Error code indicating invalid deal ID
          const: INVALID_DATA
        details:
          type: object
          description: Error details containing the path index
          properties:
            resource_path_index:
              type: integer
              format: int64
              description: Index of the path parameter that is invalid (1 for deal ID)
              const: 1
          required:
          - resource_path_index
          additionalProperties: false
        message:
          type: string
          description: Error message indicating the deal ID is invalid
          const: the related id given seems to be invalid
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    NoPermissionContactsError:
      type: object
      description: No permission to view contacts
      properties:
        code:
          type: string
          description: Error code indicating lack of permission
          const: NO_PERMISSION
        details:
          type: object
          description: Details about the missing permissions
          properties:
            permissions:
              type: array
              description: List of required permissions that are missing
              items:
                type: string
                description: Permission identifier for viewing contacts
                const: Crm_Implied_View_Contacts
              maxItems: 1
          required:
          - permissions
          additionalProperties: false
        message:
          type: string
          description: Error message indicating permission denial
          const: permission denied
        status:
          type: string
          description: Response status
          const: error
      required:
      - code
      - details
      - message
      - status
      additionalProperties: false
    DeleteRelationsSuccessResponse:
      type: object
      description: Response returned after deleting contact role relations
      properties:
        data:
          type: array
          description: Status entries for each deleted relation
          maxItems: 100
          items:
            type

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-contact-roles-api-openapi.yml