Help

User API

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 of translator, manager, language_coordinator, observer or translator_and_language_coordinator. Defaults to blank if left blank.
filter: can be one of membership, invitation or blank. Defaults to blank if left blank. Filters the list of users by invitations or memberships.

Response example:

[
  {"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 of translator, manager, language_coordinator or observer. Defaults to translator if left blank.
proofreader: allows the user to proofread other people’s translations. Can be one of true or false. Defaults to true if left blank.
super_proofreader: allows the user to proofread her own translations. Can be one of true or false. Defaults to true if left blank. Can’t be true if proofreader option is set to false.
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 respond a JSON Hash containing the URL to the invitation. The invitation should be immediately available under the “Users” tab of your project.

Response example:

{"invitation_url":"https://webtranslateit.com/en/invitations/79cfd92737c484f67a9870e0b9d7294bbe989ca8"}

🔗Implementation Example in Ruby:

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Post.new('/api/projects/:api_token/users', { 'Content-Type' => 'application/json' })
request.body = {email: 'test@test.com', role: 'translator', locale: 'fr', proofreader: true, super_proofreader: true, personal_message: "Hello there, here's an application to translate our project on WebTranslateIt. Thank you in advance!", name: 'Testy Mc Testerson' }.to_json
response = http.request(request)
puts JSON.parse(response.body)['invitation_url'] # => https://webtranslateit.com/en/invitations/26bfecbfeb8c5ccae3663fae591d840c2c1d71db

🔗Implementation Example in PHP:

<?php
$api_key = "sekret";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/users");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, array("email" => "test@test.com", "role" => "translator", "locale" => "fr", "proofreader" => "true", "super_proofreader" => "true", "personal_message" => "Hello there, here's an application to translate our project on WebTranslateIt. Thank you in advance!", "name" => "Testy Mc Testerson"));
$response = curl_exec($ch);
print_r($response);
curl_close($ch);
?>

🔗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 to true the user will be able to proofread other people’s translations. Can be one of true or false. 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 to true the user will be able to proofread her own translations. Can be one of true or false. 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 respond 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 reprentation of the error will be returned in the body.

Response example:

{"invitation_url":"https://webtranslateit.com/en/invitations/79cfd92737c484f67a9870e0b9d7294bbe989ca8"}

🔗Implementation Example in Ruby:

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Put.new('/api/projects/:api_token/users/1234/approve', { 'Content-Type' => 'application/json' })
request.body = { personal_message: "Hello there, welcome to my project!! You wanted to contribute to `fr_CA`, which we don’t have on our project, so I’m placing you as a translator for `fr`.", locale: 'fr' }.to_json
response = http.request(request)
puts JSON.parse(response.body)['invitation_url'] # => https://webtranslateit.com/en/invitations/26bfecbfeb8c5ccae3663fae591d840c2c1d71db

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

🔗Implementation Example in Ruby:

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Delete.new('/api/projects/:api_token/users/:invitation_id', { 'Content-Type' => 'application/json' })
response = http.request(request)

🔗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 reprentation 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 to true the user will be able to proofread other people’s translations. Can be one of true or false. 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 to true the user will be able to proofread her own translations. Can be one of true or false. Defaults to whatever value was set by the membership if left blank.

🔗Example response

Success:

{"membership":{"type":"membership","id":527,"avatar":"https://secure.gravatar.com/avatar/d0ed69be1d61caf4ddbdc74ce27788ff.png?d=identicon&r=PG","email":"edouard@webtranslateit.com","name":"Edouard Briere","role":"manager","locale":"fr","proofreader":true,"super_proofreader":true,"member_since":"2010-02-09T23:23:11Z"}}

Failure:

{"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."]}}

🔗Implementation Example in Ruby:

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Put.new('/api/projects/:api_token/memberships/1234', { 'Content-Type' => 'application/json' })
request.body = {proofreader: true, super_proofreader: false }.to_json
response = http.request(request)

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

🔗Implementation Example in Ruby:

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Delete.new('/api/projects/:api_token/memberships/:team_member_id', { 'Content-Type' => 'application/json' })
response = http.request(request)