Protemos API Documentation

The API is in early development stage and is subject to change without notice at any time. Be prepared to update your code accordingly.

General information

The requests should be directed to the base URL "https://api.protemos.com/v1/" followed by specific request path, for example: "https://api.protemos.com/v1/project/index". All requests must specify the API key as a query parameter "api_key" of request URL. The API key is available on Account details page of Protemos main site for account owners only. Only accounts with active license (including trial accounts) can access the API. POST requests expect parameters to be passed in request message body in "application/x-www-form-urlencoded" and/or "multipart/form-data" format (see specific request descriptions for details). GET requests expect parameters to be passed as query parameters of request URL.

Date-time values

All date-time values passed to API as parameters must be in UTC and have SQL format (for ex.: 2015-12-28 15:33:44). All date-time values returned by API are in UTC.

Error reporting

The API calls report errors with appropriate HTTP status codes. The response body returned have "application/json" content type and contains a JSON object with at least a "message" field describing the error and possibly some additional fields with more error details.

List of requests

account/view

Returns the information about Protemos account performing a request.

Method: GET
Response content type: "application/json"

client/create

Creates a new client.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name", "type_id", "default_branch_id", "first_name", "last_name", "email", "time_zone" are optional.

Response content type: "application/json"
Example request:
type_id=1&default_branch_id=1&name=TestCompany&country_id=US&city=SomeCity&time_zone=Europe/London;&first_name=FirstName&last_name=LastName&email=someaddress@mail.com
Example response:
{created client information (see client/view response)}

client/update

Updates existing client.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: same as client/create request. Response content type: "application/json"
Example request:
company_name=NewName&email=newaddress@mail.com
Example response:
{updated client information (see client/view response)}

client-contact/create

Creates a new client contact.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name" and "email" are optional.

Response content type: "application/json"
Example request:
name=Test&email=test@mail.com&phone=123456
Example response:
{created client contact information (see client-contact/view response)}

client-contact/index

Returns the information about all client contacts.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for contact1 (see client-contact/view request)}, {data for contact2}, ...]

client-contact/update

Updates an existing client contact.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Same as for client-contact/create request.
Response content type: "application/json"
Example request:
name=NewName&phone=123456
Example response:
{updated client contact information (see client-contact/view response)}

client-payment/create

Creates a new client payment.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "note" are mandatory.

Response content type: "application/json"
Example request:
client_id=123&payment_method_id=123&formPaidAt=2019-01-01 00:00:11&amount=150&currency_id=123
Example response:
{created client payment information (see client-payment/view response)}

client-payment/index

Returns the information about all client payments of all clients.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for payment1 (see client-payment/view request)}, {data for payment2}, ...]

client-payment/update

Updates an existing client payment.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example request:
amount=200
Example response:
{updated client payment information (see client-payment/view response)}

client-price/index

Returns the information about all client prices.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{"id":123,"user_id":null,"spec_id":null,"lang_pair_id":null,"service_id":null,"unit_id":4,"unit_price":"111.000000","currency_id":43,"note":null,"updated_by":2,"updated_at":"2020-04-05 11:46:17","service":null,"langPair":null,"spec":null,"unit":{"id":4,"name":"Hour","is_enabled":1,"is_word":0}}]

crm-history/create

Creates a new CRM note.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example request:
note=Test
Example response:
{"note":"Test","client_id":123,"created_by":456,"id":789,"from_status_id":null,"to_status_id":null,"created_at":"2022-01-25 11:49:00","updated_by":null,"updated_at":null}

job/accept-completion

Transitions the job to the "Completion accepted" status.

URL query parameters: Method: POST
Response content type: "application/json"
Example response:
{job information (see job/view response)}

job/create

Creates a new job.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name", "service_id", "lang_pair_id" are optional.

Response content type: "application/json"
Example request:
name=Job1&service_id=5&lang_pair_id=30&formDeadlineAt=2019-01-01 00:00:11
Example response:
{created job information (see job/view response)}

job/index

Returns the information about all jobs.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for job1 (see job/view request)}, {data for job2}, ...]

Links project input files to a job as job input files.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example request:
files[]=123&files[]=456
Example response:
{job info with a list of all linked input files (see job/view response)}

Unlinks job input files from a job.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

Job input files that are linked to payable cannot be unlinked from a job.

Response content type: "application/json"
Example request:
files[]=123&files[]=456
Example response:
{job info with a list of all linked input files (see job/view response)}

job/offer

Transitions the job to the "Offered to vendor" status. If there are following jobs in chain that can be offered, each one is also transitioned to the "Offered to vendor" status.

URL query parameters: Method: POST
Response content type: "application/json"
Example response:
{job information (see job/view response)}

job/start

Transitions the job to the "Started" status.

URL query parameters: Method: POST
Response content type: "application/json"
Example response:
{job information (see job/view response)}

job/update

Updates an existing job.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Same as for job/create request.
Response content type: "application/json"
Example request:
name=NewName&service_id=7
Example response:
{updated job information (see job/view response)}

job/delete

Deletes job.

URL query parameters: Method: DELETE

language-pair/create

Creates a new language pair.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters are required.

Response content type: "application/json"
Example request:
sourceTag=ru&targetTag=en
Example response:
{created language pair information (see language-pair/view response)}

project/create

Creates a new project.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name", "client_id", "primary_manager_id", "formStartAt" are optional. Secondary project manager cannot be the same person as primary project manager.

The "created_by" field of the project will be set equal to "primary_manager_id".

Response content type: "application/json"
Example request:
name=Test1&client_id=44&primary_manager_id=1&formStartAt=2019-01-01 00:00:11&langPairIds[]=3&langPairIds[]=4
Example response:
{created project information (see project/view response)}

project/create-from-template

Creates a new project based on specified project template.

Method: POST
Parameters: "id" - specifies the ID of the project template to base new project upon

The "created_by" field of the project will be set equal to "primary_manager_id".

Response content type: "application/json"
Example response:
{created project information (see project/view response)}

project/add-tags

Adds tags to a project.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example response:
{project information (see project/view response)}

project/index

Returns the information about all projects.

Method: GET
Response content type: "application/json"
Example response:
[{data for project1 (see project/view request)}, {data for project2}, ...]

project/update

Updates an existing project.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Same as for project/create request.
Response content type: "application/json"
Example request:
name=Test&primary_manager_id=1&formStartAt=2019-01-01 00:00:11&langPairIds[]=3&langPairIds[]=4
Example response:
{updated project information (see project/view response)}

project/view

Returns the information about project specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the project to return information for
Response content type: "application/json"
Example response: 
{"id":1009,
"branch_id":2,
"local_id":1009,
"branch_id":1,
"client_id":49,
"client_contact_id":null,
"primary_manager_id":42,
"secondary_manager_id":null,
"spec_id":7,
"status_id":3,
"last_job_number":2,
"free_of_charge":0,
"name":"302579-101T1_1_en",
"description":"Manual",
"start_at":"2015-08-12 11:00:00",
"deadline_at":"2015-08-12 11:00:00",
"offered_at":"2015-08-12 11:00:00",
"confirmed_at":"2015-08-12 11:00:00",
"confirmed_by":42,
"completed_at":"2015-08-12 23:59:31",
"completed_by":42,
"accepted_at":"2015-08-12 23:59:31",
"accepted_by":42,
"rejected_at":"2015-08-12 23:59:31",
"rejected_by":42,
"rejection_reason":"rejection reason",
"canceled_at":null,
"canceled_by":null,
"reminder1_sent_at":"2015-08-12 11:00:00",
"reminder2_sent_at":"2015-08-12 11:00:00",
"created_at":"2015-08-12 08:05:21",
"created_by":42,
"projectLangPairs": [
	{
		"project_id": 1009,
		"lang_pair_id": 10
	}
]}
Current status of the project ("status_id") can have one of the following values:
1 - Draft
2 - Offered (by client)
3 - Active (offer accepted by manager)
4 - Offer rejected (by manager)
5 - Completed
6 - Completion accepted (by client)
7 - Completion rejected (by client)
8 - Canceled

project/chain-jobs

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Example request:
jobs[]=123&jobs[]=456

The jobs specified by "jobs[]" parameter must belong to the project specified with query parameter "id", must not belong to existing jobs chain and must have the same language pair.

In case of error the server responds with 400 status code. On success the server responds with 204 status code.

project/accept-offer

project/reject-offer

project/complete

project/accept-completion

project/reject-completion

Transitions the project to a new status (according to request name).

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

The "offer_rejection_reason" is only used project/reject-offer request and is mandatory. The "completion_rejection_reason" is only used project/reject-completion request and is mandatory.

Response content type: "application/json"
Example response:
{project information (see project/view response)}

project-cat-log/index

Returns the information about all project CAT logs.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for log1 (see project-cat-log/view request)}, {data for log2}, ...]

project-cat-log/view

Returns the information about project CAT log specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the project CAT log to return information for
Response content type: "application/json"
Example response: 
{"project_id":208511,"name":"test1","cat_type_id":4,"created_by":1,"id":9189,"is_manual":0,"created_at":"2020-01-01 12:14:00","items":[{"match_type_id":1,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94052},{"match_type_id":2,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94053},{"match_type_id":3,"word_count":369,"project_id":123,"cat_log_id":9189,"id":94054},{"match_type_id":4,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94055},{"match_type_id":5,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94056},{"match_type_id":6,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94057},{"match_type_id":7,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94058},{"match_type_id":8,"word_count":0,"project_id":123,"cat_log_id":9189,"id":94059},{"match_type_id":9,"word_count":1548,"project_id":123,"cat_log_id":9189,"id":94060}]}

project-cat-log/upload

Allows to upload a new CAT log into a project.

Method: POST
Request content type: "multipart/form-data"
URL query parameters: Body parameters: Response content type: "application/json"
Example response:
{project CAT log information (see project-cat-log/view response)}

project-file/index

Returns the information about all project files.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for file1 (see project-file/view request)}, {data for file2}, ...]

project-file/view

Returns the information about project file specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the project file to return information for
Response content type: "application/json"
Example response: 
{"project_id":123,
"file_id":456,
"is_project_input":true,
"is_project_output":false,
"category_id":null,
"note":null,
"file":{"id":456,"name":"somefile.txt","size":123,"hash":"15c2a547799e1f77374ec6881929b453","created_by":1,"created_at":"2020-08-28 10:40:27"},
"jobsFiles": [
	{"project_id":123,"job_id":789,"file_id":456,"is_job_output":0}
]}

project-file/upload

Allows to upload a new file into a project.

Method: POST
Request content type: "multipart/form-data"
URL query parameters: Body parameters: Response content type: "application/json"
Example response:
{project file information (see project-file/view response)}

project-file/add-urls

Allows to add multiple file URLs into a project.

Method: POST
Request content type: "application/x-www-form-urlencoded"
URL query parameters: Body parameters: Example request:
links=http://server.com/file1
ftp://server2.com/file2

On success server returns status code 204 No Content.

project-file/download

Allows to download project file specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the project file to download
Response content type: "application/octet-stream"

quote/accept

quote/reject

Transitions the quote to a new status (according to request name).

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

The "rejection_reason" is only used by quote/reject request and is mandatory.

Response content type: "application/json"
Example response:
{quote information (see quote/view response)}

quote/add-tags

Adds tags to a quote.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example response:
{quote information (see quote/view response)}

quote/create

Creates a new quote.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name", "client_id", "primary_manager_id" are optional. Secondary project manager cannot be the same person as primary project manager.

The "created_by" field of the quote will be set equal to "primary_manager_id".

Response content type: "application/json"
Example request:
name=TestQuote1&client_id=44&currency_id=141&primary_manager_id=1&formStartAt=2019-10-21 15:00:00&langPairIds[]=3&langPairIds[]=4
Example response:
{created quote information (see quote/view response)}

quote/update

Updates an existing quote.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

The rest of the parameters are the same as for quote/create request. Which parameters are available for update depends on current quote status.

Response content type: "application/json"
Example request:
name=NewName&primary_manager_id=1&formStartAt=2019-10-21 15:00:00&langPairIds[]=3&langPairIds[]=4
Example response:
{updated quote information (see quote/view response)}

quote-cat-log/index

Analogous to project-cat-log/index request.

quote-cat-log/view

Analogous to project-cat-log/view request.

quote-cat-log/upload

Analogous to project-cat-log/upload request.

receivable/create-flat-rate

Creates a new flat rate project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "service_id", "total", "currency_id" are optional.

Response content type: "application/json"
Example request:
po_number=123&lang_pair_id=5&service_id=10&total=123.45&currency_id=20
Example response:
{created receivable information (see receivable/view response)}

receivable/index

Returns the information about all receivables.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for receivable1 (see receivable/view request)}, {data for receivable2}, ...]

quote-file/index

Returns the information about all quote files.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for file1 (see quote-file/view request)}, {data for file2}, ...]

quote-file/view

Returns the information about quote file specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the quote file to return information for
Response content type: "application/json"
Example response: 
{"quote_id":123,
"file_id":456,
"file":{"id":456,"name":"somefile.txt","size":123,"hash":"15c2a547799e1f77374ec6881929b453","created_by":1,"created_at":"2020-08-28 10:40:27"}}

quote-file/upload

Allows to upload a new file into a quote.

Method: POST
Request content type: "multipart/form-data"
URL query parameters: Body parameters: Response content type: "application/json"
Example response:
{quote file information (see quote-file/view response)}

quote-file/add-urls

Allows to add multiple file URLs into a quote.

Method: POST
Request content type: "application/x-www-form-urlencoded"
URL query parameters: Body parameters: Example request:
links=http://server.com/file1
ftp://server2.com/file2

On success server returns status code 204 No Content.

quote-file/download

Allows to download quote file specified with parameter "id".

Method: GET
Parameters: "id" - specifies the ID of the quote file to download
Response content type: "application/octet-stream"

quote-receivable/index

Returns the information about all quote receivables.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{data for quote receivable1 (see quote-receivable/view request)}, {data for quote receivable2}, ...]

