openapi: 3.1.0 info: title: Helpcenter Attachments API version: 1.0.0 tags: - name: Attachments paths: /{moduleApiName}/{recordId}/Attachments/{id}: get: operationId: getAttachmentById summary: Download a specific attachment file description: Download the file content of a specific attachment by its ID. This endpoint returns the actual file (image, PDF, document, etc.). For link attachments, an error is returned as they cannot be downloaded. security: - iam-oauth2-schema: - ZohoCRM.modules.attachments.READ parameters: - $ref: '#/components/parameters/RecordId' - $ref: '#/components/parameters/ModuleApiName' - $ref: '#/components/parameters/Id' responses: '200': description: Successfully downloaded attachment file content: application/octet-stream: schema: type: string format: binary description: The binary content of the attachment file image/png: schema: type: string format: binary description: PNG image file image/jpeg: schema: type: string format: binary description: JPEG image file application/pdf: schema: type: string format: binary description: PDF document file '204': description: No Content - Invalid attachment ID '400': description: Bad request - invalid parameters or link attachment download attempt content: application/json: schema: description: Wrapper for get attachment by ID error responses oneOf: - type: object description: Error response for link attachment download attempt properties: code: type: string description: Error code enum: - DOWNLOAD_NOT_ALLOWED details: type: object description: Additional error details properties: param_name: type: string description: Name of the missing parameter maxLength: 100 additionalProperties: false message: type: string description: Error message enum: - As it is a linked attachment, you can not download it status: type: string description: Error status indicator enum: - error required: - code - details - message - status additionalProperties: false - type: object description: Error response for invalid record ID properties: status: type: string description: Error status indicator enum: - error code: type: string description: Error code enum: - INVALID_DATA message: type: string description: Error message enum: - the related id given seems to be invalid details: type: object description: Additional error details properties: resource_path_index: type: integer format: int32 description: Index of the resource path causing the error required: - resource_path_index additionalProperties: false required: - status - code - message - details additionalProperties: false - type: object description: Error response for invalid module name properties: code: type: string description: Error code enum: - INVALID_MODULE details: type: object description: Additional error details properties: resource_path_index: type: integer format: int32 description: Index of the resource path causing the error required: - resource_path_index additionalProperties: false message: type: string description: Error message enum: - the module name given seems to be invalid status: type: string description: Error status indicator enum: - error required: - code - details - message - status additionalProperties: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' tags: - Attachments delete: operationId: deleteAttachment summary: Delete Link Attachment description: Delete a link attachment associated with a specific record in a module. security: - iam-oauth2-schema: - ZohoCRM.modules.attachments.DELETE - iam-oauth2-schema: - ZohoCRM.modules.attachments.ALL parameters: - $ref: '#/components/parameters/RecordId' - $ref: '#/components/parameters/ModuleApiName' - $ref: '#/components/parameters/Id' responses: '200': description: Successful deletion response content: application/json: schema: type: object description: Successful deletion response additionalProperties: false properties: data: type: array description: Array of deletion results maxItems: 100 items: type: object description: Deletion status details additionalProperties: false properties: code: type: string description: Response code indicating success enum: - SUCCESS details: type: object description: Details of the deleted attachment additionalProperties: false properties: id: type: string description: ID of the deleted attachment pattern: ^[0-9]+$ maxLength: 50 required: - id message: type: string description: Success message enum: - record deleted status: type: string description: Operation status enum: - success required: - code - details - message - status required: - data '400': description: Error response for invalid request content: application/json: schema: description: Wrapper for delete attachment error responses oneOf: - type: object description: Error response for invalid related id additionalProperties: false properties: status: type: string description: Error status indicator enum: - error code: type: string description: Error code indicating invalid data enum: - INVALID_DATA message: type: string description: Error message describing the issue enum: - the related id given seems to be invalid - record not deleted details: type: object description: Additional error details additionalProperties: false properties: resource_path_index: type: integer format: int32 description: Index of the resource path causing the error required: - resource_path_index required: - status - code - message - details - type: object description: Error response for invalid module name additionalProperties: false properties: status: type: string description: Error status indicator enum: - error code: type: string description: Error code indicating invalid module enum: - INVALID_MODULE message: type: string description: Error message describing the issue enum: - the module name given seems to be invalid details: type: object description: Additional error details additionalProperties: false properties: resource_path_index: type: integer format: int32 description: Index of the resource path causing the error required: - resource_path_index required: - status - code - message - details tags: - Attachments /{moduleApiName}/{recordId}/Attachments: get: operationId: getAttachments summary: Retrieve all attachments associated with a specific record description: Retrieve all attachments associated with a specific record. security: - iam-oauth2-schema: - ZohoCRM.modules.attachments.READ - iam-oauth2-schema: - ZohoCRM.modules.attachments.ALL parameters: - $ref: '#/components/parameters/RecordId' - $ref: '#/components/parameters/ModuleApiName' - $ref: '#/components/parameters/Fields' responses: '200': description: Successfully retrieved list of attachments content: application/json: schema: $ref: '#/components/schemas/AttachmentListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' tags: - Attachments post: operationId: uploadAttachment summary: Upload an attachment description: 'Upload an attachment by providing either a file or a valid URL. Maximum request body size: 100MB.' security: - iam-oauth2-schema: - ZohoCRM.modules.attachments.CREATE - iam-oauth2-schema: - ZohoCRM.modules.attachments.ALL parameters: - $ref: '#/components/parameters/RecordId' - $ref: '#/components/parameters/ModuleApiName' requestBody: content: multipart/form-data: schema: oneOf: - type: object description: Upload attachment by file properties: file: type: string format: binary description: The file to upload as an attachment required: - file additionalProperties: false - type: object description: Upload attachment by URL properties: attachmentUrl: type: string description: The URL of the attachment to be linked maxLength: 3000 title: type: - string - 'null' description: Optional title for the attachment minLength: 1 maxLength: 255 required: - attachmentUrl additionalProperties: false required: true responses: '200': description: Attachment uploaded successfully content: application/json: schema: $ref: '#/components/schemas/AttachmentSuccessResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' tags: - Attachments components: schemas: AttachmentObject: type: object description: Individual attachment metadata properties: id: type: string description: The unique numeric identifier of the attachment pattern: ^[0-9]+$ maxLength: 50 File_Name: type: string description: Name of the attached file maxLength: 250 Size: type: string description: Size of the attachment in bytes pattern: ^[0-9]+$ maxLength: 50000 Created_Time: type: string format: date-time description: Timestamp when the attachment was created (ISO 8601 with timezone) Created_By: type: object description: User who created the attachment properties: id: type: string description: User ID pattern: ^[0-9]+$ maxLength: 50 name: type: string description: User display name maxLength: 250 email: type: string format: email description: User email address maxLength: 100 required: - id - name additionalProperties: false Modified_Time: type: string format: date-time description: Timestamp when the attachment was last modified (ISO 8601 with timezone) Modified_By: type: object description: User who last modified the attachment properties: id: type: string description: User ID pattern: ^[0-9]+$ maxLength: 50 name: type: string description: User display name maxLength: 250 email: type: string format: email description: User email address maxLength: 100 required: - id - name additionalProperties: false Owner: type: object description: Owner of the attachment properties: id: type: string description: Owner user ID pattern: ^[0-9]+$ maxLength: 50 name: type: string description: Owner display name maxLength: 250 email: type: string format: email description: Owner email address maxLength: 100 required: - id - name additionalProperties: false Parent_Id: type: object description: Parent record information properties: id: type: string description: Parent record ID pattern: ^[0-9]+$ maxLength: 50 name: type: string description: Parent record name maxLength: 250 required: - id - name additionalProperties: false $field_states: type: - object - 'null' description: Field states metadata $editable: type: boolean description: Indicates if the attachment is editable $file_id: type: - string - 'null' maxLength: 255 description: File identifier for the attachment $type: type: string description: Type of the attachment maxLength: 50 $se_module: type: string description: Source module name maxLength: 100 $state: type: string description: Current state of the attachment maxLength: 50 $link_url: type: - string - 'null' format: uri description: URL for link-type attachments. Null for file attachments. maxLength: 2000 $sharing_permission: type: string description: Sharing permission level for the attachment maxLength: 50 required: - id - Created_Time - Created_By - Modified_Time - Modified_By additionalProperties: false AttachmentListResponse: type: object description: Response containing list of attachments for a record properties: data: type: array description: Array of attachment objects maxItems: 1000 items: $ref: '#/components/schemas/AttachmentObject' info: $ref: '#/components/schemas/Info' required: - data - info additionalProperties: false AttachmentSuccessResponse: type: object description: Successful attachment operation response properties: data: type: array description: Array of upload results maxItems: 100 items: type: object description: Upload status details additionalProperties: false properties: code: type: string description: Response code enum: - SUCCESS details: type: object description: Details of the uploaded attachment additionalProperties: false properties: id: type: string description: Attachment identifier pattern: ^[0-9]+$ maxLength: 50 Modified_Time: type: string format: date-time description: Last modification timestamp Created_Time: type: string format: date-time description: Creation timestamp Modified_By: type: object description: User who last modified the attachment additionalProperties: false properties: id: type: string description: User identifier pattern: ^[0-9]+$ maxLength: 50 name: type: string description: User name maxLength: 250 required: - id - name Created_By: type: object description: User who created the attachment additionalProperties: false properties: id: type: string description: User identifier pattern: ^[0-9]+$ maxLength: 50 name: type: string description: User name maxLength: 250 required: - id - name required: - id - Modified_Time - Created_Time - Modified_By - Created_By message: type: string description: Success message enum: - attachment uploaded successfully status: type: string description: Operation status enum: - success required: - code - details - message - status required: - data additionalProperties: false BodySizeLimitError: type: object description: Error response for body size limit exceeded properties: status: type: string description: Error status indicator enum: - error code: type: string description: Error code enum: - BODY_SIZE_REACHED - FILE_SIZE_MORE_THAN_ALLOWED_SIZE message: type: string description: Error message enum: - The request body limit reached - Request body size exceeds the maximum limit of 100MB - Please check if the size of the file is in the correct range details: type: object description: Additional error details additionalProperties: false required: - status - code - message - details additionalProperties: false ErrorResponse: type: object description: Generic error response structure properties: status: type: string description: Error status indicator enum: - error code: type: string description: Error code enum: - INVALID_URL_PATTERN - MANDATORY_NOT_FOUND - INVALID_DATA - REQUIRED_PARAM_MISSING - INVALID_MODULE - INVALID_TOKEN - OAUTH_SCOPE_MISMATCH - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - SERVICE_UNAVAILABLE message: type: string description: Error message enum: - the given attachment URL is incorrect - required field not found - invalid data provided - One of the expected parameter is missing - the related id given seems to be invalid - the module name given seems to be invalid - invalid oauth token - required oauth scope is missing - the id given seems to be invalid - API rate limit exceeded. Please retry after some time - Internal Server Error - Service temporarily unavailable. Please try again later details: type: object description: Additional error details additionalProperties: false properties: param_name: type: string description: Name of the parameter causing the error maxLength: 100 resource_path_index: type: integer format: int32 description: Index of the resource path causing the error required: - status - code - message - details additionalProperties: false Info: type: object description: Pagination information for list responses properties: per_page: type: integer format: int32 description: Number of records per page minimum: 1 maximum: 200 next_page_token: type: - string - 'null' maxLength: 1024 description: Token to retrieve the next page of results count: type: integer format: int32 description: Number of records returned in the current response minimum: 0 page: type: integer format: int32 description: Current page number minimum: 1 previous_page_token: type: - string - 'null' maxLength: 1024 description: Token to retrieve the previous page of results page_token_expiry: type: - string - 'null' format: date-time description: Expiry timestamp for the page tokens more_records: type: boolean description: Indicates whether more records are available required: - per_page - next_page_token - count - page - previous_page_token - page_token_expiry - more_records additionalProperties: false responses: ServiceUnavailable: description: Service unavailable - server is temporarily unable to handle the request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' BadRequest: description: Bad request - invalid input parameters or request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: Too many requests - rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Unauthorized - authentication credentials are missing or invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error - unexpected server failure content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Not found - the specified record or attachment does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Forbidden - insufficient permissions to perform the operation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PayloadTooLarge: description: Request entity too large - file size exceeds 100MB limit content: application/json: schema: $ref: '#/components/schemas/BodySizeLimitError' parameters: Id: name: id in: path required: true description: The unique identifier of the attachment schema: type: string maxLength: 64 Fields: name: fields in: query required: false description: Specify the fields to retrieve schema: type: string maxLength: 100000 RecordId: name: recordId in: path required: true description: The unique identifier of the record schema: type: string maxLength: 64 ModuleApiName: name: moduleApiName in: path required: true description: The API name of the module schema: type: string maxLength: 64 securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter