Zoho CRM Deal Contact Roles

{
  "openapi": "3.1.0",
  "info": {
    "title": "Deal Contact Roles",
    "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"
        }
      }
    }
  ],
  "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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      }
    },
    "/{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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "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
      },
      "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": "Erro

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