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://dev.frontapp.com/docs/query-object-q) with a property `statuses`, whose value should be a list of conversation statuses (`assigned`, `unassigned`, `archived`, or `trashed`). If ticketing is enabled, this endpoint accepts either `status_categories` (`open`, `waiting`, `resolved`) or `status_ids` as an alternative.' schema: type: string sortByCards: name: sort_by in: query description: Field used to sort the contacts. Either `created_at` or `updated_at`. schema: type: string cardQuery: name: q in: query description: '[Search query object](https://dev.frontapp.com/docs/query-object-q) with the optional properties `updated_after` and `updated_before`, whose value should be a timestamp in seconds with up to 3 decimal places.' schema: type: string limit: name: limit in: query description: Max number of results per [page](https://dev.frontapp.com/docs/pagination) schema: type: integer maximum: 100 example: 25 sortOrder: name: sort_order in: query description: Order by which results should be sorted schema: type: string enum: - asc - desc example: asc pageToken: name: page_token in: query description: Token to use to request the [next page](https://dev.frontapp.com/docs/pagination) schema: type: string example: https://yourCompany.api.frontapp.com/endpoint?limit=25&page_token=92f32bcd7625333caf4e0f8fc26d920c812f securitySchemes: http: type: http scheme: bearer bearerFormat: JWT x-api-id: front x-explorer-enabled: false x-proxy-enabled: true x-samples-enabled: true