Zoho CRM Attachments API

openapi: 3.2.0
info:
  title: Attachments API
  description: Attachments
  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: 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:
    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
    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
    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
    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
    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
  responses:
    TooManyRequests:
      description: Too many requests - rate limit exceeded
      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'
    ServiceUnavailable:
      description: Service unavailable - server is temporarily unable to handle the request
      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'
    BadRequest:
      description: Bad request - invalid input parameters or request body
      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'
    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:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            ZohoCRM.modules.attachments.ALL: Full access to attachments
            ZohoCRM.modules.attachments.READ: Read access to attachments
            ZohoCRM.modules.attachments.DELETE: Delete access to attachments
            ZohoCRM.modules.attachments.UPDATE: Update access to attachments
            ZohoCRM.modules.attachments.CREATE: Create access to attachments