|
Developer documentation has been migrated to the dedicated resource developers.smartcat.com. This page is deprecated but will temporarily remain available for your convenience. |
You are a bit experienced with Smartcat and API, and you know what you want to get with GET requests. If not, you can quickly boost your knowledge in API with our Getting started and Smartcat Integration 101 guides, or, well, you can just go ahead and learn on the fly.
Get directories via API
Without a single wave of a magic wand (you just need your magic mouse and keyboard) you can receive all significant information you can work with in your account. The main method is GET directory with the multiple types you can use for different purposes.
Request URL:
https://smartcat.ai/api/integration/v1/directory?type=language
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Types (account level):
- vendor - get all vendors connected to your account
- domain - get all project groups created in your account
- client - get all clients added in your account
- group - get all user access levels created in your account
- netRate - get all net rates added in your account
Types (system level):
- language - get all languages
- projectStatus - get all project statuses
- documentStatus - get all document statuses
- currency - get all currencies
- freelancerServiceType - get all freelancer's service types (translation, editing, etc)
- specialization - get all specializations (education, marketing, etc)
- specializationKnowledgeLevel - get all levels of competencies (tested, certified, etc)
- lspServiceType - get all LSP service types
The second method which is GET directory/formats returns all parsing formats that are supported in your account.
Request URL:
https://smartcat.ai/api/integration/v1/directory/formats
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Get account details
Let's start with receiving details of your account. You can do that with a GET account request that will respond to you with an account id, name, type (personal or corporate), and another type (for example, LSP or EndCustomer).
Request URL:
https://smartcat.ai/api/integration/v1/account
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
{
"id": "91c6d7fa-4677-490b-a048-6f418e9ee55e",
"name": "MyAccount",
"isPersonal": false,
"type": "LSP"
}
If your account type is LSP, you can also get a list of services from your LSP profile with a GET account/lsp/services end point.
Request URL:
https://smartcat.ai/api/integration/v1/account/lsp/services
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"sourceLanguage": "en",
"targetLanguage": "ru",
"name": "Translation",
"pricePerUnit": 0.5,
"pricePerUnitCurrency": "usd",
"serviceTypes": [
"translation"
],
"specializations": []
},
{
"sourceLanguage": "ru",
"targetLanguage": "es-AR",
"name": "Translation",
"pricePerUnit": 0.5,
"pricePerUnitCurrency": "usd",
"serviceTypes": [
"translation"
],
"specializations": []
}
]
PS:
You can also get a list of services for a specific language pair; a request in that case will look like the following:
https://smartcat.ai/api/integration/v1/account/lsp/services?sourceLanguage=en&targetLanguage=fr
Next, with a GET account/mtengines method check what machine translation engines are added to your account.
Request URL:
https://smartcat.ai/api/integration/v1/account/mtengines
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"id": "754204d5-3c49-4bc0-a5aa-28adf2e34b98",
"name": "Google"
},
{
"id": "f2aefafe-87b7-49a2-9c51-17858e3dec52",
"name": "Google Neural Machine Translation"
},
{
"id": "a22b2732-1fca-3ab5-da9e-c95ab68affff",
"name": "Microsoft Translator"
}
]
If you want to know more about your team member, get a team member's profile using a member's Smartcat id with GET account/myteam/{userid}, or you can get a team member's profile using a member's external id with GET account/myteam/
Request URL:
https://smartcat.ai/api/integration/v1/account/myteam/7aaee713-1810-4dcf-9ec8-c7b4832254e2
Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=
Response:
{
"id": "7aaee713-1810-4dcf-9ec8-c7b4832254e2",
"email": "a.nichols@mailforspam.com",
"firstName": "Aleksandra",
"lastName": "Nichols",
"services": [
{
"serviceType": "translation",
"sourceLanguage": "en",
"targetLanguage": "es",
"pricePerUnit": 0.015,
"currency": "usd",
"specializations": []
}
]
}
Request URL:
https://smartcat.ai/api/integration/v1/account/myteam?externalId=1150
Headers:
Authorization: Basic dGVzdGFwaToxMjM0NTY=
Response:
{
"id": "7aaee713-1810-4dcf-9ec8-c7b4832254e2",
"email": "a.nichols@mailforspam.com",
"firstName": "Aleksandra",
"lastName": "Nichols",
"externalId": "1150",
"services": [
{
"serviceType": "translation",
"sourceLanguage": "en",
"targetLanguage": "es",
"pricePerUnit": 0.015,
"currency": "usd",
"specializations": []
}
]
}
You might also want to know information about clients added to your account, and there is a GET client/{clientId} method to help you out.
Request URL:
https://smartcat.ai/api/integration/v1/client/36cbed44-eeea-414e-9769-6b9f2002885c
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
{
"id": "36cbed44-eeea-414e-9769-6b9f2002885c",
"name": "Client",
"netRate": {
"id": "5c0eae836baff30a2084e25d",
"name": "NetRate",
"newWordsRate": 1,
"repetitionsRate": 0,
"tmMatchRates": [
{
"fromQuality": 50,
"toQuality": 74,
"value": 1
},
{
"fromQuality": 75,
"toQuality": 84,
"value": 1
},
{
"fromQuality": 85,
"toQuality": 94,
"value": 0.9
},
{
"fromQuality": 95,
"toQuality": 99,
"value": 0.8
},
{
"fromQuality": 100,
"toQuality": 100,
"value": 0
},
{
"fromQuality": 101,
"toQuality": 101,
"value": 0
},
{
"fromQuality": 102,
"toQuality": 102,
"value": 0
}
]
}
}
The response displays a client name, client id and details about a net rate attached to the client. "fromQuality" is a bottom value of a TM match, "toQuality" is a top value of a TM match, and a value is a payment rate. For example, value 0.9 means that TM matches will be paid according to the 90% of the full per-word rate.
Get project information
Receiving information about your projects is essential, as the projects are mainly the core part of your account. There are many useful methods that are prepped for you, so go ahead and get them!
Start with the simple GET project/list method that will return a detailed list of projects in your account.
Request URL:
https://smartcat.ai/api/integration/v1/project/list
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"id": "1c0c9279-6868-4093-9564-d5ff693fe944",
"name": "Test",
"description": "",
"creationDate": "2018-12-08T19:41:35.468Z",
"createdByUserId": "ac56ed95-bd78-43a4-b817-30a7b12d3269",
"modificationDate": "2018-12-08T19:41:35.468Z",
"sourceLanguage": "en",
"targetLanguages": [
"ru"
],
"status": "created",
"statusModificationDate": "2018-12-08T19:41:35.468Z",
"vendors": [],
"workflowStages": [
{
"progress": 0,
"stageType": "translation"
}
],
"documents": [
{
"id": "cd08227b3c181d6a9e8524f0_25",
"name": "Test",
"creationDate": "2018-12-08T19:41:35.515Z",
"sourceLanguage": "en",
"documentDisassemblingStatus": "success",
"targetLanguage": "ru",
"status": "created",
"wordsCount": 2,
"statusModificationDate": "2018-12-08T19:41:35.515Z",
"pretranslateCompleted": false,
"workflowStages": [
{
"progress": 0,
"wordsTranslated": 0,
"unassignedWordsCount": 0,
"status": "assigned",
"executives": [
{
"assignedWordsCount": 2,
"progress": 0,
"id": "64b982ad-8b06-447b-82e1-cbbb7ab3e327"
}
]
}
],
"externalId": "cd08227b3c181d6a9e8524f0",
"placeholdersAreEnabled": true
}
],
"specializations": []
}
Once you receive information about all your projects, you might want to get details about a particular one with a GET project/{projectid} method...
Request URL:
https://smartcat.ai/api/integration/v1/project/67db6b32-1d54-4a09-940e-c1f550751787
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
{
"id": "67db6b32-1d54-4a09-940e-c1f550751787",
"name": "test",
"description": "",
"creationDate": "2018-12-17T22:19:07.234Z",
"createdByUserId": "ac56ed95-bd78-43a4-b817-30a7b12d3269",
"modificationDate": "2018-12-17T22:19:07.234Z",
"sourceLanguage": "en",
"targetLanguages": [
"ru"
],
"status": "inProgress",
"statusModificationDate": "2018-12-17T22:19:51.351Z",
"vendors": [],
"workflowStages": [
{
"progress": 0,
"stageType": "translation"
}
],
"documents": [
{
"id": "dd386e70420c1d60fc560f84_25",
"name": "test",
"creationDate": "2018-12-17T22:19:51.335Z",
"sourceLanguage": "en",
"documentDisassemblingStatus": "success",
"targetLanguage": "ru",
"status": "created",
"wordsCount": 1,
"statusModificationDate": "2018-12-17T22:19:51.337Z",
"pretranslateCompleted": false,
"workflowStages": [
{
"progress": 0,
"wordsTranslated": 0,
"unassignedWordsCount": 1,
"status": "notAssigned",
"executives": []
}
],
"externalId": "dd386e70420c1d60fc560f84",
"placeholdersAreEnabled": true
}
],
"specializations": []
}
...and count statistics for it with GET project/{projectId}/statistics. The statistics will be displayed for the whole project as well as for each document in the project separately.
Request URL:
https://smartcat.ai/api/integration/v1/project/67db6b32-1d54-4a09-940e-c1f550751787/statistics
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"language": "ru",
"statistics": [
{
"name": "total",
"words": 1,
"percent": 100,
"segments": 1,
"pages": 0,
"charsWithoutSpaces": 4,
"charsWithSpaces": 4,
"effectiveWordsForBilling": 1
},
{
"name": "newWords",
"words": 1,
"percent": 100,
"segments": 1,
"pages": 0,
"charsWithoutSpaces": 4,
"charsWithSpaces": 4,
"effectiveWordsForBilling": 1
},
{
"name": "repetitions",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "crossFileRepeated",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0, "charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "contextMatch_102",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0 },
{
"name": "contextMatch_101",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_100",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_95_99",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_85_94",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_75_84",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_50_74",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
}
],
"documents": [
{
"name": "test",
"statistics": [
{
"name": "total",
"words": 1,
"percent": 100,
"segments": 1,
"pages": 0,
"charsWithoutSpaces": 4,
"charsWithSpaces": 4,
"effectiveWordsForBilling": 1
},
{
"name": "newWords",
"words": 1,
"percent": 100,
"segments": 1,
"pages": 0,
"charsWithoutSpaces": 4,
"charsWithSpaces": 4,
"effectiveWordsForBilling": 1
},
{
"name": "repetitions",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "crossFileRepeated",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "contextMatch_102",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "contextMatch_101",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_100", "words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_95_99",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_85_94",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_75_84",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
},
{
"name": "match_50_74",
"words": 0,
"percent": 0,
"segments": 0,
"pages": 0,
"charsWithoutSpaces": 0,
"charsWithSpaces": 0,
"effectiveWordsForBilling": 0
}
]
}
]
}
]
When the project is partially or fully completed, it's also possible to receive statistics for the parts completed by assignees of the project with GET project/{projectId}/completedWorkStatistics. The request will return statistics for both the project and every document on the project for each assignee id.
Request URL:
https://smartcat.ai/api/integration/v1/project/67db6b32-1d54-4a09-940e-c1f550751787/completedWorkStatistics
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
There are also a couple methods to identify resources connected to the project. With GET project/{projectid}/translationmemories you receive a list of all active translation memories on the project.
Request URL:
https://smartcat.ai/api/integration/v1/project/67db6b32-1d54-4a09-940e-c1f550751787/translationmemories
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"id": "94ef1275-7c45-4a77-b193-43a49099f736",
"matchThreshold": 75,
"isWritable": true
}
]
"isWritable": true defines a translation memory where your translations are written into.
GET project/{projectId}/glossaries helps to receive a list of the attached glossaries.
Request URL:
https://smartcat.ai/api/integration/v1/project/67db6b32-1d54-4a09-940e-c1f550751787/glossaries
Headers:
Authorization: Basic ZG0wMTpRd2VydHkxMjM=
Response:
[
{
"id": "ba226212-7e7a-4bf8-aad9-17a875d71d21",
"name": "Glossary",
"description": "",
"languages": [
"en",
"ru"
],
"units": 1,
"unitsPending": 0
}
]
