freshdesk Contacts API

openapi: 3.1.0
info:
  title: Freshdesk REST Agents Contacts API
  description: The Freshdesk REST API (v2) provides programmatic access to helpdesk data and operations within Freshdesk, a customer support platform by Freshworks. It exposes endpoints for managing tickets, contacts, companies, agents, groups, conversations, products, email configurations, SLA policies, business hours, time entries, satisfaction ratings, solution categories, solution folders, solution articles, and more. The API uses JSON for request and response payloads, supports API key-based authentication, and follows RESTful conventions for CRUD operations.
  version: '2.0'
  contact:
    name: Freshdesk Support
    url: https://support.freshdesk.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshdesk.com/api/v2
  description: Freshdesk Production Server
  variables:
    domain:
      default: yourdomain
      description: Your Freshdesk subdomain, e.g. if your helpdesk URL is acme.freshdesk.com, use acme.
security:
- basicAuth: []
tags:
- name: Contacts
  description: Manage contacts (end users) who submit support tickets.
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: List all contacts
      description: Retrieves a paginated list of contacts. Contacts can be filtered by email, phone, mobile, company, or state.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      - name: email
        in: query
        description: Filter contacts by email address.
        schema:
          type: string
          format: email
      - name: phone
        in: query
        description: Filter contacts by phone number.
        schema:
          type: string
      - name: mobile
        in: query
        description: Filter contacts by mobile number.
        schema:
          type: string
      - name: company_id
        in: query
        description: Filter contacts by company ID.
        schema:
          type: integer
          format: int64
      - name: state
        in: query
        description: Filter contacts by state.
        schema:
          type: string
          enum:
          - blocked
          - deleted
          - unverified
          - verified
      responses:
        '200':
          description: Successfully retrieved list of contacts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContact
      summary: Create a contact
      description: Creates a new contact in the helpdesk. At minimum, an email, phone, mobile, or twitter_id must be provided.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: Contact created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/{contact_id}:
    get:
      operationId: getContact
      summary: View a contact
      description: Retrieves the details of a specific contact by ID.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactId'
      responses:
        '200':
          description: Successfully retrieved contact details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateContact
      summary: Update a contact
      description: Updates the properties of an existing contact.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: Soft-deletes a contact. The contact can be restored later.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactId'
      responses:
        '204':
          description: Contact deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contact_id}/restore:
    put:
      operationId: restoreContact
      summary: Restore a deleted contact
      description: Restores a previously soft-deleted contact.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/contactId'
      responses:
        '204':
          description: Contact restored successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/merge:
    post:
      operationId: mergeContacts
      summary: Merge contacts
      description: Merges secondary contacts into a primary contact. The secondary contacts are deleted and their tickets are reassigned to the primary.
      tags:
      - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - primary_contact_id
              - secondary_contact_ids
              properties:
                primary_contact_id:
                  type: integer
                  format: int64
                  description: ID of the primary contact to merge into.
                secondary_contact_ids:
                  type: array
                  items:
                    type: integer
                    format: int64
                  description: IDs of secondary contacts to merge.
      responses:
        '200':
          description: Contacts merged successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/export:
    post:
      operationId: exportContacts
      summary: Export contacts
      description: Initiates an export of contacts and returns a job ID to check status.
      tags:
      - Contacts
      responses:
        '202':
          description: Export job initiated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Export job ID.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contact_fields:
    get:
      operationId: listContactFields
      summary: List all contact fields
      description: Retrieves all default and custom contact fields.
      tags:
      - Contacts
      responses:
        '200':
          description: Successfully retrieved contact fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Field'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication failed or credentials were not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the contact.
        name:
          type: string
          description: Full name of the contact.
        email:
          type: string
          format: email
          description: Primary email address of the contact.
        phone:
          type: string
          nullable: true
          description: Phone number of the contact.
        mobile:
          type: string
          nullable: true
          description: Mobile phone number of the contact.
        twitter_id:
          type: string
          nullable: true
          description: Twitter handle of the contact.
        address:
          type: string
          nullable: true
          description: Physical address of the contact.
        description:
          type: string
          nullable: true
          description: Description or notes about the contact.
        job_title:
          type: string
          nullable: true
          description: Job title of the contact.
        language:
          type: string
          nullable: true
          description: Language preference of the contact.
        time_zone:
          type: string
          nullable: true
          description: Time zone of the contact.
        company_id:
          type: integer
          format: int64
          nullable: true
          description: ID of the company the contact belongs to.
        active:
          type: boolean
          description: Whether the contact is active.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the contact.
        other_emails:
          type: array
          items:
            type: string
            format: email
          description: Additional email addresses for the contact.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom fields set on the contact.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the contact was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the contact was last updated.
    Field:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the field.
        name:
          type: string
          description: Internal name of the field.
        label:
          type: string
          description: Display label of the field.
        description:
          type: string
          nullable: true
          description: Description of the field.
        type:
          type: string
          description: Data type of the field.
        default:
          type: boolean
          description: Whether this is a default system field.
        required_for_closure:
          type: boolean
          description: Whether this field must be filled before closing a ticket.
        required_for_agents:
          type: boolean
          description: Whether this field is required when agents create tickets.
        required_for_customers:
          type: boolean
          description: Whether this field is required when customers create tickets.
        choices:
          type: array
          items:
            type: string
          nullable: true
          description: Available choices for dropdown fields.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the field was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the field was last updated.
    ContactCreate:
      type: object
      properties:
        name:
          type: string
          description: Full name of the contact.
        email:
          type: string
          format: email
          description: Email address of the contact.
        phone:
          type: string
          description: Phone number of the contact.
        mobile:
          type: string
          description: Mobile phone number of the contact.
        twitter_id:
          type: string
          description: Twitter handle of the contact.
        address:
          type: string
          description: Physical address of the contact.
        description:
          type: string
          description: Description or notes about the contact.
        job_title:
          type: string
          description: Job title of the contact.
        language:
          type: string
          description: Language preference of the contact.
        time_zone:
          type: string
          description: Time zone of the contact.
        company_id:
          type: integer
          format: int64
          description: ID of the company to associate.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate with the contact.
        other_emails:
          type: array
          items:
            type: string
            format: email
          description: Additional email addresses.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
    Error:
      type: object
      properties:
        description:
          type: string
          description: Human-readable error description.
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error.
              message:
                type: string
                description: Error message for the field.
              code:
                type: string
                description: Error code.
  parameters:
    perPage:
      name: per_page
      in: query
      description: Number of results per page (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    contactId:
      name: contact_id
      in: path
      required: true
      description: Unique identifier of the contact.
      schema:
        type: integer
        format: int64
    page:
      name: page
      in: query
      description: Page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Freshdesk uses API key-based authentication. Pass your API key as the username with any string (e.g. X) as the password using HTTP Basic Authentication.
externalDocs:
  description: Freshdesk API Documentation
  url: https://developers.freshdesk.com/api/