Smartling Reports API
The Reports API allows to request various reports available on Smartling platform and specify additional filtering criteria to narrow down data returned by the reports.
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: support@smartling.com
description: 'Before you begin using the Smartling APIs, we recommend going through our [Developer documentation](https://help.smartling.com/hc/en-us/categories/1260801686149).
'
termsOfService: https://www.smartling.com/legal
title: Smartling REST API Reference Account & Projects Reports API
version: 2.0.0
x-logo:
url: smartling_logo.png
servers:
- url: https://api.smartling.com
tags:
- name: Reports
description: 'The Reports API allows to request various reports available on Smartling
platform and specify additional filtering criteria to narrow down data
returned by the reports.'
paths:
/reports-api/v3/word-count:
get:
summary: Get Word Count Report
description: Word Count report data for the specified parameters.
tags:
- Reports
operationId: getWordCountReport
parameters:
- description: A parameter to limit words processed on or after the ```startDate```, in America/New_York timezone.
in: query
name: startDate
required: true
schema:
format: YYYY-MM-DD
type: string
- description: A parameter to limit words processed on or before the ```endDate```, in America/New_York timezone.
in: query
name: endDate
required: true
schema:
format: YYYY-MM-DD
type: string
- description: The account’s unique identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: query
name: accountUid
required: true
schema:
type: string
- description: Optional array of unique project identifiers. This can be found in the Smartling Dashboard under Account Settings > API.
in: query
name: projectIds
required: false
schema:
items:
type: string
type: array
- description: Optional parameter to filter to the specified list of translation jobs.
in: query
name: jobUids
required: false
schema:
items:
type: string
type: array
- description: Optional parameter of unique agency identifier.
in: query
name: agencyUid
required: false
schema:
type: string
- description: Optional parameter to filter to the specified list of translation resources.
in: query
name: userUids
required: false
schema:
items:
type: string
type: array
- description: Optional parameter to filter to the specified list of translation locale IDs.
in: query
name: targetLocaleIds
required: false
schema:
items:
type: string
type: array
- description: "Optional parameter to filter to the specified list of workflow step types.\n\nThe supported list of workflow step types is:\n\n - Translation\n\n - Edit\n\n - Review\n\n - Post-Edit\n\n - Transcreation\n\n - Transcreation review\n\n - AI Review\n\n - Quality Evaluation\n\n - LQA\n\n - Internal Review\n\n - Desktop Publishing\n\n - AI Translation\n\n - Light Post-Edit"
in: query
name: workflowStepTypes
required: false
schema:
items:
type: string
type: array
- description: "Optional comma-separated list of fields names to be returned by the endpoint. If this parameter is not set then the list of fields returned is defined by `include...` parameters.\n\nBoth `fields` and `include...` parameters are not allowed at the same time.\n\nThe supported list of fields names is:\n\n - accountUid\n\n - accountName\n\n - projectId\n\n - projectName\n\n - targetLocaleId\n\n - targetLocale\n\n - jobUid\n\n - jobName\n\n - jobReferenceNumber\n \n - jobNumber\n\n - translationResourceUid\n\n - translationResourceName\n\n - agencyUid\n\n - agencyName\n\n - workflowStepType\n\n - workflowStepUid\n\n - workflowStepName\n\n - fuzzyProfileName\n\n - fuzzyTier\n\n - wordCount\n\n - weightedWordCount\n\n - characterCount. Please note: the column shows correct data since 2022-10-01.\n"
in: query
name: fields
required: false
schema:
type: string
- description: 'Optional parameter to specify whether the report should group word count by translation resource name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeTranslationResource
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by translation job name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeJob
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by translation job and include reference number in the response.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeJobReferenceNumber
required: false
deprecated: true
schema:
default: false
type: boolean
- description: "Optional parameter to specify whether the report should group word count by translation job and include job number in the response. \nDeprecated, use parameter `fields` instead.\n"
in: query
name: includeJobNumber
required: false
deprecated: true
schema:
default: false
type: boolean
- description: "Optional parameter to specify whether the report should group word count by fuzzy match profile and tier. \n\nDeprecated, use parameter `fields` instead.\n"
in: query
name: includeFuzzyMatchProfile
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by workflow step uid and name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeWorkflowStep
required: false
deprecated: true
schema:
default: false
type: boolean
- description: Standard Smartling limit and offset to paginate through results. Default value is 10000.
in: query
name: limit
required: false
schema:
default: 10000
maximum: 10000
minimum: 0
type: integer
- description: Standard Smartling limit and offset to paginate through results. Default value is 0.
in: query
name: offset
required: false
schema:
default: 0
maximum: 10000
minimum: 0
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WordCountResponse'
examples:
response:
value:
response:
code: SUCCESS
data:
items:
- accountName: Test Account
accountUid: 35a84f71
agencyName: Test Agency 1
agencyUid: 0ed85b93
fuzzyProfileName: Default
fuzzyTier: 85 - 94.9%
jobName: Translation Job 1
jobUid: f12ad8e9
jobReferenceNumber: Job reference number
projectId: ba952f4c
projectName: Test Project 1
targetLocaleId: es-ES
targetLocaleName: Spanish (Spain)
translationResourceName: Agency Translator 5
translationResourceUid: da57302e
weightedWordCount: 4
wordCount: 20
characterCount: 101
workflowStepType: Translation
workflowStepUid: lk3gh7zr20ao
workflowStepName: Translation
- accountName: Test Account
accountUid: 35a84f71
agencyName: Test Agency 2
agencyUid: 4d6230e1
fuzzyProfileName: Default
fuzzyTier: 85 - 94.9%
jobName: Translation Job 1
jobUid: f12ad8e9
jobReferenceNumber: Job reference number
projectId: ba952f4c
projectName: Test Project 1
targetLocaleId: es-ES
targetLocale: Spanish (Spain)
translationResourceName: Agency Editor 12
translationResourceUid: 5eb90a14
weightedWordCount: 20
wordCount: 20
characterCount: 101
workflowStepType: Edit
workflowStepUid: ac7ac1bd15bf
workflowStepName: Edit
resultsTruncated: false
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
/reports-api/v3/word-count/csv:
get:
summary: Export Word Count in CSV format
description: Export Word Count report in CSV format.
tags:
- Reports
operationId: exportWordCountReport
parameters:
- description: A parameter to limit words processed on or after the ```startDate```, in America/New_York timezone.
in: query
name: startDate
required: true
schema:
format: YYYY-MM-DD
type: string
- description: A parameter to limit words processed on or before the ```endDate```, in America/New_York timezone.
in: query
name: endDate
required: true
schema:
format: YYYY-MM-DD
type: string
- description: The account’s unique identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: query
name: accountUid
required: true
schema:
type: string
- description: Optional array of unique project identifiers. This can be found in the Smartling Dashboard under Account Settings > API.
in: query
name: projectIds
required: false
schema:
items:
type: string
type: array
- description: Optional parameter to filter to the specified list of translation jobs.
in: query
name: jobUids
required: false
schema:
items:
type: string
type: array
- description: Optional parameter of unique agency identifier.
in: query
name: agencyUid
required: false
schema:
type: string
- description: Optional parameter to filter to the specified list of translation resources.
in: query
name: userUids
required: false
schema:
items:
type: string
type: array
- description: Optional parameter to filter to the specified list of translation locale IDs.
in: query
name: targetLocaleIds
required: false
schema:
items:
type: string
type: array
- description: "Optional parameter to filter to the specified list of workflow step types.\n\nThe supported list of workflow step types is:\n\n - Translation\n\n - Edit\n\n - Review\n\n - Post-Edit\n\n - Transcreation\n\n - Transcreation review\n\n - AI Review\n\n - Quality Evaluation\n\n - LQA\n\n - Internal Review\n\n - Desktop Publishing\n\n - AI Translation\n\n - Light Post-Edit"
in: query
name: workflowStepTypes
required: false
schema:
items:
type: string
type: array
- description: "Optional comma-separated list of fields names to be returned by the endpoint. If this parameter is not set then the list of fields returned is defined by `include...` parameters.\n\nBoth `fields` and `include...` parameters are not allowed at the same time.\n\nThe supported list of fields names is:\n\n - accountUid\n\n - accountName\n\n - projectId\n\n - projectName\n\n - targetLocaleId\n\n - targetLocale\n\n - jobUid\n\n - jobName\n\n - jobReferenceNumber\n \n - jobNumber\n\n - translationResourceUid\n\n - translationResourceName\n\n - agencyUid\n\n - agencyName\n\n - workflowStepType\n\n - workflowStepUid\n\n - workflowStepName\n\n - fuzzyProfileName\n\n - fuzzyTier\n\n - wordCount\n\n - weightedWordCount\n\n - characterCount. Please note: the column shows correct data since 2022-10-01.\n"
in: query
name: fields
required: false
schema:
type: string
- description: 'Optional parameter to specify whether the report should group word count by translation resource name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeTranslationResource
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by translation job name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeJob
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by translation job and include reference number in the response.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeJobReferenceNumber
required: false
deprecated: true
schema:
default: false
type: boolean
- description: "Optional parameter to specify whether the report should group word count by translation job and include job number in the response. \nDeprecated, use parameter `fields` instead.\n"
in: query
name: includeJobNumber
required: false
deprecated: true
schema:
default: false
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by fuzzy match profile and tier.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeFuzzyMatchProfile
required: false
deprecated: true
schema:
default: true
type: boolean
- description: 'Optional parameter to specify whether the report should group word count by workflow step uid and name.
Deprecated, use parameter `fields` instead.
'
in: query
name: includeWorkflowStep
required: false
deprecated: true
schema:
default: false
type: boolean
responses:
'200':
description: OK
content:
text/csv:
schema:
type: string
examples:
response:
value: Account,Project,Job Uid,Job,Translation Resource,Agency Uid,Agency, Target Language,Workflow Step,Workflow Step Uid,Workflow Step Name, Fuzzy Profile,Fuzzy Breakdown,Word Count,Weighted Words,Character Count Test Account,Test Project,f12ad8e9,Translation Job,Translator 1, Test Agency 1 Uid, Test Agency 1,Spanish (Spain),Translation,123abc456def, Translation,Default,85 - 94.9%,1,1,1
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
components:
schemas:
Error500Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- GENERAL_ERROR
- MAINTENANCE_MODE_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
type: object
Error400Response:
type: object
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- VALIDATION_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
SuccessResponse:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- SUCCESS
type: string
required:
- code
type: object
Error429Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- MAX_OPERATIONS_LIMIT_EXCEEDED
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
type: object
Error401Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- AUTHENTICATION_ERROR
- AUTHORIZATION_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
type: object
Error:
type: object
properties:
key:
example: general_error
type: string
message:
example: Unexpected server error
type: string
details:
example: {}
type: object
required:
- key
- message
WordCountResponse:
type: object
required:
- response
properties:
response:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- properties:
data:
properties:
items:
items:
properties:
accountName:
description: Name of the account
type: string
accountUid:
description: The account’s unique identifier. This can be found in the Smartling Dashboard under Account Settings > API.
type: string
agencyName:
description: Name of the agency that was credited for the words
type: string
agencyUid:
description: The unique identifier of the agency that was credited for the words
type: string
fuzzyProfileName:
description: Name of the fuzzy match profile used
type: string
fuzzyTier:
description: Fuzzy match tier that matches fuzzy score of the processed words
type: string
jobName:
description: Name of the translation job
type: string
jobUid:
description: The unique identifier of the translation job
type: string
projectId:
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
type: string
projectName:
description: Name of the project
type: string
targetLocaleId:
description: Locale ID of the translations
type: string
targetLocaleName:
description: Name of the locale of the translations
type: string
translationResourceName:
description: Name of the translation resource who was credited for the words
type: string
translationResourceUid:
description: The unique identifier of the translation resource who was credited for the words
type: string
weightedWordCount:
description: The number of weighted words processed by a translation resource
type: integer
wordCount:
description: The number of words processed by a translation resource
type: integer
characterCount:
description: The number of characters processed by a translation resource
type: integer
workflowStepType:
description: Type of the workflow step (Translation, Edit, Review) the words transitioned through
type: string
workflowStepUid:
description: Unique identifier of the workflow step the words transitioned through
type: string
workflowStepName:
description: Name of the workflow step the words transitioned through
type: string
type: object
type: array
resultsTruncated:
description: The flag showing whether all qualified records returned by the response.
type: boolean
type: object
type: object
description: A list of report records
responses:
Error400ResponseDefinition:
description: Provided request parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400Response'
examples:
response:
value:
response:
code: VALIDATION_ERROR
errors:
- key: unknown.field
message: The field unknown.parameter was not expected. Please consult the documentation to verify the fields you are submitting.
details: unknown.parameter
Error429ResponseDefinition:
description: Too many simultaneous API requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error429Response'
examples:
response:
value:
response:
code: MAX_OPERATIONS_LIMIT_EXCEEDED
errors:
- key: too.many.requests
message: The limit of 10 concurrent Smartling file API operations for this project has been exceeded.
Error500ResponseDefinition:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500Response'
Error401ResponseDefinition:
description: Provided credentials are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error401Response'
examples:
response:
value:
response:
code: AUTHENTICATION_ERROR
errors:
- details: {}
key: invalid_token
message: Invalid token
externalDocs:
description: Smartling Help Center
url: https://help.smartling.com