Front Contacts API

openapi: 3.0.0
info:
  version: 1.0.0
  title: Channel Accounts Contacts API
  contact:
    name: Front Platform
    url: https://community.front.com
servers:
- url: https://api2.frontapp.com
security:
- http: []
tags:
- name: Contacts
paths:
  /contacts:
    get:
      summary: List contacts
      operationId: list-contacts
      description: 'List the contacts of the company.


        Required scope: `contacts:read`'
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/cardQuery'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByCards'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfContacts'
      x-required-scopes:
      - contacts:read
    post:
      summary: Create contact
      operationId: create-contact
      description: 'Create a new contact at the company level.


        Required scope: `contacts:write`'
      tags:
      - Contacts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
      responses:
        '201':
          $ref: '#/components/responses/contact'
      x-required-scopes:
      - contacts:write
  /contacts/merge:
    post:
      summary: Merge contacts
      operationId: merge-contacts
      description: "Merges the contacts specified into a single contact, deleting the merged-in contacts.\nIf a target contact ID is supplied, the other contacts will be merged into that one.\nOtherwise, some contact in the contact ID list will be treated as the target contact.\nMerge conflicts will be resolved in the following ways:\n  * name will prioritize manually-updated and non-private contact names\n  * descriptions will be concatenated and separated by newlines in order from\n    oldest to newest with the (optional) target contact's description first\n  * all handles, groups, links, and notes will be preserved\n  * other conflicts will use the most recently updated contact's value\n\n\nRequired scope: `contacts:write`"
      tags:
      - Contacts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeContacts'
      responses:
        '200':
          $ref: '#/components/responses/contact'
      x-required-scopes:
      - contacts:write
  /contacts/{contact_id}:
    get:
      summary: Get contact
      operationId: get-contact
      description: 'Fetch a contact.


        Required scope: `contacts:read`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: contact_id
        required: true
        description: The contact ID. Alternatively, you can supply the contact's source and handle as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: crd_123
      responses:
        '200':
          $ref: '#/components/responses/contact'
      x-required-scopes:
      - contacts:read
    patch:
      summary: Update a contact
      operationId: update-a-contact
      description: 'Updates a contact.


        Required scope: `contacts:write`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: contact_id
        required: true
        description: The contact ID. Alternatively, you can supply the contact's source and handle as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: crd_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - contacts:write
    delete:
      summary: Delete a contact
      operationId: delete-a-contact
      description: 'Delete a contact.


        Required scope: `contacts:delete`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: contact_id
        required: true
        description: The contact ID. Alternatively, you can supply the contact's source and handle as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: crd_123
      responses:
        '204':
          description: No content
      x-required-scopes:
      - contacts:delete
  /contacts/{contact_id}/conversations:
    get:
      summary: List contact conversations
      operationId: list-contact-conversations
      description: 'List the conversations for a contact in reverse chronological order (newest first). For more advanced filtering, see the [search endpoint](https://dev.frontapp.com/reference/conversations#search-conversations).



        Required scope: `conversations:read`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: contact_id
        required: true
        description: The Contact ID. Alternatively, you can supply the contact's source and handle as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: crd_123
      - $ref: '#/components/parameters/conversationQuery'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          $ref: '#/components/responses/listOfConversations'
      x-required-scopes:
      - conversations:read
  /teammates/{teammate_id}/contacts:
    get:
      summary: List teammate contacts
      operationId: list-teammate-contacts
      description: 'List the contacts of a teammate.


        Required scope: `contacts:read`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: teammate_id
        required: true
        description: The teammate ID. Alternatively, you can supply an email as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: tea_123
      - $ref: '#/components/parameters/cardQuery'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByCards'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfContacts'
      x-required-scopes:
      - contacts:read
    post:
      summary: Create teammate contact
      operationId: create-teammate-contact
      description: 'Create a contact for a teammate.


        Required scope: `contacts:write`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: teammate_id
        required: true
        description: The teammate ID. Alternatively, you can supply an email as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        schema:
          type: string
          default: tea_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
      responses:
        '201':
          $ref: '#/components/responses/contact'
      x-required-scopes:
      - contacts:write
  /teams/{team_id}/contacts:
    get:
      summary: List team contacts
      operationId: list-team-contacts
      description: 'List the contacts of a team (workspace).


        Required scope: `contacts:read`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: team_id
        required: true
        description: The team ID
        schema:
          type: string
          default: tim_123
      - $ref: '#/components/parameters/cardQuery'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByCards'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfContacts'
      x-required-scopes:
      - contacts:read
    post:
      summary: Create team contact
      operationId: create-team-contact
      description: 'Create a contact for a team (workspace).


        Required scope: `contacts:write`'
      tags:
      - Contacts
      parameters:
      - in: path
        name: team_id
        required: true
        description: The team ID
        schema:
          type: string
          default: tim_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContact'
      responses:
        '201':
          $ref: '#/components/responses/contact'
      x-required-scopes:
      - contacts:write
