openapi: 3.0.0 info: version: 1.0.0 title: Channel Accounts Analytics API contact: name: Front Platform url: https://community.front.com servers: - url: https://api2.frontapp.com security: - http: [] tags: - name: Analytics paths: /analytics/exports: post: summary: Create a new analytics export operationId: create-analytics-export description: 'Create a new analytics export of messages or events (activities) over a specific time span. The export will be executed asynchronously. The response will include a link that can be used to retrieve the export status & result. Refer to the [Analytics](https://dev.frontapp.com/reference/analytics) topic for details about specific metrics. Required scope: `analytics:read`' tags: - Analytics requestBody: content: application/json: schema: $ref: '#/components/schemas/AnalyticsExportRequest' responses: '201': description: An analytics export. content: application/json: schema: $ref: '#/components/schemas/AnalyticsExportResponse' x-required-scopes: - analytics:read /analytics/exports/{export_id}: get: summary: Fetch an analytics export operationId: get-analytics-export description: 'Fetch an analytics exports. Refer to the [Analytics](https://dev.frontapp.com/reference/analytics) topic for details about specific metrics. Required scope: `analytics:read`' tags: - Analytics parameters: - in: path name: export_id required: true description: The export ID. schema: type: string default: exp_123 responses: '200': description: An analytics export. content: application/json: schema: $ref: '#/components/schemas/AnalyticsExportResponse' x-required-scopes: - analytics:read /analytics/reports: post: summary: Create a new analytics report operationId: create-analytics-report description: 'Create a new analytics report for a set of metrics over a specific time span. Different filters (e.g. Inbox v Tag v Teammates) will be joined with AND logic, but the IDs within a filter will be joined with OR logic (e.g. Inbox A or Inbox B, Tag A or Tag B). The report will be executed asynchronously. The response will include a link that can be used to retrieve the report status & result. Refer to the [Analytics](https://dev.frontapp.com/reference/analytics) topic for details about specific metrics. Required scope: `analytics:read`' tags: - Analytics requestBody: content: application/json: schema: $ref: '#/components/schemas/AnalyticsReportRequest' responses: '201': description: An analytics report. content: application/json: schema: $ref: '#/components/schemas/AnalyticsReportResponse' x-required-scopes: - analytics:read /analytics/reports/{report_uid}: get: summary: Fetch an analytics report operationId: get-analytics-report description: 'Fetch an analytics report. Refer to the [Analytics](https://dev.frontapp.com/reference/analytics) topic for details about specific metrics. Required scope: `analytics:read`' tags: - Analytics parameters: - in: path name: report_uid required: true description: The report UID. schema: type: string default: 723ec32796f12c6f05f6b124d8ef76191a38cec990e0f65d549206c51373f1a0 responses: '200': description: An analytics report. content: application/json: schema: $ref: '#/components/schemas/AnalyticsReportResponse' x-required-scopes: - analytics:read components: schemas: AnalyticsActivitiesColumns: type: string enum: - Activity ID - Type - Source - Message ID - Segment ID - Conversation ID - Ticket IDs - Segment - Segment start - Segment end - Direction - Status - Status at activity time - Inbox - Inbox API ID - Inbox at activity time - Inbox API IDs at activity time - Previous inbox IDs - Message date - Autoreply - Reaction time - Total reply time - Handle time - Response time - Stage resolution time - Replies to resolution - Ticket resolution time - Ticket replies to resolution - Attributed to - Assignee - Author - Contact name - Contact handle - Account names - From - To - Cc - Bcc - Extract - Tags - Tag API IDs - Tags at activity time - Tag API IDs at activity time - Tag application duration - Activity API ID - Message API ID - Comment API ID - Conversation API ID - Message original ID - New Conversation - First response - Business hours - Subject - Account name - Survey rating - Survey comment - Segment closed - Segment contains messages - Last segment activity - Added tag - Added tag API ID - Removed tag - Removed tag API ID - Segment cumulative teammates - Ticket status name - Ticket status category - Time spent in Ticket Status - Transitions to Ticket Status - Smart QA score - Custom Field - Updated Custom Field AccountIds: type: object required: - account_ids properties: account_ids: type: array items: $ref: '#/components/schemas/ResourceID' AnalyticsScalar: type: object required: - id - type - value properties: id: $ref: '#/components/schemas/AnalyticsMetricId' type: $ref: '#/components/schemas/AnalyticsScalarType' value: $ref: '#/components/schemas/AnalyticsScalarValue' ResourceID: type: string AnalyticsExportRequest: discriminator: propertyName: type mapping: messages: '#/components/schemas/AnalyticsMessagesExportColumns' events: '#/components/schemas/AnalyticsActivitiesExportsColumns' oneOf: - $ref: '#/components/schemas/AnalyticsMessagesExportColumns' - $ref: '#/components/schemas/AnalyticsActivitiesExportsColumns' properties: type: type: string description: The type of export to create. The type you specify determines which columns are available for the export. enum: - messages - events start: type: number description: Start time of the data to include in the export (seconds since 1970-01-01T00:00:00+00). Will be rounded down to the start of the day. end: type: number description: End time of the data to include in the export (seconds since 1970-01-01T00:00:00+00). Will be rounded up to the end of the day. timezone: type: string description: '[IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of the timezone to format the dates with. If omitted, the export will use Etc/UTC.' filters: $ref: '#/components/schemas/AnalyticsFilters' required: - start - end - type AnalyticsActivitiesParameterizedColumns: type: string oneOf: - type: string pattern: ^Time spent in Ticket Status:\d+$ - type: string pattern: ^Transitions to Ticket Status:\d+$ - type: string pattern: ^Smart QA score:\w+$ - type: string pattern: ^Custom Field:\d+$ - type: string pattern: ^Updated Custom Field:\d+$ AnalyticsReportResponse: type: object required: - _links - uid - status - progress - metrics properties: _links: type: object properties: self: type: string description: Link to analytics job. example: https://yourCompany.api.frontapp.com/analytics/reports/b45efa66237cc453252d9019449c7a64f5cfdb491b6c2c1d6df33c1050d60e33 uid: type: string description: The UID of the analytics report example: b45efa66237cc453252d9019449c7a64f5cfdb491b6c2c1d6df33c1050d60e33 status: type: string enum: - running - done - failed description: Status of the report. example: done progress: type: integer minimum: 0 maximum: 100 description: Number ranging from 0 to 100 corresponding to the percentage of the analytics processed. example: 100 metrics: type: array description: The metrics computed for the report. items: $ref: '#/components/schemas/AnalyticsScalar' AnalyticsActivitiesExportsColumns: required: - columns type: object properties: columns: type: array description: "List of the columns to include in the export. In addition to the\npredefined columns, you can also include parameterized columns by\nappending the parameter value to the column name, separated by a\ncolon (`:`). List of supported prefixes:\n - `Time spent in Ticket Status` (e.g., \"Time spent in Ticket Status:123\", where 123 is the ticket status tag ID)\n - `Transitions to Ticket Status` (e.g., \"Transitions to Ticket Status:123\", where 123 is the ticket status tag ID)\n - `Smart QA score` (e.g., \"Smart QA score:Comprehension\", where \"Comprehension\" is the Smart QA criteria ID)\n - `Custom Field` (e.g., \"Custom Field:456\", where 456 is the custom field ID)\n - `Updated Custom Field` (e.g., \"Updated Custom Field:456\", where 456 is the custom field ID)\n\nExample: `[\"Message ID\", \"Time spent in Ticket Status:123\", \"Smart QA score:Comprehension\"]`\n" items: oneOf: - $ref: '#/components/schemas/AnalyticsActivitiesColumns' - $ref: '#/components/schemas/AnalyticsActivitiesParameterizedColumns' default: - Activity ID - Type - Source - Message ID - Segment ID - Conversation ID - Ticket IDs - Segment - Segment start - Segment end - Direction - Status - Status at activity time - Inbox - Inbox API ID - Inbox at activity time - Inbox API IDs at activity time - Previous inbox IDs - Message date - Autoreply - Reaction time - Total reply time - Handle time - Response time - Ticket resolution time - Ticket replies to resolution - Attributed to - Assignee - Author - Contact name - Contact handle - Account names - From - To - Cc - Bcc - Extract - Tags - Tag API IDs - Tags at activity time - Tag API IDs at activity time - Tag application duration - Activity API ID - Message API ID - Comment API ID - Conversation API ID - Message original ID - New Conversation - First response - Business hours - Subject - Account name - Survey rating - Survey comment - Segment closed - Segment contains messages - Last segment activity - Added tag - Added tag API ID - Removed tag - Removed tag API ID - Segment cumulative teammates AnalyticsMetricId: type: string enum: - avg_csat_survey_response - avg_first_response_time - avg_handle_time - avg_replies_to_resolution - avg_resolution_time - avg_response_time - avg_sla_breach_time - avg_total_reply_time - new_segments_count - num_active_segments_full - num_archived_segments - num_archived_segments_with_reply - num_csat_survey_response - num_messages_received - num_messages_sent - num_sla_breach - pct_csat_survey_satisfaction - pct_resolved_on_first_reply - pct_tagged_conversations - num_closed_segments - num_open_segments_start - num_open_segments_end - num_resolved_segments - num_unresolved_active_segments - num_workload_segments TagIds: type: object required: - tag_ids properties: tag_ids: type: array items: $ref: '#/components/schemas/ResourceID' AnalyticsExportResponse: type: object required: - _links - id - status - progress - filters properties: _links: type: object properties: self: type: string description: Link to analytics export example: https://yourCompany.api.frontapp.com/analytics/exports/exp_o9y1a id: type: string description: The public ID of the analytics export example: exp_o9y1a status: type: string enum: - running - done - too_big - failed description: Status of the analytics example: running progress: type: integer minimum: 0 maximum: 100 description: Number ranging from 0 to 100 corresponding to the percentage of the analytics processed. example: 20 url: type: string description: The URL from which the export data can be downloaded. Only displays after you make a GET request to the link included in the POST response. example: https://api.frontapp.com/analytics/exports/exp_o9y1a/download filename: type: string description: The filename of the export with extension included. Only displays after you make a GET request to the link included in the POST response. example: export-messages-yourCompany-2023-07-19-212d-e55df0.csv size: type: number nullable: true description: Size (in bytes) of the export data. Only displays after you make a GET request to the link included in the POST response. example: 26639 created_at: type: number description: Timestamp (in seconds) at which the export was requested. example: 1703103649.159 filters: $ref: '#/components/schemas/AnalyticsFilters' ChannelIds: type: object required: - channel_ids properties: channel_ids: type: array items: $ref: '#/components/schemas/ResourceID' AnalyticsReportRequest: properties: start: type: number description: Start time of the data to include in the export (seconds since 1970-01-01T00:00:00+00). Will be rounded down to the start of the day. end: type: number description: End time of the data to include in the export (seconds since 1970-01-01T00:00:00+00). Will be rounded up to the end of the day. timezone: type: string description: '[IANA name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of the timezone to format the dates with. If omitted, the export will use Etc/UTC.' filters: $ref: '#/components/schemas/AnalyticsFilters' metrics: type: array description: List of the metrics required. items: $ref: '#/components/schemas/AnalyticsMetricId' required: - start - end - metrics AnalyticsScalarType: type: string example: number enum: - number - percentage - string - duration - resource InboxIds: type: object required: - inbox_ids properties: inbox_ids: type: array items: $ref: '#/components/schemas/ResourceID' AnalyticsScalarValue: oneOf: - type: integer - type: string - type: object properties: label: type: string resource: type: object required: - id - _links properties: id: type: string _links: type: object properties: self: type: string description: Link to a resource. nullable: true description: The value of a scalar metric. AnalyticsFilters: description: Resources to compute the analytics for. Defaults to all. anyOf: - $ref: '#/components/schemas/TagIds' - $ref: '#/components/schemas/TeammateIds' - $ref: '#/components/schemas/ChannelIds' - $ref: '#/components/schemas/InboxIds' - $ref: '#/components/schemas/TeamIds' - $ref: '#/components/schemas/AccountIds' TeamIds: type: object required: - team_ids properties: team_ids: type: array items: $ref: '#/components/schemas/ResourceID' TeammateIds: type: object required: - teammate_ids properties: teammate_ids: type: array items: $ref: '#/components/schemas/ResourceID' AnalyticsMessagesColumns: type: string enum: - Message ID - Segment ID - Conversation ID - Ticket IDs - Segment - Direction - Status - Inbox - Inbox API ID - Inbox at activity time - Inbox API IDs at activity time - Message date - Autoreply - Reaction time - Total reply time - Handle time - Response time - Attributed to - Assignee - Author - Contact name - Contact handle - Account names - From - To - Cc - Bcc - Extract - Tags - Tag API IDs - Message API ID - Conversation API ID - New Conversation - First response - Business hours - Subject - Segment start - Segment end - Segment closed - Last segment activity - Segment cumulative teammates - Ticket status name - Ticket status category - Custom Field AnalyticsMessagesExportColumns: required: - columns type: object properties: columns: type: array description: 'List of the columns to include in the export. ' items: $ref: '#/components/schemas/AnalyticsMessagesColumns' default: - Message ID - Segment ID - Conversation ID - Ticket IDs - Segment - Direction - Status - Inbox - Inbox API ID - Inbox at activity time - Inbox API IDs at activity time - Message date - Autoreply - Reaction time - Total reply time - Handle time - Response time - Attributed to - Assignee - Author - Contact name - Contact handle - Account names - From - To - Cc - Bcc - Extract - Tags - Tag API IDs - Message API ID - Conversation API ID - New Conversation - First response - Business hours - Subject - Segment start - Segment end - Segment closed - Last segment activity - Segment cumulative teammates securitySchemes: http: type: http scheme: bearer bearerFormat: JWT x-api-id: front x-explorer-enabled: false x-proxy-enabled: true x-samples-enabled: true