receivable/create-cat-log-based

Creates a new CAT log based project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "catLogId", "service_id", "unit_amount", "unit_type", "unit_price", "currency_id" are optional.

Response content type: "application/json"
Example request:
catLogId=1&templateId=2&ReceivableCatLogItem[105][conversion_rate]=35&ReceivableCatLogItem[107][conversion_rate]=50&po_number=123&lang_pair_id=5&service_id=10&unit_price=123.45&currency_id=20
Example response:
{created receivable information (see receivable/view response)}

receivable/create-unit-based

Creates a new unit based project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "service_id", "unit_amount", "unit_type", "unit_price", "currency_id" are optional.

Response content type: "application/json"
Example request:
po_number=123&lang_pair_id=5&service_id=10&unit_amount=50&unit_type=5&unit_price=123.45&currency_id=20
Example response:
{created receivable information (see receivable/view response)}

receivable/delete

Deletes receivable.

URL query parameters: Method: DELETE

receivable/update

Updates specified project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: The rest of parameters are the same as for receivable/create-flat-rate or receivable/create-unit-based requests, depending on the type of receivable being updated.
Response content type: "application/json"
Example request:
po_number=123&lang_pair_id=5&service_id=10&unit_amount=50&unit_type=5&unit_price=123.45&currency_id=20
Example response:
{receivable information (see receivable/view response)}

receivable/update-discount

Updates discount and extra charge amounts of the specified project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example request:
extra_charge_and_discount_type=1&discount_amount=10
Example response:
{receivable information (see receivable/view response)}

receivable/apply-rates-template

Applies specified CAT log conversion scheme to existing project receivable.

URL query parameters: Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters: Response content type: "application/json"
Example request:
templateId=123
Example response:
{receivable information (see receivable/view response)}

tax/index

Returns the information about all taxes defined in the system.

Method: GET
Response content type: "application/json"
Example response:
[{"id":1,"name":"VAT","type":1,"sort_order":1},{"id":2,"name":"Bank fee","type":2,"sort_order":2}, ...]
Type of the tax ("type") can have one of the following values:
1 - percentage;
2 - absolute.

payable/create-flat-rate

Creates a new flat rate job payable.

URL query parameters:

Everything else is analogous to receivable/create-flat-rate request.

payable/create-cat-log-based

Creates a new CAT log based job payable.

URL query parameters:

Everything else is analogous to receivable/create-cat-log-based request.

payable/create-unit-based

Creates a new unit based job payable.

URL query parameters:

Everything else is analogous to receivable/create-unit-based request.

payable/delete

Deletes payable.

URL query parameters: Method: DELETE

payable/update

Analogous to receivable/update request.

payable/apply-rates-template

Analogous to receivable/apply-rates-template request.

vendor/create

Creates a new vendor.

Method: POST
Request content type: "application/x-www-form-urlencoded"
Parameters:

All parameters except "name", "type_id", "default_branch_id", "first_name", "last_name", "email", "time_zone" are optional.

Response content type: "application/json"
Example request:
type_id=1&default_branch_id=1&name=TestCompany&country_id=US&city=SomeCity&time_zone=Europe/London;&first_name=FirstName&last_name=LastName&email=someaddress@mail.com
Example response:
{created vendor information (see vendor/view response)}

vendor-contact/create

Analogous to client-contact/create request.

vendor-contact/index

Analogous to client-contact/index request.

vendor-contact/update

Analogous to client-contact/update request.

vendor-contact/view

Analogous to client-contact/view request.

client-invoice/index

Returns the information about all client invoices.

Method: GET
Parameters: Response content type: "application/json"
Example response:
[{"id": 123,"local_id": 456,"branch_id": 123,...}, {data for invoice2}, ...]

vendor-price/index

Analogous to client-price/index request.

todo/create

Creates a new to-do.

Method: POST
Request content type: "multipart/form-data"
Parameters:

All parameters except "name", "priority", "assigned_to" are optional.

Response content type: "application/json"
Example response:
{created to-do information (see todo/view response)}

account-payment-method/index

account-payment-method/view

branch/index

branch/view

cat-log-template/index

cat-log-template/view

client/index

client/view

client-contact/view

client-invoice/view

client-payment/view

client-source/index

client-source/view

crm-history/index

currency/index

currency/view

job/view

language-pair/index

language-pair/view

manager/index

manager/view

payable/index

payable/view

quote/index

quote/view

quote-receivable/view

receivable/view

specialization/index

specialization/view

service/index

service/view

project-template/index

project-template/view

unit/index

unit/view

vendor/index

vendor/view

todo/index

todo/view

Analogous to project/index and project/view requests.

client/add-tags

vendor/add-tags

Analogous to quote/add-tags request.