ProZ.com global directory of translation services
The translation workplace
Ideas

ProZ.com 2.0 API View the new API docs

Overview

The ProZ.com 2.0 API is a REST-like API for interacting with ProZ.com services. Use of the API is subject to the API terms and conditions.

If you have any questions or want to talk more about integrating your app with ProZ.com, please send an email to [email protected].

Services

The following services are currently exposed via the API.

Developer resources

Usage

Here's a quick overview of how to use the API.

Making an API request

The base URL for the API is https://api.proz.com/v2/. SSL is required.

An example GET request using the curl utility looks like this:

curl -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' https://api.proz.com/v2/freelancer/32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7

When making a POST or PUT request, you must also specify the Content-Type header and the JSON data:

curl -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "recipient_uuids": [ "32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7" ],
        "sender_name": "William James",
        "sender_email": "[email protected]",
        "subject": "Test message",
        "body": "This is only a test."
    }' \
    https://api.proz.com/v2/messages

If the Content-Type header is not included you'll receive an error response with a 415 Unsupported media type HTTP status code.

Authentication

For simple internal applications that access only public data or that act only on behalf of a single ProZ.com user account, an API key can be used to authenticate.

If you're making a public application for use by others, or if you need to access ProZ.com on behalf of different users, you must use OAuth2.

See the authentication guide for details.

OpenID Connect

There is a basic implementation of the OpenID Connect Core protocol. To get the ID token make a request to the authorize endpoint with response_type=code id_token and include openid in your requested scope:

curl https://www.proz.com/oauth/authorize?response_type=code%20id_token&scope=openid&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}

In response you would receive encrypted `id_token` which contains the following info:

{
    "iss": "https:\/\/www.proz.com",
    "sub": "32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7",
    "aud": "724…a6",
    "iat": 1528104705,
    "exp": 1528108305,
    "auth_time": 1528104705,
    "nonce": "645125488"
}

sub is the same as id in the ProZ.com account link, so you can use it to link ProZ.com users to users in your app.

We don't use sub in the API to retrieve user data, so you have to get UUID via a request to GET: /user.

There are no claims supported at the moment. If have any requests for claims support you need then contact us at [email protected].

Response format

API responses include an HTTP status code header and a JSON data structure. JSON responses are wrapped in a common format, to make them easier to parse.

Every response object has a success attribute, which is 1 on success, and 0 on error.

An error response looks like this:

{
    "success":0,
    "error_messages": [
        "Please specify a language pair."
    ]
}

A success response is different for each resource, but in general it tends to look something like this:

{
    "meta": {
        "num_results": 1234
    },
    "data": ...
}

The exact content of the response object will be different for different endpoints. The meta attribute, if it exists, will contain metadata about the response, and the data attribute, if it exists, will contain the resource(s) requested.

Resources may be sent as partial objects; some fields may be excluded from the data structure if they are not set, in order to save bandwidth.

Error handling

If there is an error in your request, an HTTP 4xx status code ("client error") will be returned. A JSON response may or may not be returned as well, depending on the nature of the error. If a JSON error response is returned, check the error_messages attribute to learn more about what was wrong with the request.

If the ProZ.com servers are having trouble, an HTTP 5xx status code ("server error") may be returned. In this case you should try your request again later, and submit a support request to ProZ.com staff if the problem persists.

Rate limiting

Rate limits will probably be imposed in the future. For now, please be considerate and don't abuse the service.

Resource types

The data structures transmitted through service endpoints.

Enumerated types

Lists of codes and IDs used for some fields.

Formats

Standardized formats used.

Client libraries

The following third-party client libraries have been made available by others for interacting with the ProZ.com API.

Terms and conditions

Use of the API is subject to the API terms and conditions.