Documentation
API
User API
List and create users, approve or remove invitations and update memberships with the WebTranslateIt User API.
9 min read
The User API is composed of 6 endpoints:
- List Users - list members of a project
- Create User - create an invitation request
- Approve Invitation - approve a requested invitation
- Remove Invitation - remove an invitation
- Update Membership - update a membership
- Remove Membership - remove a membership
List Users
This endpoint is only accessible by the read-write Project API key and lists the users and invitations of a project.
/api/projects/:project_token/users.format [GET]
Parameters:
role: can be blank, or one oftranslator,manager,language_coordinator,observerortranslator_and_language_coordinator. Defaults to blank if left blank.filter: can be one ofmembership,invitationor blank. Defaults to blank if left blank. Filters the list of users by invitations or memberships.
GET
/api/projects/:project_token/users.jsoncurl "https://webtranslateit.com/api/projects/PROJECT_TOKEN/users.json?role=translator"
const response = await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/users.json?role=translator'
)
const users = await response.json()
import requests
response = requests.get(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/users.json",
params={"role": "translator"},
)
users = response.json()
require 'net/http'
require 'json'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users.json')
uri.query = URI.encode_www_form(role: 'translator')
users = JSON.parse(Net::HTTP.get(uri))
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users.json?role=translator');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$users = json_decode(curl_exec($ch), true);
curl_close($ch);
Response example:
json
[
{"type":"membership","id":1,"user_id":1234,"avatar":"https://secure.gravatar.com/avatar/a80d19a157623f4d9dc5f1365858da37.png?d=identicon&r=PG","email":"something@gmail.com","name":"","role":"translator","locale":"fr","proofreader":true, "super_proofreader":true,"member_since":"2010-02-12T17:57:39Z"},
{"type":"membership","id":2,"user_id":1235,"avatar":"https://secure.gravatar.com/avatar/1961fef04b12f9366acd7c0f8ce0297b.png?d=identicon&r=PG","email":"soulim@gmail.com","name":"Someone","role":"translator","locale":"ru","proofreader":true, "super_proofreader":true,"member_since":"2010-02-16T12:05:26Z"},
{"type":"membership","id":3,"user_id":1236,"avatar":"https://secure.gravatar.com/avatar/46ff6de645e2045f8ce6a3c640c1d48c.png?d=identicon&r=PG","email":"someone@googlemail.com","name":"Someone","role":"translator","locale":"sv","proofreader":true, "super_proofreader":true,"member_since":"2010-09-14T18:52:12Z"},
{"type":"membership","id":4,"user_id":1237,"avatar":"https://secure.gravatar.com/avatar/aa4a2ba1be686c97724a09218a35644c.png?d=identicon&r=PG","email":"someone@yahoo.fr","name":"Someone","role":"translator","locale":"fr","proofreader":false, "super_proofreader":true,"member_since":"2012-02-09T22:21:22Z"},
{"type":"membership","id":5,"user_id":1238,"avatar":"https://secure.gravatar.com/avatar/bad9247edfb251a4165fc45ca88655b7.png?d=identicon&r=PG","email":"someoneelse@gmail.com","name":"Someone","role":"translator","locale":"fr","proofreader":true, "super_proofreader":true,"member_since":"2013-03-01T13:22:31Z"},
{"type":"invitation","id":121,"status":"pending","avatar":"https://s3.amazonaws.com/users0-webtranslateit/development/user_avatars/thumb/10538_chonchon.jpg?1366636154","email":"someone@webtranslateit.com","name":"Someone","role":"translator","locale":"fr","proofreader":true, "super_proofreader":true,"member_since":"2013-04-22T13:08:44Z", "invitation_link":"https://webtranslateit.com/en/invitations/aPnBeFaPPzX4M0zqKsjqqA"},
{"type":"invitation","id":19121,"status":"requested","avatar":"https://secure.gravatar.com/avatar/3fd534aa706f80d3768fe55f26d28b2e.png?d=identicon&r=PG","email":"dfdkj@dksjd.com","name":"","role":"translator","locale":null,"suggested_locale":"ace","proofreader":false,"super_proofreader":false,"member_since":"2013-12-30T08:56:36Z","invitation_link":"https://webtranslateit.com/en/invitations/aGPqF3NrK1lxNvsk4KCSnQ"}
]
Note that if a person requests an invitation in a locale (or language) that you do not yet support, locale will be null, and an additional parameter suggested_locale will contain the code of the locale that the user wishes to translate to.
Create User
This endpoint is only accessible by the read-write Project API key and creates an invitation request to a user.
/api/projects/:project_token/users [POST]
Parameters:
email: the e-mail address of the person to invite on the project.role: can be one oftranslator,manager,language_coordinatororobserver. Defaults totranslatorif left blank.proofreader: allows the user to proofread other people’s translations. Can be one oftrueorfalse. Defaults totrueif left blank.super_proofreader: allows the user to proofread her own translations. Can be one oftrueorfalse. Defaults totrueif left blank. Can’t betrueifproofreaderoption is set tofalse.locale: code of the locale to assign the translator or language coordinator to (optional for managers and observers).personal_message: Personal message that will be sent along with the invitation e-mail (optional).name: The name of the person invited. Used in the invitation e-mail. (optional).
If everything goes well, the server should respond with 201 Created in the response headers. The response body should contain a JSON Hash containing the URL to the invitation. The invitation should be immediately available under the “Users” tab of your project.
POST
/api/projects/:project_token/userscurl -X POST "https://webtranslateit.com/api/projects/PROJECT_TOKEN/users" \
-H "Content-Type: application/json" \
-d '{
"email": "translator@example.com",
"role": "translator",
"locale": "fr",
"personal_message": "Welcome aboard — here is our project on WebTranslateIt."
}'
const response = await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/users',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'translator@example.com',
role: 'translator',
locale: 'fr',
personal_message: 'Welcome aboard — here is our project on WebTranslateIt.'
})
}
)
const { invitation_url: invitationUrl } = await response.json()
import requests
response = requests.post(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/users",
json={
"email": "translator@example.com",
"role": "translator",
"locale": "fr",
"personal_message": "Welcome aboard — here is our project on WebTranslateIt.",
},
)
invitation_url = response.json()["invitation_url"]
require 'net/http'
require 'json'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users')
response = Net::HTTP.post(uri, {
email: 'translator@example.com',
role: 'translator',
locale: 'fr',
personal_message: 'Welcome aboard — here is our project on WebTranslateIt.'
}.to_json, 'Content-Type' => 'application/json')
invitation_url = JSON.parse(response.body)['invitation_url']
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'email' => 'translator@example.com',
'role' => 'translator',
'locale' => 'fr',
'personal_message' => 'Welcome aboard — here is our project on WebTranslateIt.',
]));
$invitationUrl = json_decode(curl_exec($ch), true)['invitation_url'];
curl_close($ch);
Response example:
json
{"invitation_url":"https://webtranslateit.com/en/invitations/79cfd92737c484f67a9870e0b9d7294bbe989ca8"}
Approve Invitation
This endpoint is only accessible by the read-write Project API key and approves a requested invitation.
/api/projects/:project_token/users/:invitation_id/approve [PATCH]
Optional parameters:
locale: code of the locale (or language) to assign the translator to. If left blank, the invitation will default to the language chosen or suggested by the translators.personal_message: Personal message that will be sent along with the invitation e-mail (optional).name: The name of the person invited. Used in the invitation e-mail. (optional).proofreader: sets or unsets proofreading rights to the requested invitation. If set totruethe user will be able to proofread other people’s translations. Can be one oftrueorfalse. Defaults to whatever value was set by the invitation request if left blank.super_proofreader: sets or unsets super proofreading rights to the requested invitation. If set totruethe user will be able to proofread her own translations. Can be one oftrueorfalse. Defaults to whatever value was set by the invitation request if left blank.
If everything goes well, the server should respond with 202 Accepted in the response headers. The response body should contain a JSON Hash containing the URL to the invitation. The invitation should be immediately available under the “Users” tab of your project. If the invitation fails to be approved a JSON representation of the error will be returned in the body.
PATCH
/api/projects/:project_token/users/:invitation_id/approvecurl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234/approve" \
-H "Content-Type: application/json" \
-d '{ "locale": "fr" }'
const response = await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234/approve',
{
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ locale: 'fr' })
}
)
const { invitation_url: invitationUrl } = await response.json()
import requests
response = requests.patch(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234/approve",
json={"locale": "fr"},
)
invitation_url = response.json()["invitation_url"]
require 'net/http'
require 'json'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234/approve')
request = Net::HTTP::Patch.new(uri, 'Content-Type' => 'application/json')
request.body = {locale: 'fr'}.to_json
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
invitation_url = JSON.parse(response.body)['invitation_url']
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234/approve');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['locale' => 'fr']));
$invitationUrl = json_decode(curl_exec($ch), true)['invitation_url'];
curl_close($ch);
Response example:
json
{"invitation_url":"https://webtranslateit.com/en/invitations/79cfd92737c484f67a9870e0b9d7294bbe989ca8"}
Remove Invitation
This endpoint is only accessible by the read-write Project API key and cancels an invitation.
/api/projects/:project_token/users/:invitation_id [DELETE]
If everything goes well, the server should respond with 202 Accepted in the response headers, and nothing in the body.
DELETE
/api/projects/:project_token/users/:invitation_idcurl -X DELETE "https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234"
await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234',
{ method: 'DELETE' }
)
import requests
requests.delete(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234"
)
require 'net/http'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(Net::HTTP::Delete.new(uri))
end
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/users/1234');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_exec($ch);
curl_close($ch);
Update Membership
This endpoint is only accessible by the read-write Project API key and updates a membership.
/api/projects/:project_token/memberships/:membership_id [PATCH]
If everything goes well, the server should respond with 202 Accepted in the response headers. The body should contain a JSON representation of the membership. If the membership fails to be approved a JSON representation of the error will be returned in the body.
Optional parameters:
locale: code of the locale to assign the user to.proofreader: sets or unsets proofreading rights to the member. If set totruethe user will be able to proofread other people’s translations. Can be one oftrueorfalse. Defaults to whatever value was set by the membership if left blank.super_proofreader: sets or unsets super proofreading rights to the member. If set totruethe user will be able to proofread her own translations. Can be one oftrueorfalse. Defaults to whatever value was set by the membership if left blank.
PATCH
/api/projects/:project_token/memberships/:membership_idcurl -X PATCH "https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527" \
-H "Content-Type: application/json" \
-d '{ "proofreader": true, "super_proofreader": false }'
const response = await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527',
{
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ proofreader: true, super_proofreader: false })
}
)
// `membership` comes back as a JSON string, so it needs a second parse.
const membership = JSON.parse((await response.json()).membership)
import json
import requests
response = requests.patch(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527",
json={"proofreader": True, "super_proofreader": False},
)
# `membership` comes back as a JSON string, so it needs a second parse.
membership = json.loads(response.json()["membership"])
require 'net/http'
require 'json'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527')
request = Net::HTTP::Patch.new(uri, 'Content-Type' => 'application/json')
request.body = {proofreader: true, super_proofreader: false}.to_json
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
# `membership` comes back as a JSON string, so it needs a second parse.
membership = JSON.parse(JSON.parse(response.body)['membership'])
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'proofreader' => true,
'super_proofreader' => false,
]));
// `membership` comes back as a JSON string, so it needs a second parse.
$membership = json_decode(json_decode(curl_exec($ch), true)['membership'], true);
curl_close($ch);
Example response
Success. Note that membership holds the membership encoded as a JSON string, not a nested
object, so it needs a second parse — that is what the examples above do:
json
{"membership":"{\"type\":\"membership\",\"id\":527,\"email\":\"edouard@webtranslateit.com\",\"name\":\"Edouard Briere\",\"role\":\"manager\",\"locale\":\"fr\",\"proofreader\":true,\"super_proofreader\":true,\"member_since\":\"2010-02-09T23:23:11Z\"}"}
Failure:
json
{"error":"Problem saving membership","request":"https://webtranslateit.com/api/projects/43847jdhsjh19289/memberships/527","errors":{"proofreader":["Super proofreaders require the user have proofreading rights too. Add proofreading rights in order to save this membership."]}}
Remove Membership
This endpoint is only accessible by the read-write Project API key and removes a membership.
/api/projects/:project_token/memberships/:membership_id [DELETE]
If everything goes well, the server should respond with 202 Accepted in the response headers, and nothing in the body.
DELETE
/api/projects/:project_token/memberships/:membership_idcurl -X DELETE "https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527"
await fetch(
'https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527',
{ method: 'DELETE' }
)
import requests
requests.delete(
"https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527"
)
require 'net/http'
uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527')
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(Net::HTTP::Delete.new(uri))
end
<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN/memberships/527');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_exec($ch);
curl_close($ch);