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].
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.
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.