components:
  schemas:
    TagResponse:
      type: object
      description: A tag is a label that can be used to classify conversations.
      required:
      - _links
      - id
      - name
      - description
      - highlight
      - is_private
      - is_visible_in_conversation_lists
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy
            related:
              type: object
              properties:
                conversations:
                  type: string
                  description: Link to tag conversations
                  example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/conversations
                owner:
                  type: string
                  nullable: true
                  description: Link to tag owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6jydq
                parent_tag:
                  type: string
                  nullable: true
                  description: Link to parent tag
                  example: https://yourCompany.api.frontapp.com/tags/tag_3h07ym
                children:
                  type: string
                  nullable: true
                  description: Link to tag children
                  example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/children
        id:
          type: string
          description: Unique identifier of the tag
          example: tag_2oxhvy
        name:
          type: string
          description: Name of the tag
          example: Warehouse task
        description:
          type: string
          nullable: true
          description: Description of the tag
          example: Sitting on your biscuit, never having to risk it
        highlight:
          type: string
          nullable: true
          description: Highlight color or emoji of the tag. Null if the tag does not have a highlight.
          example: null
        is_private:
          type: boolean
          description: Whether or not the tag is individual
          example: false
        is_visible_in_conversation_lists:
          type: boolean
          description: Whether the tag is visible in conversation lists.
          example: true
        created_at:
          type: number
          description: Timestamp of tag create creation
          example: 1682538996.583
        updated_at:
          type: number
          description: Timestamp of the last tag update
          example: 1699575875.186
    ContactHandle:
      type: object
      required:
      - handle
      - source
      properties:
        handle:
          type: string
          description: Handle used to reach the contact.
          example: dwight@limitlesspaper.com
        source:
          type: string
          enum:
          - twitter
          - email
          - phone
          - facebook
          - intercom
          - front_chat
          - custom
          description: Source of the handle. Can be `email`, `phone`, `twitter`, `facebook`, `intercom`, `front_chat`, or `custom`.
          example: email
    Contact:
      properties:
        name:
          type: string
          description: Contact name
        description:
          type: string
          description: Contact description
        avatar:
          type: string
          description: 'Binary data of avatar. Must use `Content-Type: multipart/form-data` if specified. See [example](https://gist.github.com/hdornier/e04d04921032e98271f46ff8a539a4cb) or read more about [Attachments](https://dev.frontapp.com/docs/attachments-1).  Max 25 MB.'
          format: binary
        links:
          type: array
          description: List of all the links of the contact
          items:
            type: string
        group_names:
          type: array
          description: List of all the group names the contact belongs to. It will automatically create missing groups. ⚠️ Deprecated. Use `list_names` instead.
          items:
            type: string
        list_names:
          type: array
          description: List of all the contact list names the contact belongs to. It will automatically create missing groups
          items:
            type: string
        custom_fields:
          description: Custom fields for this contact. If you want to keep all custom fields the same when updating this resource, do not include any custom fields in the update. If you want to update custom fields, make sure to include all custom fields, not just the fields you want to add or update. If you send only the custom fields you want to update, the other custom fields will be erased. You can retrieve the existing custom fields before making the update to note the current fields.
          $ref: '#/components/schemas/CustomFieldParameter'
    MergeContacts:
      required:
      - contact_ids
      properties:
        target_contact_id:
          type: string
          description: Optional contact ID to merge the other contacts into.
        contact_ids:
          type: array
          description: Array of all the contact IDs of the contacts to be merged.  If a target contact id is provided and that contact id is not in this array, the length of this array must be between 1 and 49.  If no target contact id is provided or it is contained in this array, the length must be between 2 and 50.
          items:
            type: string
    ContactListResponses:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/contact_lists/grp_3j342
            related:
              type: object
              properties:
                contacts:
                  type: string
                  description: Link to contact list contacts
                  example: https://yourCompany.api.frontapp.com/contact_lists/grp_3j342/contacts
                owner:
                  type: string
                  description: Link to list owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_e35u
        id:
          type: string
          description: Unique identifier of the list
          example: grp_3j342
        name:
          type: string
          description: Name of the list
          example: Party Planning Committee
        is_private:
          type: boolean
          description: Whether or not the contact is individual
          example: false
    ContactResponse:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/contacts/crd_3cgz4ge"
            related:
              type: object
              properties:
                notes:
                  type: string
                  description: Link to contact notes
                  example: https://yourCompany.api.frontapp.com/contacts/crd_3cgz4ge/notes
                conversations:
                  type: string
                  description: Link to contact conversations
                  example: https://yourCompany.api.frontapp.com/contacts/crd_3cgz4ge/conversations
                owner:
                  type: string
                  description: Link to contact owner
                  example: null
        id:
          type: string
          description: Unique identifier of the contact
          example: crd_3cgz4ge
        name:
          type: string
          description: Contact name
          example: Dwight Schrute
        description:
          type: string
          description: Contact description
          example: Assistant to the regional manager
        avatar_url:
          type: string
          description: URL of the contact's avatar
          example: https://yourCompany.api.frontapp.com/contacts/crd_3cgz4ge/avatar-1673436467707
        links:
          type: array
          description: List of all the links of the contact
          items:
            type: string
            example:
            - https://shrutefarms.com
            - https://eatyourbeets.com
        groups:
          type: array
          deprecated: true
          description: List of the groups the contact belongs to. ⚠️ Deprecated. use `lists` instead.
          items:
            $ref: '#/components/schemas/ContactListResponses'
        lists:
          type: array
          description: List of the contact lists the contact belongs to.
          items:
            $ref: '#/components/schemas/ContactListResponses'
        handles:
          type: array
          description: List of the handles and sources with which the contact is reachable.
          items:
            $ref: '#/components/schemas/ContactHandle'
        custom_fields:
          description: Custom fields for this contact.
          $ref: '#/components/schemas/CustomFieldParameter'
        is_private:
          type: boolean
          description: Whether or not the contact is individual
          example: true
    ConversationResponse:
      type: object
      required:
      - _links
      - id
      - subject
      - status
      - ticket_ids
      - assignee
      - recipient
      - tags
      - links
      - custom_fields
      - is_private
      - scheduled_reminders
      - metadata
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q
            related:
              type: object
              properties:
                events:
                  type: string
                  description: Link to conversation events
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/events
                followers:
                  type: string
                  description: Link to conversation followers
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/followers
                messages:
                  type: string
                  description: Link to conversation messages
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/messages
                comments:
                  type: string
                  description: Link to conversation comments
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/comments
                inboxes:
                  type: string
                  description: Link to conversation inboxes
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/inboxes
                last_message:
                  type: string
                  description: Link to last message of the conversation
                  example: https://yourCompany.api.frontapp.com/messages/msg_1q15qmtq?referer=conversation
        id:
          type: string
          description: Unique identifier of the conversation
          example: cnv_yo1kg5q
        subject:
          type: string
          description: Subject of the message for email message
          example: How to prank Dwight Schrute
        status:
          type: string
          description: Status of the conversation
          enum:
          - archived
          - unassigned
          - deleted
          - assigned
          example: assigned
        status_id:
          type: string
          description: Unique identifier of the conversation status category, only present if ticketing is enabled
          example: sts_5x
        status_category:
          type: string
          description: Status category of the conversation
          enum:
          - open
          - waiting
          - resolved
          example: resolved
        ticket_ids:
          type: array
          description: List of ticket ids associated with the conversation
          items:
            type: string
          example:
          - TICKET-1
        assignee:
          nullable: true
          $ref: '#/components/schemas/TeammateResponse'
          description: Partial representation of the teammate assigned to the conversation
        recipient:
          nullable: true
          $ref: '#/components/schemas/RecipientResponse'
          description: Main recipient of the conversation
        tags:
          type: array
          description: List of the tags for this conversation
          items:
            $ref: '#/components/schemas/TagResponse'
        links:
          type: array
          description: List of the links for this conversation
          items:
            $ref: '#/components/schemas/LinkResponse'
        custom_fields:
          description: Custom fields for this conversation
          $ref: '#/components/schemas/CustomFieldParameter'
        created_at:
          type: number
          description: Timestamp at which the conversation was created.
          example: 1701292649.333
        updated_at:
          type: number
          description: Timestamp at which the conversation was last updated.
          example: 1701292649.333
        waiting_since:
          type: number
          description: Timestamp of the oldest unreplied message.
          example: 1701292649.333
        is_private:
          type: boolean
          description: Whether or not the conversation is private
          example: true
        scheduled_reminders:
          type: array
          description: List of scheduled (non-expired and non-canceled) reminders for this conversation
          items:
            $ref: '#/components/schemas/Reminder'
        metadata:
          type: object
          description: Optional metadata about the conversation
          properties:
            external_conversation_ids:
              type: array
              description: List of external_ids for partner channel associated with the conversation. Only present for partner channel token authenticated requests.
              example:
              - JS3949
              - JS9403
              items:
                type: string
    LinkResponse:
      type: object
      description: A link used to connect a Front conversation to an external resource.
      required:
      - _links
      - id
      - name
      - type
      - external_url
      - custom_fields
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/links/top_b2wpa
        id:
          type: string
          description: Unique identifier of the link
          example: top_b2wpa
        name:
          type: string
          description: Display name of the link
          example: JIRA-SCRAN-4567
        type:
          type: string
          description: Type of the link. Typically associated with the underlying link provider (if known)
          example: app_2f76b9ac738de158
        external_url:
          type: string
          description: Underlying identifying external URL of the link
          example: https://dundermifflin.atlassian.net/browse/PB-SCRAN-4567
        custom_fields:
          description: Custom fields for this link
          $ref: '#/components/schemas/CustomFieldParameter'
    CreateContact:
      required:
      - handles
      allOf:
      - $ref: '#/components/schemas/Contact'
      - type: object
        properties:
          handles:
            type: array
            description: List of the handles for this contact. Each handle object should include `handle` and `source` fields.
            items:
              $ref: '#/components/schemas/ContactHandle'
    RecipientResponse:
      type: object
      required:
      - _links
      - name
      - handle
      - role
      properties:
        _links:
          type: object
          properties:
            related:
              type: object
              properties:
                contact:
                  type: string
                  nullable: true
                  description: Link to recipient contact
                  example: https://yourCompany.api.frontapp.com/contacts/crd_2njtoem
        name:
          type: string
          nullable: true
          description: Name of the recipient.
          example: Phyllis Lapin-Vance
        handle:
          type: string
          description: Handle of the contact. Can be any string used to uniquely identify the contact
          example: purpleboss@limitlesspaper.com
        role:
          type: string
          description: Role of the recipient
          enum:
          - from
          - to
          - cc
          - bcc
          - reply-to
          example: cc
    CustomFieldParameter:
      type: object
      description: An object whose key is the `name` property defined for the custom field in the Front UI. The value of the key must use the same `type` specified for the custom field, as described in https://dev.frontapp.com/reference/custom-fields
      example:
        city: London, UK
        isVIP: true
        renewal_date: 1525417200
        sla_time: 90
        owner: leela@planet-express.com
        replyTo: inb_55c8c149
        Job Title: firefighter
    TeammateResponse:
      type: object
      description: A teammate is a user in Front.
      required:
      - _links
      - id
      - email
      - username
      - first_name
      - last_name
      - license_type
      - is_admin
      - is_available
      - is_blocked
      - type
      - custom_fields
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a
            related:
              type: object
              properties:
                inboxes:
                  type: string
                  description: Link to teammate's inboxes
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/inboxes
                conversations:
                  type: string
                  description: Link to teammate's conversations
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/conversations
                botSource:
                  type: string
                  description: Link to the source resource of the bot (e.g. rule)
                  example: https://yourCompany.api.frontapp.com/rules/rul_6r55a
        id:
          type: string
          description: Unique identifier of the teammate
          example: tea_6r55a
        email:
          type: string
          description: Email address of the teammate
          example: michael.scott@dundermifflin.com
        username:
          type: string
          description: Username of the teammate (used for "@" mentions)
          example: PrisonMike
        first_name:
          type: string
          description: First name of the teammate
          example: Michael
        last_name:
          type: string
          description: Last name of the teammate
          example: Scott
        is_admin:
          type: boolean
          description: Whether or not the teammate is an admin in your company
          example: true
        is_available:
          type: boolean
          description: Whether or not the teammate is available
          example: false
        is_blocked:
          type: boolean
          description: Whether or not the teammate account has been blocked
          example: false
        type:
          type: string
          description: "Type of the teammate, normal teammates are denoted as \"user\", while visitors are denoted as \"visitor\".\nBot users are denoted by their parent resource type.\nThe following bot types are available:\n  * rule: acting on behalf of a Rule, author of comments and drafts\n  * macro: acting on behalf of a Macro, author of comments and drafts\n  * API: acting on behalf of OAuth clients\n  * integration: acting on behalf of an Integration\n  * CSAT: used for authoring CSAT response comments\n"
          enum:
          - user
          - visitor
          - rule
          - macro
          - API
          - integration
          - CSAT
        custom_fields:
          description: Custom fields for this teammate
          $ref: '#/components/schemas/CustomFieldParameter'
    Reminder:
      type: object
      required:
      - _links
      properties:
        _links:
          type: object
          properties:
            related:
              type: object
              properties:
                owner:
                  type: string
                  description: Link to conversation owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a
        created_at:
          type: number
          description: Timestamp at which the conversation reminder has been created
          example: 1701806790.536
        scheduled_at:
          type: number
          description: Timestamp that the conversation reminder has been scheduled for
          example: 1701874800
        updated_at:
          type: number
          description: Timestamp at which the conversation reminder has been updated
          example: 1701806790.536
  responses:
    contact:
      description: A contact
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ContactResponse'
    listOfConversations:
      description: Array of conversations
      content:
        application/json:
          schema:
            type: object
            properties:
              _pagination:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: Link to next [page of results](https://dev.frontapp.com/docs/pagination)
                    example: https://yourCompany.api.frontapp.com/conversations?page_token=ce787da6f075740cf187d926f5e9f612bc7875763a8dd37d5
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/conversations
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationResponse'
    listOfContacts:
      description: Array of contacts
      content:
        application/json:
          schema:
            type: object
            properties:
              _pagination:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: Link to next [page of results](https://dev.frontapp.com/docs/pagination)
                    example: https://yourCompany.api.frontapp.com/contacts?page_token=e0b5767cb0f1100743d46f67fcd765caac2ed
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/contacts
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/ContactResponse'
  parameters:
    conversationQuery:
      name: q
      in: query
      description: '[Search query object](https://de

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/front/refs/heads/main/openapi/front-contacts-api-openapi.yml