Cloudwords Customer API Documentation

General Concepts

Authentication

Cloudwords respects the privacy and sensitivity of any content an organization stores with us, and therefore we take great pains to ensure the security of your data.

To access the Cloudwords API, a client must add an "Authorization" HTTP header to every API request, and that header's value must contain a valid API token. An API token is unique to each user in Cloudwords, and can be generated by asking a user to go to the "My Account" -> "API" Settings area in the Cloudwords application where they'll find a page dedicated to generating their own API token. Once their token is generated, you can add it to each request with the following syntax:

Authorization: UserToken <token_value>

Character Encoding

Cloudwords, as a localization and internationalization based service, has standardized on UTF-8 encoding for all data stored and returned by our service. So to avoid any encoding issues when using the Cloudwords API, be sure your code and libraries support UTF-8 and be sure any text inputted by your users is converted to UTF-8 before sending the data to Cloudwords.

Binary Content

The Cloudwords API exposes the ability to download the binary content that is stored in Cloudwords. This is of course the real meat of what you want to get into and out of Cloudwords. However, this content can be very large, so for the sake of bandwidth and time concerns you should really only download the binary content as needed and only when the content has changed. We offer metadata representations of your files that helps you understand when content was last updated, and this metadata should be used as the primary way of interacting with files in Cloudwords.

HTTPS and SSL

The Cloudwords API requires that you use the TLS 1.2 cryptographic protocol. Using "SSL/early TLS" is not supported since the Cloudwords API does not support fallback mechanisms to older, insecure versions.

Cloudwords respects the privacy and sensitivity of any content an organization stores with us. To ensure the privacy of communication between your application and Cloudwords, we enforce that any connection with the Cloudwords API must be made via HTTPS. Your library and environment will therefore need to support making SSL connections.

To enforce this requirement, any requests made to http://api.cloudwords.com will receive a response with a 302 status code along with the following header:

Location: https://api.cloudwords.com

API limits

To ensure the quality of our service and to protect from the occasional integration run amock, we enforce two types of limits when using the Cloudwords API. Note, when we say "account" below we mean a "company" and not "user".

Concurrent Request Limit: We guarantee only 5 concurrent connections to the Cloudwords API for any Cloudwords account.
Total Requests Per Hour: We guarantee only 1000 requests per hour for any Cloudwords account. The hour period begins when the first request is made by a client for a given account, and will reset to zero one hour after that first call.

If you find these limits to be problematic for your integration, please contact Cloudwords support at support@cloudwords.com.

RESTful API

Base URI

Any call to the Cloudwords API is made using the following domains:

Environment	Domain
Production	https://api.cloudwords.com/
Sandbox	https://api-sandbox.cloudwords.com/

Please note that the protocol needs to be "https", as we don't support non-secure "http" connections to the Cloudwords API.

Version Numbers

APIs need to be versioned, so that any future change or enhancement we make to the Cloudwords API won't break existing client integrations. To support this, we enforce that a API version number must be added to the Base URI:

https://api.cloudwords.com/<version_number>

So to "bind" or reference the version 1.24 Cloudwords API, you'll simply tack "1.24" onto the Base URI, like so:

https://api.cloudwords.com/1.24

The current version of the API is 1.24.

Response Handling

Responses from the Cloudwords API follow standard RESTful practices. Specifically, we communicate via the HTTP response code the result of a client request. Therefore, your integration should look first at the response status code of any response from the Cloudwords API to get a quick idea of what happened. For instance, a "200" code generally means your request processed successfully and you can expect to find the expected success result in Cloudwords. Whereas a "404" response code means we couldn't find the resource you were looking for, most likely due to that resource not existing or due to using an invalid URI.

As a general practice, any response from Cloudwords will contain a content in the response body in standard JSON format. The response body will contain either the expected resource to be returned from a successful call, or more information to explain an exceptional or error related response code. So as a best practice, always first consult the status code of a response, and then inspect the response body for more information.

JSON is a well-supported language-independent format, and there are plenty of libraries across almost all programming languages to assist in serializing/deserializing JSON into a usable form for any language. All Cloudwords SDKs contain a JSON parser.

Response Code Conventions

2xx response codes: Generally returned when the request resulted in a successful response. The response body usually contains the expected resource that was requested or was created as a result of the request.

4xx response codes: Generally a client generated error, which means the client made a request that is either malformed, invalid, or not allowed for the given resource at that time. The response body will contain an "error" attribute explaining what happened and how to correct, if applicable.

500 response code: A server side error, which means there is a problem or bug in the Cloudwords service. Cloudwords is notified whenever a 500 response code happens, and we will try to respond and fix promptly.

Standard Response Codes

Success Codes

Code	Description
200	General success response, consult the response body for more details or the requested resource.
201	The request to create a resource was successful, consult the response body for it's current representation.

Client Error Codes

Code	Description
400	General client error, consult the response body for more details.
401	A request to the API has been made without a valid "Authorization" header and/or valid security token. Please see the "Authentication" section in this document.
403	A request to the API has been made by a Cloudwords account that does not have the ability to access the API. The API is only available in certain editions of Cloudwords, please contact your Cloudwords account manager for more details.
404	The requested resource was not found. Either the resource doesn't exist, or the URI is not valid.
405	The requested HTTP method is not supported for this resource.
415	The specified content-type in the HTTP request was invalid, consult the "Content Types for Data Creation" for more detail.
421	Rate limit exceeded. Consult the response body to understand the specific type of rate limit error, and review the "Rate Limiting" section in this document.

Server Error Codes

Code	Description
500	Server error. We've been notified and will try to fix as soon as possible.

Content Types for Data Creation

Resource Creation
For any request that contains JSON in the request body (POST or PUT operations), we support a content type of "application/json". You should then expect any content in the response body to also be returned as JSON. For example the HTTP request headers would look like:

Accept: application/json
Content-Type: application/json; charset=UTF-8

File/Binary Uploads
For any request where you're sending binary content (such as file uploads), we support a content type of "multipart/form-data". Please note with standard HTTP uploads you need to specify the multi-part boundary as part of the content-type, which most HTTP clients will generate for you. You should then expect any content in the response body to also be returned as JSON, which in the case of file uploads is the metadata representation of that file. For example, the HTTP request headers will need to look like the following:

Accept: application/json
Content-type: multipart/form-data; boundary=<some-multipart-boundary>

Path and Content Path Fields

Path
For any resource returned, there is an additional API-only field named "path". The "path" field gives the fully qualified URL to access that resource. This is most handy in method calls that return lists of objects, where the path field allows you to easily navigate to a specific resource.

Content Path
For resources that represent file metadata, there is an additional API-only field named "contentPath." The "contentPath" field gives the fully qualified URL to download the binary content of the file represented by the metadata resource.

Date Format

All dates returned in the API will follow the standard ISO 8601 format:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Or:
[4 digit year]-[2 digit month]-[2 digit date]'T'[2 digit hour]:[2 digit minute]:[2 digit second].[3 digit millisecond][Timezone]

For example:

2011-08-28T00:00:02.000+0000

would mean August 28th, 2011, 12:00:02 a.m. UTC time.

Similarly, the API expects all date inputs to be in the same standard ISO 8601 format.

By default all date/times returned from Cloudwords will be in UTC time, as denoted by "+0000" for the time zone portion of the format.

Currency

All currency type fields will be returned as values represented in United States dollars, without a currency symbol and with two decimals representing cents. For example:

amount: 123432.00

Project Methods

List Projects

Get the list of projects in Cloudwords.

URL Structure
<base_uri>/<version>/project.json?parameters

Version(s)
All

Method(s)
GET

Parameters

Name	Required	Default	Value
offset	false	0	Start results at `offset` (starts at 0)
limit	false	20	Limit result count to `limit` (max 200)
projectContentType	false	none	Only include projects with a content type of `projectContentType`, case sensitive. Pass parameter multiple times for OR query.
status	false	none	Only include projects with a status of `status`, case sensitive. Pass parameter multiple times for OR query. See the list of Project status values below. Also accepted are "open" and "closed".
sortBy	false	id	Sort the result by a project property. Possible values: id, name, createdDate, bidDueDate, bidSelectDeadlineDate, deliveryDueDate, currency, sourceLanguage
sortOrder	false	asc	Sort ascending (`asc`) or descending (`desc`)

Returns
A result including a list of projects. Up to 200 projects may be returned in a single call, use offset and limit to retrieve more.

Sample Request
<base_uri>/<version>/project.json?status=open&limit=20

Sample JSON response:

{  
   "offset":0,
   "limit":20,
   "count":2,
   "results":[  
      {  
         "name":"My first translation project",
         "id":951,
         "description":"Hey, I need to go global. This is my marketing material.",
         "projectContentType":"STANDARD",
         "status":{  
            "display":"All Languages Approved",
            "code":"all_languages_approved"
         },
         "sourceLanguage":{  
            "display":"English (UK)",
            "languageCode":"en-gb"
         },
         "targetLanguages":[  
            {  
               "display":"German",
               "languageCode":"de"
            },
            {  
               "display":"French (Canada)",
               "languageCode":"fr-ca"
            }
         ],
         "deliveryDueDate":"2011-06-21T00:00:00.000+0000",
         "bidDueDate":"2011-06-19T00:00:00.000+0000",
         "reviewDueDate":"2011-06-25T00:00:00.000+0000",
         "createdDate":"2011-05-18T00:53:52.000+0000",
         "notes":"Mr. Translation Vendor, please do your best",
         "uiFeatures":{  
            "change_source_language":true,
            "change_target_languages":true,
            "change_source_material":true
         },
         "intendedUse":{  
            "name":"Website",
            "id":1
         },
         "department":{  
            "name":"Marketing",
            "id":3
         },
         "owner":{  
            "firstName":"Magic",
            "lastName":"Johnson",
            "id":32,
            "email":"mjohnson@example.org"
         },
         "poNumber":"34293202",
         "bidSelectDeadlineDate":"2011-06-21T00:00:00.000+0000",
         "currency":"USD",
         "amount":10560.00,
         "followers":[  
            {  
               "firstName":"Magic",
               "lastName":"Johnson",
               "id":32,
               "email":"mjohnson@example.org"
            },
            {  
               "firstName":"James",
               "lastName":"Worthy",
               "id":42,
               "email":"jworthy@example.org"
            }
         ],
         "path":"https://api.cloudwords.com/1/project/951.json"
      },
      {  
         "name":"My next translation project",
         "id":993,
         "description":"Wow, I'm getting the hang of this. This is my website",
         "projectContentType":"Drupal",
         "status":{  
            "display":"In Translation",
            "code":"in_translation"
         },
         "sourceLanguage":{  
            "display":"English (UK)",
            "languageCode":"en-gb"
         },
         "targetLanguages":[  
            {  
               "display":"French (France)",
               "languageCode":"fr-fr"
            },
            {  
               "display":"Latvian",
               "languageCode":"lv"
            }
         ],
         "deliveryDueDate":"2011-06-25T00:00:00.000+0000",
         "bidDueDate":"2011-06-19T00:00:00.000+0000",
         "reviewDueDate":"2011-06-25T00:00:00.000+0000",
         "createdDate":"2011-05-26T20:13:58.000+0000",
         "notes":"Dont't forget we have to localize the text in our images.",
         "uiFeatures":{  
            "change_source_language":true,
            "change_target_languages":true,
            "change_source_material":true
         },
         "intendedUse":{  
            "name":"FAQ",
            "id":1
         },
         "department":{  
            "name":"Training",
            "id":4
         },
         "owner":{  
            "firstName":"James",
            "lastName":"Worthy",
            "id":42,
            "email":"jworthy@example.org"
         },
         "poNumber":"34293202",
         "bidSelectDeadlineDate":"2011-06-21T00:00:00.000+0000",
         "currency":"USD",
         "amount":12560.00,
         "followers":[  
            {  
               "firstName":"James",
               "lastName":"Worthy",
               "id":42,
               "email":"jworthy@example.org"
            }
         ],
         "path":"https://api.cloudwords.com/1/project/993.json"
      }
   ]
}

Get Open Projects (deprecated)

Get the list of open projects in Cloudwords.

URL Structure
<base_uri>/<version>/project/open.json

Version(s)
1

Method(s)
GET

Returns
A list of all open projects.

Sample JSON response:

[{
	"name": "My first translation project",
	"id": 951,
	"description": "Hey, I need to go global. This is my marketing material.",
	"projectContentType": "STANDARD",
	 "status": {
		"display": "All Languages Approved",
		"code": "all_languages_approved"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "German",
		"languageCode": "de"
	}, {
		"display": "French (Canada)",
		"languageCode": "fr-ca"
	}],
	"deliveryDueDate": "2011-06-21T00:00:00.000+0000",
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"createdDate": "2011-05-18T00:53:52.000+0000",
	"notes": "Mr. Translation Vendor, please do your best",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"intendedUse": {
		"name": "Website",
		"id": 1
	},
	"department": {
		"name": "Marketing",
		"id": 3
	},
	"owner": {
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	},
	"poNumber": "34293202",
	"bidSelectDeadlineDate": "2011-06-21T00:00:00.000+0000",
	"currency" : "USD",
	"amount": 10560.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}, {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/951.json"
}, {
	"name": "My next translation project",
	"id": 993,
	"description": "Wow, I'm getting the hang of this. This is my website",
	"projectContentType": "Drupal",
	 "status": {
		"display": "In Translation",
		"code": "in_translation"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "French (France)",
		"languageCode": "fr-fr"
	}, {
		"display": "Latvian",
		"languageCode": "lv"
	}],
	"deliveryDueDate": "2011-06-25T00:00:00.000+0000",
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"createdDate": "2011-05-26T20:13:58.000+0000",
	"notes": "Dont't forget we have to localize the text in our images.",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"intendedUse": {
		"name": "FAQ",
		"id": 1
	},
	"department": {
		"name": "Training",
		"id": 4
	},
	"owner": {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	},
	"poNumber": "34293202",
	"bidSelectDeadlineDate": "2011-06-21T00:00:00.000+0000",
	"currency" : "USD",
	"amount": 12560.00,
	"followers": [{
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/993.json"
}]

Get Closed Projects (deprecated)

Get the list of closed projects in Cloudwords.

URL Structure
<base_uri>/<version>/project/closed.json

Version(s)
1

Method(s)
GET

Returns
A list of all closed projects.

Sample JSON response:

[{
	"name": "white album",
	"id": 129,
	"description": "this is going to be revolutionary",
	"projectContentType": "STANDARD",
	"status": {
		"display": "Project Closed",
		"code": "project_closed"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "English (US)",
		"languageCode": "en-us"
	}],
	"deliveryDueDate": "2011-01-25T01:00:00.000+0000",
	"bidDueDate": "2011-01-23T01:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"createdDate": "2011-01-19T17:37:08.000+0000",
	"notes": "Notes and instructions for the providers ",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"intendedUse": {
		"name": "FAQ",
		"id": 7
	},
	"department": {
		"name": "Training",
		"id": 4
	},
	"owner": {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	},
	"poNumber": "34293202",
	"bidSelectDeadlineDate": "2011-01-23T13:00:00.000+0000",
	"currency" : "USD",
	"amount": 20560.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}, {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/129.json"
}, {
	"name": "let it be",
	"id": 237,
	"description": "This is going to be our biggest project so far, maybe ever!",
	"projectContentType": "STANDARD",
	"status": {
		"display": "Cancelled",
		"code": "cancelled"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "Arabic",
		"languageCode": "ar"
	}, {
		"display": "French (France)",
		"languageCode": "fr-fr"
	}],
	"deliveryDueDate": "2011-01-30T01:00:00.000+0000",
	"bidDueDate": "2011-01-28T01:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"createdDate": "2011-01-24T17:08:38.000+0000",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"notes": "note that this is a note",
	"intendedUse": {
		"name": "UI",
		"id": 7
	},
	"department": {
		"name": "Marketing",
		"id": 3
	},
	"owner": {
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	},
	"poNumber": "34293202",
	"bidSelectDeadlineDate": "2011-01-28T13:00:00.000+0000",
	"currency" : "USD",
	"amount": 25874.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/237.json"
}]

Get Project

Get a specific project from Cloudwords.

URL Structure
<base_uri>/<version>/project/<project_id>.json

Version(s)
1

Method(s)
GET

Returns
A specific project.

Sample JSON response:

{
	"name": "My first translation project",
	"id": 951,
	"description": "I need to go global and translate my marketing materials.",
	"projectContentType": "STANDARD",
	"status": {
		"display": "All Languages Approved",
		"code": "all_languages_approved"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "German",
		"languageCode": "de"
	}, {
		"display": "French (Canada)",
		"languageCode": "fr-ca"
	}],
	"deliveryDueDate": "2011-06-21T00:00:00.000+0000",
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"reviewDueDate": "2011-06-24T00:53:52.000+0000",
	"createdDate": "2011-05-18T00:53:52.000+0000",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"notes": "Mr. Translation Vendor, please do your best",
	"intendedUse": {
		"name": "Website",
		"id": 1
	},
	"department": {
		"name": "Marketing",
		"id": 3
	},
	"owner": {
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	},
	"poNumber": "34293202",
	"bidSelectDeadlineDate": "2011-06-21T00:00:00.000+0000",
	"currency" : "USD",
	"amount": 10560.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}, {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/951.json"
}

Create Project

Create a project in Cloudwords.

URL Structure
<base_uri>/<version>/project

Version(s)
1

Method(s)
POST

Returns
The metadata associated with the created project.

Required Fields
name, projectContentType, department (required if organization has Department functionality enabled)

Not Settable Fields
id, createdDate, status, bidSelectDeadline

Field Restrictions

Field Name	Version(s)	Note
name	1	Must be 50 characters or less in length.
description	1	Must be 250 characters or less in length.
sourceLanguage	1	The value must match the "languageCode" attribute that can be found in the Source Language resource detailed below.
targetLanguages	1	Target languages cannot contain the language code found in the sourceLanguage field. The values must match the "languageCode" attribute that can be found in the Target Language resource detailed below.
bidDueDate	1	Must be 48 hours or more in the future.
deliveryDueDate	1	Must be 48 hours or more after the bidDueDate.
reviewDueDate	1	Must be after or on deliveryDueDate.
notes	1	Must be 1000 characters or less in length.
intendedUse	1	The value must match the "id" attribute that can be found in the Intended Use resource detailed below.
department	1.1	The value must match the "id" attribute that can be found in the Department resource detailed below. This field is only supported for Cloudwords organizations that have enabled Department functionality.
owner	1	The value must match the "id" attribute for a user in Cloudwords. Note, this field is optional, and will default to the context user.
poNumber	1	Must be 45 characters or less in length.
followers	1	If specified, must include the project owner, each object is a User object, but only the ID is required.
projectContentType	1.1	Max 40 Characters. Provide a (filterable/searchable) name for your integration to make it easier to identify projects in Cloudwords. (i.e. "Drupal", "MyIntegration", etc.). This is called "Content Source" in the Cloudwords UI.
uiFeatures	1.1	A map of key-value pairs. See Project UI Features.

Sample JSON request:

{
	"name": "My newly created Cloudwords project",
	"description": "Some content from my CMS system.",
	"projectContentType" : "MyCMS",
	"sourceLanguage": "en-gb",
	"targetLanguages": ["de", "fr-ca"],
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"deliveryDueDate": "2011-06-21T00:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"notes": "Mr. Translation Vendor, please do your best",
	"intendedUse": 1,
	"department": {"id":3},
	"owner": 32,
	"poNumber": "34293202",
	"followers": [{
		"id": 32
	}, {
	"id": 42
	}]

}

Sample JSON response:

{
	"name": "My newly created Cloudwords project",
	"id": 1001,
	"description": "Some content from my CMS system.",
	"projectContentType": "MyCMS",
	"status": {
		"display": "Configured Project Details",
		"code": "configured_project_details"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "German",
		"languageCode": "de"
	}, {
		"display": "French (Canada)",
		"languageCode": "fr-ca"
	}],
	"deliveryDueDate": "2011-06-21T00:00:00.000+0000",
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"createdDate": "2011-05-18T00:53:52.000+0000",
	"notes": "Mr. Translation Vendor, please do your best",
	"intendedUse": {
		"name": "Website",
		"id": 1
	},
	"department": {
		"name": "Marketing",
		"id": 3
	},
	"owner": {
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	},
	"poNumber": "34293202",
	"uiFeatures": {
        "change_source_language": true,
        "change_target_languages": true,
        "change_source_material": true
    },
	"bidSelectDeadlineDate": "2011-06-21T00:00:00.000+0000",
	"currency" : "USD",
	"amount": 0.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}, {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/1001.json"
}

Update Project

Update a project in Cloudwords.

URL Structure
<base_uri>/<version>/project/<project_id>

Version(s)
1

Method(s)
PUT

Returns
The metadata associated with the updated project.

Updateable Fields
Pre-Bid Request: All fields except id, createdDate, status, bidSelectDeadlineDate, owner, department, projectContentType
During Bidding: All fields except sourceLanguage, targetLanguges, deliveryDueDate, id, status, createdDate, bidDueDate, bidSelectDeadlineDate, owner, department, projectContentType
Post Bidding: All fields except sourceLanguage, targetLanguges, id, status, createdDate, bidDueDate, bidSelectDeadlineDate, owner, department, projectContentType

Field Restrictions
See "Field Restrictions" in project create section above.

Sample JSON request:

{
	"name": "My newly UPDATED Cloudwords project",
	"deliveryDueDate": "2011-09-21T00:00:00.000+0000",
	"uiFeatures" : { "change_source_language" : true }
}

Sample JSON response:

{
	"name": "My newly UPDATED Cloudwords project",
	"id": 1001,
	"description": "Some content from my CMS system.",
	"projectContentType": "MyCMS",
	"status": {
		"display": "Configured Project Details",
		"code": "configured_project_details"
	},
	"sourceLanguage": {
		"display": "English (UK)",
		"languageCode": "en-gb"
	},
	"targetLanguages": [{
		"display": "German",
		"languageCode": "de"
	}, {
		"display": "French (Canada)",
		"languageCode": "fr-ca"
	}],
	"deliveryDueDate": "2011-09-21T00:00:00.000+0000",
	"bidDueDate": "2011-06-19T00:00:00.000+0000",
	"createdDate": "2011-05-18T00:53:52.000+0000",
	"reviewDueDate": "2011-06-25T00:00:00.000+0000",
	"notes": "Mr. Translation Vendor, please do your best",
	"intendedUse": {
		"name": "Website",
		"id": 1
	},
	"department": {
		"name": "Marketing",
		"id": 3
	},
	"owner": {
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	},
	"uiFeatures": {
        "change_source_language": false,
        "change_target_languages": true,
        "change_source_material": true
    },
	"poNumber": "asdf",
	"bidSelectDeadlineDate": "2011-06-21T00:00:00.000+0000",
	"currency" : "USD",
	"amount": 0.00,
	"followers": [{
		"firstName": "Magic",
		"lastName": "Johnson",
		"id": 32,
		"email" : "mjohnson@example.org"
	}, {
		"firstName": "James",
		"lastName": "Worthy",
		"id": 42,
		"email" : "jworthy@example.org"
	}],
	"path": "https://api.cloudwords.com/1/project/1001.json"
}

Project Workflows

Get the list of initialized project workflows for the given project. Workflows may not be available until a template is selected.

URL Structure
<base_uri>/<version>/project/<project_id>/workflow.json

Version(s)
1.12

Method(s)
GET

Returns
The list of initialized workflows, one per target language.

Sample JSON response:

[
  {
    "complete": false,
    "language": {
      "display": "French",
      "languageCode": "fr"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/fr.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "complete": false,
    "language": {
      "display": "Dutch",
      "languageCode": "nl"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/nl.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customer": {
                "id": 3006,
                "name": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "complete": false,
    "language": {
      "display": "German",
      "languageCode": "de"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/de.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "dueDate": "2014-05-16T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  }
]

Project Workflow by Language

Get an initialized project workflow by target language. While the project is in translation or review, two additional properties, "currentStepNumber" and "currentPhaseNumber" (integers) will be available which indicate the step and phase the workflow is currently on.

URL Structure
<base_uri>/<version>/project/<project_id>/workflow/<language>.json

Version(s)
1.12

Method(s)
GET

Returns
The workflow, if it has been initialized.

Sample JSON response:

{
  "complete": false,
  "language": {
    "display": "German",
    "languageCode": "de"
  },
  "path": "http://api.cloudwords.com/1.12/project/288/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2014-05-14T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 1,
          "phaseType": {
            "code": "work",
            "display": "Work"
          }
        },
        {
          "allowRevision": true,
          "assignee": {
            "customerUser": {
              "email": "pm@crestas.com",
              "firstName": "Project ",
              "id": 33,
              "lastName": "Manager",
              "path": ""
            },
            "path": ""
          },
          "assigneeType": {
            "code": "customer_user",
            "display": "Internal"
          },
          "dueDate": "2014-05-16T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 2,
          "phaseType": {
            "code": "review",
            "display": "Review"
          },
          "possibleAssignees": [
            {
              "customerUser": {
                "email": "admin@notcrestas.com",
                "firstName": "NewUser",
                "id": 20,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "user@crestas.com",
                "firstName": "User",
                "id": 26,
                "lastName": "Request",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "translator@crestas.com",
                "firstName": "Translator",
                "id": 40,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            }
          ]
        }
      ],
      "stepNumber": 1
    }
  ],
  "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
  "templateName": "Basic 1-Step Workflow",
  "templateType": {
    "code": "builtin_single_step",
    "display": "Built-in Single Step"
  }
}

Update Project Workflow

URL Structure
<base_uri>/<version>/project/<project_id>/workflow/<language>.json

Version(s)
1.12

Method(s)
PUT

Returns
The updated workflow

Sample JSON request:

{
  "steps": [
    {
      "phases": [
        {
          "phaseNumber": 2,
          "assignee" : {"customerUser" : {"id" : 33}},
          "dueDate" : "2014-05-16T00:00:00.000+0000"
        }
      ],
      "stepNumber": 1
    }
  ]
}

Sample JSON response:

{
  "complete": false,
  "language": {
    "display": "German",
    "languageCode": "de"
  },
  "path": "http://api.cloudwords.com/1.12/project/288/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2014-05-14T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 1,
          "phaseType": {
            "code": "work",
            "display": "Work"
          }
        },
        {
          "allowRevision": true,
          "assignee": {
            "customerUser": {
              "email": "pm@crestas.com",
              "firstName": "Project ",
              "id": 33,
              "lastName": "Manager",
              "path": ""
            },
            "path": ""
          },
          "assigneeType": {
            "code": "customer_user",
            "display": "Internal"
          },
          "dueDate": "2014-05-16T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 2,
          "phaseType": {
            "code": "review",
            "display": "Review"
          },
          "possibleAssignees": [
            {
              "customerUser": {
                "email": "admin@notcrestas.com",
                "firstName": "NewUser",
                "id": 20,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "user@crestas.com",
                "firstName": "User",
                "id": 26,
                "lastName": "Request",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "translator@crestas.com",
                "firstName": "Translator",
                "id": 40,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            }
          ]
        }
      ],
      "stepNumber": 1
    }
  ],
  "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
  "templateName": "Basic 1-Step Workflow",
  "templateType": {
    "code": "builtin_single_step",
    "display": "Built-in Single Step"
  }
}

Project Workflow Templates

Get the list of available workflow templates for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/workflow-template.json

Version(s)
1.12

Method(s)
GET

Returns
The list of the workflow templates

Sample JSON response:

[
  {
    "description": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "id": 9,
    "name": "Basic 1-Step Workflow",
    "path": "http://api.cloudwords.com/1.12/project/288/workflow-template/9.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "type": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "description": "Use this workflow if the vendor needs to deliver additional files after you have reviewed and approved the translation. For example, if the vendor needs to deliver a final PDF or other type of file once the translations have been approved.",
    "id": 16,
    "name": "Basic 2-Step Workflow",
    "path": "http://api.cloudwords.com/1.12/project/288/workflow-template/16.json",
    "steps": [
      {
        "name": "Initial Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      },
      {
        "name": "Final files",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 2
      }
    ],
    "type": {
      "code": "builtin_two_step",
      "display": "Built-in Two Step"
    }
  },
  {
    "description": "",
    "id": 34,
    "name": "Feedback compilation",
    "path": "http://api.cloudwords.com/1.12/project/288/workflow-template/34.json",
    "steps": [
      {
        "name": "Initial Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      },
      {
        "name": "Vendor Customer",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 2
      },
      {
        "name": "Customer Customer",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 3
      }
    ],
    "type": {
      "code": "custom",
      "display": "Custom"
    }
  },
  {
    "description": "Normal first step, vendor vendor step, vendor customer customer step",
    "id": 37,
    "name": "vendor in middle",
    "path": "http://api.cloudwords.com/1.12/project/288/workflow-template/37.json",
    "steps": [
      {
        "name": "Initial Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      },
      {
        "name": "All Vendor",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 2
      },
      {
        "name": "3 Customer",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          },
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 3,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          },
          {
            "allowRevision": true,
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "durationInDays": 1,
            "path": "",
            "phaseNumber": 4,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 3
      }
    ],
    "type": {
      "code": "custom",
      "display": "Custom"
    }
  }
]

Project Workflow Template by ID

Get a specific template available on a project by template ID

URL Structure
<base_uri>/<version>/project/<project_id>/workflow-template/<template_id>.json

Version(s)
1.12

Method(s)
GET

Returns
The list of the workflow templates

Sample JSON response:

{
  "description": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
  "id": 9,
  "name": "Basic 1-Step Workflow",
  "path": "http://api.cloudwords.com/1.12/project/288/workflow-template/9.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "path": "",
          "phaseNumber": 1,
          "phaseType": {
            "code": "work",
            "display": "Work"
          }
        },
        {
          "allowRevision": true,
          "assigneeType": {
            "code": "customer_user",
            "display": "Internal"
          },
          "path": "",
          "phaseNumber": 2,
          "phaseType": {
            "code": "review",
            "display": "Review"
          }
        }
      ],
      "stepNumber": 1
    }
  ],
  "type": {
    "code": "builtin_single_step",
    "display": "Built-in Single Step"
  }
}

Select Project Workflow Template

Select a workflow template to use. A template may be selected once the project's deliveryDueDate and targetLanguages are set, but before the project has been sent out for bids. Once the project is sent out for bids, the workflow template cannot be changed. It may be changed as many times as needed before that.

URL Structure
<base_uri>/<version>/project/<project_id>/workflow.json

Version(s)
1.12

Method(s)
POST

Returns
The list of initialized workflows, one per target language.

Sample JSON request:

{"workflowTemplateId" : 9}

Sample JSON response:

[
  {
    "complete": false,
    "language": {
      "display": "German",
      "languageCode": "de"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/de.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "complete": false,
    "language": {
      "display": "French",
      "languageCode": "fr"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/fr.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "complete": false,
    "language": {
      "display": "Dutch",
      "languageCode": "nl"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/workflow/nl.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customer": {
                "id": 3006,
                "name": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  }
]

Project "status" values

At its core, Cloudwords offers deep workflow for managing translation projects. The key to understanding where a project is at in its life cycle is through the "status" field. Project status communicates what actions can be taken, or that action is needed before progress on a project can continue. Below is the set of all project status values, and what they mean.

Please note that the project status is a read-only field provided only for informational purpose and may be subject to change. The field contains two attributes: 1) "code" which is a stable field you can program against and 2) "display" which is meant to be human readable.

Status Code	Status Description
configured_project_name	The project has been configured with some basic information, but not all required fields.
configured_project_details	The project has all required information configured, but does not have source materials uploaded yet.
uploaded_source_materials	The project has all required information configured, and has source materials uploaded.
configured_bid_options	The project has bidding options configured, but has yet to request bids.
submitted_for_bids	The project has been submitted for bids to the appropriate vendors.
waiting_for_bid_selection	Bidding has closed for the project and is awaiting a bid selection by the customer.
bid_selection_expired	The customer did not select a winning bid before the "bidSelectDeadlineDate". The project has now been reverted back to creation state.
in_translation	A bid has been selected and the project is currently in translation.
in_review	The vendor has delivered all translations for the project. Review each language deliverable's status to see if it is waiting for approval, been approved, or is currently in revision.
change_order_requested	A change order has been requested by the customer, and is currently in the change order workflow process.
all_languages_approved	The customer has approved all translations for the project.
in_cancellation_waiting_for_vendor	The customer is requesting cancellation of the project, and is awaiting an vendor cancellation bid.
in_cancellation_waiting_for_customer	A vendor cancellation bid has been submitted, and is awaiting customer approval.
project_closed	The project is closed and requires no further action.
cancelled	The project has been cancelled and requires no further action.

Project UI Features

Version(s)
1.1

The Create and Update project methods allow an integrator to disable certain features of the Cloudwords Web UI. This allows an integration to avoid issues that may arise if a user modifies vital parts of a Project in the Project Wizard or through a Change Order. The features can be accessed through the uiFeatures property of a Project. When a project is retrieved, the current value of all possible features will be reported. By default, the value of a feature is true, this means the operation specified is permitted in the Cloudwords Web UI (that is, if change_source_material is true, the user will be allowed to upload new source materials in the Project Wizard, Source Files tab, or by creating a Change Order). Depending on the status of a project, the operation may not be possible, even if the value is true.

UI features do not apply to the Cloudwords API. Disabling a certain operation via a feature will not prevent an API call from performing that operation. Features may be updated at any time on a project, including at project creation.

Feature Code	Default Value	Description
launch_project	`true`	If set to false, the Project Wizard prevents the project from being launched. This flag can be set to false while source files are being added to the project. Once all source files have been added, this flag can then be set to true to allow the project to proceed.
change_source_material	`true`	If set to false, the source materials (but not reference materials) of a project will be locked in the Project Wizard and "Source Files" tab. Additionally, the user will not be able to upload new source files during a Change Order.
change_source_language	`true`	If set to false, the source language will be locked in the Project Wizard.
change_target_languages	`true`	If set to false, the target languages of a project will be locked in the Project Wizard and "Edit Project" page. Additionally, the user will not be able to change target languages via a Change Order.
clone_project	`true`	If set to false, the project cannot be cloned. This prevents the user from creating a copy of the Project, which an integrating system would not know about.

Project Source Material Methods

Upload Source Bundle

Upload or update/overwrite the source bundle for the specified project.
Note: Source materials may only be uploaded/updated before a project has been submitted for bids.
As of release 1.14, uploading a ZIP to this call will cause the ZIP to be extracted, and each file in the ZIP will be added to the list of source documents, all existing source is replaced by this operation.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source

Version(s)
1

Method(s)
PUT

Returns
A new/updated metadata file resource for the project's source material.

Request Body
A multipart upload which consists of a zip file that contains the project's source material. The multipart parameter name for the file being uploaded is "file".

Sample JSON response:

{
	"filename": "marketing_materials.zip",
	"id": 2395,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/source/content",
	"sizeInKilobytes": 1256,
	"fileContents": "sales_datasheet.pdf, corporate_deck.ppt",
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/source.json"
}

Add Source Document

Source documents may be added before a bid request is created. At least one source document must exist to create a bid request. To upload multiple source documents simultaneously, upload a ZIP to the "Upload Source Bundle" call documented above. Note that the "Upload Source Bundle" call replaces all current source with the uploaded file(s). The call documented here does not replace files.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document

Version
1.14+

Method
POST

Request Body
A multipart upload which contains a file. The multipart parameter name for the file being uploaded is "file".

Returns
The metadata for the uploaded file, including the ID and path.

Sample JSON response:

{
    "path": "https://api.cloudwords.com/1.14/project/425/file/source/document/997.json",
    "id": 997,
    "file": {
        "path": "",
        "id": 2160,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/425/file/source/document/997/content",
        "sizeInKilobytes": 62,
        "fileContents": "",
        "createdDate": "2014-09-21T21:20:47.000+0000"
    }
}

Replace Source Document

Source documents may be replaced before a bid request is created.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>

Version
1.14+

Method
PUT

Request Body
A multipart upload which contains a file. The multipart parameter name for the file being uploaded is "file".

Returns
The metadata for the uploaded file, including the ID and path.

Sample JSON response:

{
    "path": "https://api.cloudwords.com/1.14/project/425/file/source/document/997.json",
    "id": 997,
    "file": {
        "path": "",
        "id": 2160,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/425/file/source/document/997/content",
        "sizeInKilobytes": 62,
        "fileContents": "",
        "createdDate": "2014-09-21T21:20:47.000+0000"
    }
}

Delete Source Document

Source documents may be removed before a bid request is created. Note that this operation has no response body, the HTTP status code indicates the success of the operation. A response body may be returned if the operation fails (i.e. because the document does not exist).

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>

Version
1.14+

Method
DELETE

Returns
HTTP status code only (200 for success)

Get Source Bundle

Get the source material metadata for the specified project.

Note: As of release 1.14, this object now represents the source bundle, which is generated automatically when a bid request is created for the project. For projects that have not yet been sent out to bid, the source material call may return an HTTP 404 response. It is recommended that all API users use the Source Documents call to retrieve project source.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source.json

Version(s)
1

Method(s)
GET

Returns
A metadata file resource for the project's source material.

Sample JSON response:

{
	"filename": "marketing_materials.zip",
	"id": 2395,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/source/content",
	"sizeInKilobytes": 1256,
	"fileContents": "sales_datasheet.pdf, corporate_deck.ppt",
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/source.json"
}

Download Source Bundle

Get the source material bundle's binary data for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/content

Version(s)
1

Method(s)
GET

Returns
A stream containing a binary file (zip) that contains the project's source material.

Get Source Documents

Get the individual documents that are to be translated as part of the project. This object will include a reference to a downloadable file under the 'file' attribute. An additional version of the file, in XLIFF format may also be provided. Note that the XLIFF version of the file is not generated until a bid request is created for the project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document.json

Version
1.14+

Method
GET

Request Body
A multipart upload which contains a file. The multipart parameter name for the file being uploaded is "file".

Returns
The list of source documents to be translated

Sample JSON response:

[{
    "path": "https://api.cloudwords.com/1.14/project/429/file/source/document/965.json",
    "id": 965,
    "file": {
        "path": "",
        "id": 2078,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/965/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-18T22:40:46.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 2081,
        "filename": "File-by-FileReview-ProjectWorkflow.docx.xlf",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/965/xliff",
        "sizeInKilobytes": 5,
        "fileContents": "",
        "createdDate": "2014-09-18T22:42:01.000+0000"
    }
}, {
    "path": "https://api.cloudwords.com/1.14/project/429/file/source/document/966.json",
    "id": 966,
    "file": {
        "path": "",
        "id": 2079,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/966/content",
        "sizeInKilobytes": 62,
        "fileContents": "",
        "createdDate": "2014-09-18T22:40:47.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 2082,
        "filename": "PaymentCards.docx.xlf",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/966/xliff",
        "sizeInKilobytes": 29,
        "fileContents": "",
        "createdDate": "2014-09-18T22:42:03.000+0000"
    }
}, {
    "path": "https://api.cloudwords.com/1.14/project/429/file/source/document/967.json",
    "id": 967,
    "file": {
        "path": "",
        "id": 2080,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/967/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-18T22:40:49.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 2083,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api.cloudwords.com/1.14/project/429/file/source/document/967/xliff",
        "sizeInKilobytes": 4,
        "fileContents": "",
        "createdDate": "2014-09-18T22:42:04.000+0000"
    }
}
]

Get Source Document by ID

Get an individual document that is to be translated as part of the project. This object will include a reference to a downloadable file under the 'file' attribute. An additional version of the file, in XLIFF format may also be provided under the property 'xliff'. Note that the XLIFF version of the file is not generated until a bid request is created for the project.

If an XLIFF file is uploaded as a source document, the metadata will not have a 'file' property, instead, the XLIFF information is available through the 'xliff' property.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>.json

Version
1.14+

Method
GET

Request Body
A multipart upload which contains a file. The multipart parameter name for the file being uploaded is "file".

Returns
The list of source documents to be translated

Sample JSON response:

{
    "path": "https://api.cloudwords.com/1.14/project/432/file/source/document/992.json",
    "id": 992,
    "file": {
        "path": "",
        "id": 2152,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/432/file/source/document/992/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-19T22:14:07.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 2172,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api.cloudwords.com/1.14/project/432/file/source/document/992/xliff",
        "sizeInKilobytes": 4,
        "fileContents": "",
        "createdDate": "2014-09-22T21:32:44.000+0000"
    }
}

Download Source Document by ID

Source documents can be represented in two forms, original and XLIFF. In cases where the original file is an XLIFF, only the /xliff call will work. For cases where the original file is not XLIFF, the /content call must be used. For certain formats, Cloudwords can automatically extract XLIFF from the original. In these cases, both /content and /xliff will return data. The /content call will return the original, where the /xliff call will return the derived XLIFF. The Get Source Document By ID call will return a file property (for /content) and an xliff property (for /xliff). If one of these properties is not set, the corresponding call below will return a status of 404.

URL Structure for File
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>/content

URL Structure for XLIFF
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>/xliff

Version
1.14+

Method
GET

Returns
The content of the document.

Upload Source Preview Bundle

The source preview bundle allows users to view source text in-context within Cloudwords. A preview bundle should be uploaded for each source document that is uploaded to a project. The preview bundle should be a zip file containing one html file and all referenced local resources to view the rendered asset.

URL Structure
<base_uri>/<version>/project/<project_id>/file/source/document/<document_id>/preview

Version(s)
1.16+

Method(s)
PUT

Returns
HTTP status code only (200 for success)

Request body:

A multipart upload which consists of a zip file that contains the preview bundle. The multipart parameter name for the file being uploaded is "file".

Project Reference Material Methods

Get All Reference Materials

Get a list of reference materials file metadata for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/reference.json

Version(s)
1

Method(s)
GET

Returns
A list of metadata file resources for the project's reference materials.

Sample JSON response:

[{
	"filename": "about_my_company.docx",
	"id": 2396,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2396/content",
	"sizeInKilobytes": 12,
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2396.json"
},
{
	"filename": "fun_facts.pdf",
	"id": 2397,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2397/content",
	"sizeInKilobytes": 12,
	"createdDate": "2011-05-18T00:55:12.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2397.json"
}]

Get a Reference Material

Get reference material file metadata for the specified project and reference material.

URL Structure
<base_uri>/<version>/project/<project_id>/file/reference/<reference_id>.json

Version(s)
1

Method(s)
GET

Returns
A metadata file resource for a given reference material

Sample JSON response:

{
	"filename": "about_my_company.docx",
	"id": 2396,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2396/content",
	"sizeInKilobytes": 12,
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2396.json"
}

Download Reference Material

Get reference material binary data for the specified project and reference material.

URL Structure
<base_uri>/<version>/project/<project_id>/file/reference/<reference_id>/content

Version(s)
1

Method(s)
GET

Returns
A stream containing the content of the reference document.

Upload Reference Material

Upload new reference material for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/reference

Version(s)
1

Method(s)
POST

Returns
A metadata file resource for the newly created reference material.

Request Body
A multipart upload which contains the reference material document. The multipart parameter name for the file being uploaded is "file".

Sample JSON response:

{
	"filename": "about_my_company.docx",
	"id": 2395,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2395/content",
	"sizeInKilobytes": 12,
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2395.json"
}

Update Reference Material

Upload new version of an existing reference material for the specified project and reference material.

URL Structure
<base_uri>/<version>/project/<project_id>/file/reference/<reference_id>

Version(s)
1

Method(s)
PUT

Returns
A metadata file resource for the newly updated reference material.

Request Body
A multipart upload which contains the reference material document. The multipart parameter name for the file being uploaded is "file".

Sample JSON response:

{
	"filename": "about_my_company_take_2.docx",
	"id": 2395,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2395/content",
	"sizeInKilobytes": 13,
	"createdDate": "2011-05-18T01:30:5100+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2395.json"
}

Bid Request Methods

Note: Bid Request Methods are deprecated as of API version 1.19. Use Translation Requests instead.

Get Bid Request

Get the most recently created bid request for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/bid-request/current.json

Version(s)
1

Method(s)
GET

Returns
The latest bid request for the given project.

Sample JSON response:

{
   "doLetCloudwordsChoose": false,
   "preferredVendors": [{
	   "name": "Turk Translations",
	   "id": 3296,
	   "path": "https://api.cloudwords.com/1/vendor/3296.json"
   }],
   "createdDate": "2011-07-11T18:45:12.000+0000",
   "doAutoSelectBidFromVendor": false,
   "winningBidId": 31606,
   "path": "https://api.cloudwords.com/1/project/20127/bid-request/current.json"
}

Note: The "doAutoSelectBidFromVendor" field enables automatic selection and approval of a vendor bid once it has been submitted. This means that the Project will instantly move into translation once the Vendor has provided their bid, and therefore you will not have the ability to review and reject the submitted Vendor bid. However, you can always choose to cancel the Project at any time. Setting This option is only possible for this BidRequest if you select a single preferred Vendor and you DO NOT have the doLetCloudwordsChoose option enabled.

Create Bid Request

Create a new bid request for the specified project.
Note: A project must have source materials uploaded for it, and can not be in any active bid request or state of translation to successfully launch a bid request.

URL Structure
<base_uri>/<version>/project/<project_id>/bid-request

Version(s)
1

Method(s)
POST

Returns
A metadata file resource for the newly created bid request.

Sample JSON request:

{
	"doLetCloudwordsChoose": false,
	"preferredVendors": [{
		"id": 3037
	}],
	"doAutoSelectBidFromVendor": false,
}

Select a Winning Bid

Select a winning bid for the specified project.
Note: The bid specified in the "winningBidId" field must be from the most recent bid request for the specified project, and the bid must have a status of "submitted".

URL Structure
<base_uri>/<version>/project/<project_id>/bid-request

Method(s)
PUT

Returns
The associated bid request resource.

Sample JSON request:

{
	"winningBidId": 123145
}

Bid Methods

Get All Bids

Get all vendor bids for the most recently created bid request for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/bid.json

Method(s)
GET

Returns
Bid resources for the most recently created bid request for the specified project.

Sample JSON response:

[{
   "id" : 1254
   "vendor" : {
	   "name": "Turk Translations",
	   "id": 3037
   },
	"status" : {

code: "submitted",

display: "Submitted"
   }
   "description": "Blah blah blah",
   "amount" : $12,011,
   "createdDate": "2011-07-11T18:45:12.000+0000"",
   "path": "https://api.cloudwords.com/1/project/129/bid/1254.json"
},
{
   "id" : 1255
   "vendor" : {
	   "name": "Go Global Linguistics",
	   "id": 3038
   },
	"status" : {

code: "vendor_accepted",

display: "Vendor Accepted"
   }
   "description": "Blah blah blah",
   "amount" : 0.00,
   "createdDate": "2011-07-11T18:45:12.000+0000"",
   "path": "https://api.cloudwords.com/1/project/129/bid/1255.json"
}
]

Get Bid

Get the specified vendor bid for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/bid/<bid_id>.json

Method(s)
GET

Returns
The specified bid resource.

Sample JSON response:

{
   "id" : 1254
   "vendor" : {
	   "name": "Turk Translations",
	   "id": 3037
   },
   "status" : {
code: "submitted",
display: "Submitted"
   }
   "description": "Blah blah blah",
   "amount" : $12,011,
   "createdDate": "2011-07-11T18:45:12.000+0000",
   "path": "https://api.cloudwords.com/1/project/129/bid/1254.json"
}

Bid "Status" Values

Please note that the bid status is a read-only field provided only for informational purpose and may be subject to change. The field contains two attributes: 1) "code" which is a stable field you can program against and 2) "display" which is meant to be human readable.

Code	Description
Status Code	Status Description
waiting_for_vendor	The vendor has been notified of your request, but has yet to accept or reject the request.
vendor_accepted	The vendor has accepted you bid request, but has yet to submit a completed bid.
submitted	The vendor has submit a completed bid.
customer_accepted	The bid that was selected as the winning bid for the project.
customer_rejected	A bid that was not selected as the winning bid for the project.

Translated Materials Methods

Get Project Translations Bundle

Get the translated "master deliverables" file metadata for the specified project.
Note: The master deliverable file contains all delivered project language translations in one bundled zip.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated.json

Version(s)
1

Method(s)
GET

Returns
A metadata file for the translated "master deliverables" metadata file.

Sample JSON response:

{
	"filename": "cw_deliverables_id1025.zip",
	"id": 2855,
	"contentPath": "https://api.cloudwords.com/1/project/1025/file/translated/content",
	"sizeInKilobytes": 1,
	"fileContents": "ar-kw/keyword_stats_20100914_1403298-01.csv,
					 fr/keyword_stats_20100914_1403298-01.csv",
	"createdDate": "2011-07-11T18:45:12.000+0000",
	"path": "https://api.cloudwords.com/1/project/1025/file/translated.json"
}

Download the Project Translations Bundle

Get the translated "master deliverables" binary data for the specified project.
Note: The master deliverable file contains all delivered project language translations in one bundled zip.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/content

Version(s)
1

Method(s)
GET

Returns
A stream containing a binary file (zip) that contains the translated "master deliverables".

Get All Translated Bundles

Get the list of the per language translation file metadata for the specified project.
Note: Each metadata representation in the list will be specific to a target language.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language.json

Version(s)
1

Method(s)
GET

Returns
List of the per language translation file metadata for the specified project.

Sample JSON response:

[{
   "status": {
	   "code": "approved",
	   "display": "Approved"
   },
   "lang": {
	   "display": "Chinese (Traditional)",
	   "languageCode": "zh-tw"
   },
   "id": 105374,
   "filename": "not_tmx_file.txt.zip",
   "createdDate": "2011-06-23T05:19:39.000+0000",
   "contentPath": "https://api.cloudwords.com/1/project/20127/file/translated/language/zh-tw/content",
   "sizeInKilobytes": 1,
   "fileContents": "not_tm.txt",
   "path": "https://api.cloudwords.com/1/project/20127/file/translated/language/zh-tw.json"
}, {
	"status": {
	   "code": "delivered",
	   "display": "Delivered"
    }, 
    "lang": {
	   "display": "Arabic (Kuwait)",
	   "languageCode": "ar-kw"
    },
   "filename": "zip_training.zip",
   "id": 2883,
   "contentPath": "https://api.cloudwords.com/1/project/1025/file/translated/language/ar-kw/content",
   "sizeInKilobytes": 1,
   "fileContents": "keyword_stats_20100914_1403298-01.csv",
   "createdDate": "2011-07-11T18:43:09.000+0000",
   "path": "https://api.cloudwords.com/1/project/1025/file/translated/language/ar-kw.json"
}]

Get a Translation Bundle by Language

Get a language translation bundle's metadata for the specified project and language.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>.json

Version(s)
1

Method(s)
GET

Returns
A language translation file metadata for the specified project and language.

Sample JSON response:

{
	"status": {
	   "code": "approved",
	   "display": "Approved"
	},
	"lang": {
		"display": "French",
		"languageCode": "fr"
	},
	"filename": "zip_training.zip",
	"id": 2885,
	"contentPath": "https://api.cloudwords.com/1/project/1025/file/translated/language/fr/content",
	"sizeInKilobytes": 1,
	"fileContents": "keyword_stats_20100914_1403298-01.csv",
	"createdDate": "2011-07-11T18:43:1100+0000",
	"path": "https://api.cloudwords.com/1/project/1025/file/translated/language/fr.json"
}

Download Translated Material by Language

Get a language translation bundle's binary data for the specified project and language.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/content

Version(s)
1

Method(s)
GET

Returns
A stream containing a binary file (zip) that contains the translation file's binary data.

Approve a Translated Material

Designates a delivered translated material as approved.
Note: The status of the translated material must be "delivered" in order to be approved, and once a language's translated material is marked as approved it can no longer have a "Revision Request" filed against it. Approving a language closes the current review phase of the project workflow and moves on to the next phase (if any) or closes the translation process for that language.

Note The URL for this call changed in API v1.14, the old URL did not end in .json, the new one does (the URL is otherwise the same).

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>.json

Version(s)
1

Method(s)
PUT

Returns
The associated translated material resource.

Sample JSON request:

{
   "status": {
	   "code": "approved"
   }
}

Get Translated Documents by Language

Get the list of translated documents for a language. The structure for translated documents is similar to source documents with added workflow and revision request information, as well as the ID of the source document from which the file was translated.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document.json

Version(s)
1.14+

Method(s)
GET

Returns
The list of translated documents.

Sample JSON response:

[{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/383.json",
    "id": 383,
    "file": {
        "path": "",
        "id": 744,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/383/content",
        "sizeInKilobytes": 64,
        "fileContents": "",
        "createdDate": "2015-08-04T21:28:08.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 742,
        "filename": "PaymentCards.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/383/xliff",
        "sizeInKilobytes": 56,
        "fileContents": "",
        "createdDate": "2015-08-04T21:27:46.000+0000"
    },
    "status": {
        "display": "Approved",
        "code": "approved"
    },
    "sourceDocumentId": 381
}, {
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384.json",
    "id": 384,
    "file": {
        "path": "",
        "id": 745,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384/content",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-04T21:28:12.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 743,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384/xliff",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-04T21:27:51.000+0000"
    },
    "status": {
        "display": "In Review",
        "code": "in_review"
    },
    "sourceDocumentId": 382,
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 3,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 7,
                "firstName": "Admin",
                "lastName": "Customer",
                "email": "admin@customer.com"
            }
        },
        "dueDate": "2015-08-17T00:00:00.000+0000"
    }
}, {
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/387.json",
    "id": 387,
    "file": {
        "path": "",
        "id": 752,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/387/content",
        "sizeInKilobytes": 8,
        "fileContents": "",
        "createdDate": "2015-08-04T21:39:03.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 750,
        "filename": "File-by-FileReview-ProjectWorkflow.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/387/xliff",
        "sizeInKilobytes": 9,
        "fileContents": "",
        "createdDate": "2015-08-04T21:38:50.000+0000"
    },
    "status": {
        "display": "In Review",
        "code": "in_review"
    },
    "sourceDocumentId": 385,
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 3,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 7,
                "firstName": "Admin",
                "lastName": "Customer",
                "email": "admin@customer.com"
            }
        },
        "dueDate": "2015-08-17T00:00:00.000+0000"
    }
}
]

Get a Translated Document by ID

Get an individual translated document. This operation does not provide more information than the operation above.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document/<document_id>.json

Version(s)
1.14+

Method(s)
GET

Returns
The metadata for an individual translated document.

Sample JSON response:

{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384.json",
    "id": 384,
    "file": {
        "path": "",
        "id": 745,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384/content",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-04T21:28:12.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 743,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32054/file/translated/language/fr/document/384/xliff",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-04T21:27:51.000+0000"
    },
    "status": {
        "display": "In Review",
        "code": "in_review"
    },
    "sourceDocumentId": 382,
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 3,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 7,
                "firstName": "Admin",
                "lastName": "Customer",
                "email": "admin@customer.com"
            }
        },
        "dueDate": "2015-08-17T00:00:00.000+0000"
    }
}

Upload a Translated Document

Upload a new translation for a source document. It is possible to upload a translated document without mapping it to a source file, but in general all translated documents should be mapped. This mapping is accomplished by adding an additional parameter to the standard upload file mechanism. Please see the example below (the source is the second section, ID #274). Note that if an existing document exists with the same source ID, that document will be replaced instead.

The list of valid source IDs can be retrieved via the Get Source Documents call.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document

Version(s)
1.14+

Method(s)
POST

Returns
The metadata for the newly uploaded document.

Sample Request:

------WebKitFormBoundaryY7hFuRT1hogyCWVA
Content-Disposition: form-data; name="file"; filename="ProjectSearchViewArchitecture.docx.xlf"
Content-Type: text/plain


------WebKitFormBoundaryY7hFuRT1hogyCWVA
Content-Disposition: form-data; name="source"

274
------WebKitFormBoundaryY7hFuRT1hogyCWVA--

Sample JSON response:

{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279.json",
    "id": 279,
    "xliff": {
        "path": "",
        "id": 521,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279/xliff",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-07T18:34:26.000+0000"
    },
    "status": {
        "display": "Not Ready",
        "code": "not_ready"
    },
    "sourceDocumentId": 274,
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 2,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customer": {
                "path": "",
                "id": 8236,
                "name": "Customer"
            }
        }
    }
}

Replace Translated Document

This operation allows an individual translated document to be replaced. Replacing a document that is in revision causes the revision request to be automatically closed.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document/<document_id>

Version(s)
1.14+

Method(s)
PUT

Returns
The metadata for the newly uploaded document.

Sample JSON response:

{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279.json",
    "id": 279,
    "xliff": {
        "path": "",
        "id": 521,
        "filename": "ProjectSearchViewArchitecture.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279/xliff",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-07T18:34:26.000+0000"
    },
    "status": {
        "display": "Not Ready",
        "code": "not_ready"
    },
    "sourceDocumentId": 274,
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 2,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customer": {
                "path": "",
                "id": 8236,
                "name": "Customer"
            }
        }
    }
}

Update Translated Document Status

This operation allows approval or revision request for individual translated documents. To approve a document, set the status to 'approved'. To request revision update the status to 'in_revision" and add a "revisionRequest" object as a property. The "revisionRequest" object has one property, 'comment', which is required.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document/<document_id>

Version(s)
1.14+

Method(s)
PUT

Returns
The metadata for the newly uploaded document.

Sample Request:

{
    "path": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/943.json",
    "id": 943,
    "file": {
        "path": "",
        "id": 2020,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/943/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-18T01:55:57.000+0000"
    },
    "status": "in_revision",
    "sourceDocumentId": 931,
    "revisionRequest": {
        "comment": "Please change the translation."
    }
}

Sample JSON Response:

{
    "path": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/943.json",
    "id": 943,
    "file": {
        "path": "",
        "id": 2020,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/943/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-18T01:55:57.000+0000"
    },
    "status": {
        "display": "In Revision",
        "code": "in_revision"
    },
    "sourceDocumentId": 931,
    "revisionRequest": {
        "path": "",
        "comment": "Please change the translation.",
        "creator": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 53,
                "firstName": "Fast",
                "lastName": "Crestas",
                "email": "fast@crestas.com"
            }
        }
    }
}

Mass Update Translated Document Status

This operation allows approval or revision request for multiple translated documents. To approve a document, set the status to 'approved'. To request revision update the status to 'in_revision" and add a "revisionRequest" object as a property. The "revisionRequest" object has one property, 'comment', which is required. Note that approving all documents has the same effect as Approving a Language.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document/<document_id>

Version(s)
1.14+

Method(s)
PUT

Returns
The metadata for the newly uploaded document.

Sample Request:

[{
    "path": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/393.json",
    "id": 393,
    "file": {
        "path": "",
        "id": 2020,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-de/document/393/content",
        "sizeInKilobytes": 6,
        "fileContents": "",
        "createdDate": "2014-09-18T01:55:57.000+0000"
    },
    "status": "in_revision",
    "sourceDocumentId": 391,
    "revisionRequest": {
        "comment": "Please change the translation."
    }
}]

Sample JSON Response:

[{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32055/file/translated/language/de/document/393.json",
    "id": 393,
    "file": {
        "path": "",
        "id": 792,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32055/file/translated/language/de/document/393/content",
        "sizeInKilobytes": 64,
        "fileContents": "",
        "createdDate": "2015-08-04T22:35:21.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 767,
        "filename": "PaymentCards.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32055/file/translated/language/de/document/393/xliff",
        "sizeInKilobytes": 55,
        "fileContents": "",
        "createdDate": "2015-08-04T22:35:07.000+0000"
    },
    "status": {
        "display": "In Revision",
        "code": "in_revision"
    },
    "sourceDocumentId": 391,
    "revisionRequest": {
        "path": "",
        "comment": "Please change the translation.",
        "creator": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 7,
                "firstName": "Admin",
                "lastName": "Customer",
                "email": "admin@customer.com"
            }
        }
    },
    "currentStep": {
        "path": "",
        "stepNumber": 1,
        "name": "Initial Translation"
    },
    "currentPhase": {
        "path": "",
        "phaseNumber": 3,
        "assigneeType": {
            "display": "Internal",
            "code": "customer_user"
        },
        "phaseType": {
            "display": "Review",
            "code": "review"
        },
        "allowRevision": true,
        "assignee": {
            "path": "",
            "customerUser": {
                "path": "",
                "id": 7,
                "firstName": "Admin",
                "lastName": "Customer",
                "email": "admin@customer.com"
            }
        },
        "dueDate": "2015-08-24T00:00:00.000+0000"
    }
} ]

Deliver Translated Documents

The status of a translated material can be updated to two different values: 'approved' and 'delivered'. Updating the status to 'approved' has the same effect as updating each document to the approved status (this can also be accomplished with the call above). Updating the status to 'delivered' is used to complete the work phase of a workflow, after uploading one or more translated documents.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>.json

Version(s)
1.14+

Method(s)
PUT

Returns
The metadata for the translated material.

Sample Request:

{
    "path": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-lu.json",
    "filename": "",
    "contentPath": "",
    "sizeInKilobytes": "",
    "fileContents": "",
    "createdDate": "",
    "lang": {
        "display": "German (Luxembourg)",
        "languageCode": "de-lu"
    },
    "status": "delivered"
}

Sample JSON Response:

{
    "path": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-lu.json",
    "filename": "",
    "contentPath": "",
    "sizeInKilobytes": "",
    "fileContents": "",
    "createdDate": "",
    "lang": {
        "display": "German (Luxembourg)",
        "languageCode": "de-lu"
    },
    "status": {
        "display": "Syncing",
        "code": "syncing"
    }
}

Translated Material "Status" Values

The translated material's "status" field specifies where that deliverable is in the project workflow.

Please note that the status field is a read-only field provided only for informational purpose and may be subject to change. The field contains two attributes: 1) "code" which is a stable field you can program against and 2) "display" which is meant to be human readable.

Status Code	Status Description
not_delivered	The deliverable for the specified language has not been delivered by the vendor.
delivered	The deliverable for the specified language has been delivered by the vendor and is awaiting approval or revision request.
in_revision	The deliverable for the specified language has revisions requested, and is currently being reviewed by the vendor.
approved	The deliverable for the specified language has been approved, and no further action is required.
syncing	The deliverable for the specified language is currently being synced to an external system.

Upload Translation Preview Bundle

The preview bundle allows reviewers to view and revise translations in-context within Cloudwords. A preview bundle should be uploaded each time a new deliverable is retrieved from Cloudwords and processed within the integrating system. The preview bundle should be a zip file containing one html file and all referenced local resources to view the rendered asset. Each translated document should have its own preview bundle. Each time a preview bundle is uploaded, it replaces any previous preview bundle for that translated document.

URL Structure
<base_uri>/<version>/project/<project_id>/file/translated/language/<language_code>/document/<document_id>/preview

Version(s)
1.16+

Method(s)
PUT

Returns
HTTP status code only (200 for success)

Request body:

A multipart upload which consists of a zip file that contains the preview bundle. The multipart parameter name for the file being uploaded is "file".

Reviewer Instructions

Get Reviewer Instructions by Project and Target Language

Get the reviewer instructions for a project's target language from Cloudwords.

URL Structure
<base_uri>/<version>/project/<project_id>/language/<language_code>/reviewer-instructions.json

Version(s)
1.11

Method(s)
GET

Returns
The instructions for the reviewer for a specific project and target language.

Sample JSON response:

{
	"id": 123,
	"content": "Login to the CMS and review the source and translated materials.",
	"path": "https://api.cloudwords.com/1/reviewer-instructions/123.json"
}

Get Reviewer Instructions

Get the reviewer instructions for a project's target language from Cloudwords.

URL Structure
<base_uri>/<version>/reviewer-instructions/<reviewer_instructions_id>.json

Version(s)
1.11

Method(s)
GET

Returns
The instructions for the reviewer for a specific project and target language.

Sample JSON response:

{
	"id": 123,
	"content": "Login to the CMS and review the source and translated materials.",
	"path": "https://api.cloudwords.com/1/reviewer-instructions/123.json"
}

Create Reviewer Instructions

Create the reviewer instructions for a project's target language in Cloudwords.
Note: The language_code must be a target language for the project.

URL Structure
<base_uri>/<version>/project/<project_id>/language/<language_code>/reviewer-instructions

Version(s)
1.11

Method(s)

POST

Returns
The metadata associated with the created reviewer instructions.

Required Fields
content

Not Settable Fields
id

Field Restrictions

Field Name	Version(s)	Note
content	1.11	Must be 5000 characters or less in length.

Sample JSON request:

{
	  "content": "Login to the CMS and review the source and translated material."
}

Sample JSON response:

{
	"id": 1001,
	"content": "Login to the CMS and review the source and translated material.",
	"path": "https://api.cloudwords.com/1/reviewer-instructions/1001.json"
}

Update Reviewer Instructions

Update the reviewer instructions for a project's target language in Cloudwords.

URL Structure
<base_uri>/<version>/reviewer-instructions/<reviewer-instructions_id>

Version(s)
1.11

Method(s)

PUT

Returns
The metadata associated with the updated reviewer instructions.

Changeable Fields
content

Not Settable Fields
id

Field Restrictions
See "Field Restrictions" in Create Reviewer Instructions section above.

Sample JSON request:

{
	  "content": "Login to the CMS and review the source and translated material."
}

Sample JSON response:

{
	"id": 1001,
	"content": "Login to the CMS and review the source and translated material.",
	"path": "https://api.cloudwords.com/1/reviewer-instructions/1001.json"
}

Delete Reviewer Instructions

Delete the reviewer instructions for a project's target language in Cloudwords.

URL Structure
<base_uri>/<version>/reviewer-instructions/<reviewer-instructions_id>

Version(s)
1.11

Method(s)

DELETE

Project Task Methods

Project Task "status" and "type" values

Translation project management in Cloudwords revolves around a series of tasks that need to be resolved for the translation project to be successfully completed. Many types of tasks are generated and managed automatically by Cloudwords to facilitate the standard translation workflows offered. Or, certain types of tasks (e.g. "custom" and "revise_language" types) can be created by the developer at any time to enhance, augment, or inject custom workflow and processes into a translation project.

Status field

Cloudwords tasks can go through various stages or statuses as they are managed. Below is the set of all project status values, and what they mean.
Please note that the project status is a read-only field provided only for informational purpose and may be subject to change. The field contains two attributes: 1) "code" which is a stable field you can program against and 2) "display" which is meant to be human readable.

Status Code	Status Description
open	The task is open and, depending on the task's start date, should be resolved.
closed	The task is closed, which means it has been completed and no further action is needed.
rejected	The task has been rejected by it's assignee, which generally means the assigneed does not believe the task to be valid or is impossible to complete.
cancelled	The task has been cancelled, and no further action is needed.

Type field

Cloudwords supports a large variety of Task types, most of which are created and managed by the Cloudwords application and standard workflows. However, the task types described below can be used to explicitly create tasks by the developer to enhance and extend translation and process worfklow as needed.

Type Code	Type Description
custom	A custom task that can be defined and described in whatever manner needed. For example, you can use this type to create a task named and described to fit whatever workflow you need. For example, you can create tasks with names like: "Build the staging environment", "Please provide the Purchase Order number", etc.
revise_language	The type used to request a revision of a delivered translation by a vendor. This type MUST be accompanied by the "target_language" field being populated, and the language specified must have a deliverable that has not yet been approved and does not have an existing open "revise_language" task.

Get Project Tasks

Get the list of all tasks for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/task.json

Version(s)
1

Method(s)
GET

Returns
A list of all tasks for the specified project.

Sample JSON response:

[{
		"name": "Build German QA environment",
		"id": 6693,
		"type": {
			"code": "custom",
			"display": "Custom"
		},
		"description": "Joe, please build the German QA environment with the delivered German translation from Turk Translation. Please post a comment to this task with the proper endpoint and credentials when ready.",
		"status": {
			"code": "open",
			"display": "Open"
		},
		"dueDate": "2012-07-20T00:18:50.000+0000",
		"emailReminderDay": "2012-07-18T00:18:50.000+0000",
		"startDate": "2012-07-14T00:18:50.000+0000",
		"project": {
			"name": "My first translation project",
			"id": 119,
			"path": "https://api.cloudwords.com/1/project/951.json"
		},
		"followers": [{
			"vendor": "",
			"customerUser": {
				"id": 6,
				"firstName": "Joe",
				"lastName": "Johnson",
				"path": "",
				"email" : "jjohnson@example.org"
			},
			"path": ""
		}, {
			"vendor": {
				"name": "Cloud",
				"id": 3000,
				"path": "https://api.cloudwords.com/1/vendor/3000.json"
			},
			"customerUser": "",
			"path": ""
		}],
		"targetLanguage": {
			"display": "German",
			"languageCode": "de"
		},
		"assignee": {
			"customer": "",
			"projectFollowers": "",
			"vendor": {
				"name": "Turk Translations",
				"id": 3296,
				"path": "https://api.cloudwords.com/1/vendor/3000.json"
			},
			"customerUser": "",
			"path": ""
		},
		"creatorUser": {
			"id": 6,
			"firstName": "Joe",
			"lastName": "Johnson",
			"path": "",
			"email" : "jjohnson@example.org"
		},
		"creatorCustomer": {
			"name": "Acme, Inc.",
			"id": 3001,
			"path": ""
		},
		"createdDate": "2012-07-13T00:18:50.000+0000",
		"closedDate": "",
		"path": "https://api.cloudwords.com/1/project/951/task/6693.json"
	}, {
		"followers": [{
			"vendor": "",
			"customerUser": {
				"id": 3,
				"firstName": "John",
				"lastName": "Lennon",
				"path": "",
				"email" : "jlennon@example.org"
			},
			"path": ""
		}, {
			"vendor": "",
			"customerUser": {
				"id": 51,
				"firstName": "George",
				"lastName": "Harrison",
				"path": "",
				"email" : "gharrison@example.org"
			},
			"path": ""
		}, {
			"vendor": "",
			"customerUser": {
				"id": 237,
				"firstName": "Ringo",
				"lastName": "Star",
				"path": "",
				"email" : "rstar@example.org"
			},
			"path": ""
		}, {
			"vendor": "",
			"customerUser": {
				"id": 413,
				"firstName": "Mike",
				"lastName": "Lassetter",
				"path": "",
				"email" : "mlassetter@example.org"
			},
			"path": ""
		}, {
			"vendor": {
				"name": "Decca International",
				"id": 3021,
				"path": "https://api.cloudwords.com/1/vendor/3021.json"
			},
			"customerUser": "",
			"path": ""
		}],
		"assignee": {
			"customer": "",
			"projectFollowers": "",
			"vendor": {
				"name": "Decca International",
				"id": 3021,
				"path": "https://api.cloudwords.com/1/vendor/3021.json"
			},
			"customerUser": "",
			"path": ""
		},
		"creatorUser": {
			"id": 3,
			"firstName": "John",
			"lastName": "Lennon",
			"path": "",
			"email" : "jlennon@example.org"
		},
		"name": "Bad character encodings found",
		"id": 1747,
		"type": {
			"code": "revise_language",
			"display": "Revise Language"
		},
		"description": "Please fixup these translations",
		"status": {
			"code": "open",
			"display": "Open"
		},
		"dueDate": "2012-05-21T22:17:31.000+0000",
		"emailReminderDay": "",
		"startDate": "",
		"project": {
			"name": "My second translation project!",
			"id": 2545,
			"path": "https://api.cloudwords.com/1/project/2545.json"
		},
		"targetLanguage": {
			"display": "Chinese (Traditional)",
			"languageCode": "zh-tw"
		},
		"createdDate": "2012-05-21T22:17:31.000+0000",
		"creatorCustomer": {
			"name": "Acme, Inc",
			"id": 3001,
			"path": ""
		},
		"closedDate": "",
		"path": "https://api.cloudwords.com/1/project/2545/task/1747.json"
	}]

Get Project Tasks with Status

Get the list of all tasks for the specified project with a given status. See the Project Task "status" and "type" values section to see the list of valid statuses.

URL Structure
<base_uri>/<version>/project/<project_id>/task/status/<status>.json

Version(s)
1

Method(s)
GET

Returns
Get the list of all tasks for the specified project with a given status.

Sample JSON response:

[{
	"name": "Build German QA environment",
	"id": 6693,
	"type": {
		"code": "custom",
		"display": "Custom"
	},
	"description": "Joe, please build the German QA environment with the delivered German translation from Turk Translation. Please post a comment to this task with the proper endpoint and credentials when ready.",
	"status": {
		"code": "open",
	"display": "Open"
	},
	"dueDate": "2012-07-20T00:18:50.000+0000",
	"emailReminderDay": "2012-07-18T00:18:50.000+0000",
	"startDate": "2012-07-14T00:18:50.000+0000",
	"project": {
		"name": "My first translation project",
		"id": 119,
		"path": "https://api.cloudwords.com/1/project/951.json"
	},
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 6,
			"firstName": "Joe",
			"lastName": "Johnson",
			"path": "",
			"email" : "jjohnson@example.org"
		},
		"path": ""
		}, {
			"vendor": {
			"name": "Cloud",
			"id": 3000,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"targetLanguage": {
		"display": "German",
		"languageCode": "de"
	},
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Turk Translations",
			"id": 3296,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 6,
		"firstName": "Joe",
		"lastName": "Johnson",
		"path": "",
		"email" : "jjohnson@example.org"
	},
	"creatorCustomer": {
		"name": "Acme, Inc.",
		"id": 3001,
		"path": ""
	},
	"createdDate": "2012-07-13T00:18:50.000+0000",
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/951/task/6693.json"
}, {
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 3,
			"firstName": "John",
			"lastName": "Lennon",
			"path": "",
			"email" : "jlennon@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 51,
			"firstName": "George",
			"lastName": "Harrison",
			"path": "",
			"email" : "gharrison@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 237,
			"firstName": "Ringo",
			"lastName": "Star",
			"path": "",
			"email" : "rstar@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 413,
			"firstName": "Mike",
			"lastName": "Lassetter",
			"path": "",
			"email" : "mlassetter@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
	"customerUser": "",
	"path": ""
	},
	"creatorUser": {
		"id": 3,
		"firstName": "John",
		"lastName": "Lennon",
		"path": "",
		"email" : "jlennon@example.org"
	},
	"name": "Bad character encodings found",
	"id": 1747,
	"type": {
		"code": "revise_language",
		"display": "Revise Language"
	},
	"description": "Please fixup these translations",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-05-21T22:17:31.000+0000",
	"emailReminderDay": "",
	"startDate": "",
	"project": {
		"name": "My second translation project!",
		"id": 2545,
		"path": "https://api.cloudwords.com/1/project/2545.json"
	},
	"targetLanguage": {
		"display": "Chinese (Traditional)",
		"languageCode": "zh-tw"
	},
	"createdDate": "2012-05-21T22:17:31.000+0000",
	"creatorCustomer": {
		"name": "Acme, Inc",
		"id": 3001,
		"path": ""
	},
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/2545/task/1747.json"
}]

Get Project Task

Get a specified task for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/task/<task_id>.json

Version(s)
1

Method(s)
GET

Returns
A specified task for the specified project.

Sample JSON response:

[{
	"name": "Build German QA environment",
	"id": 6693,
	"type": {
		"code": "custom",
		"display": "Custom"
	},
	"description": "Joe, please build the German QA environment with the delivered German translation from Turk Translation. Please post a comment to this task with the proper endpoint and credentials when ready.",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-07-20T00:18:50.000+0000",
	"emailReminderDay": "2012-07-18T00:18:50.000+0000",
	"startDate": "2012-07-14T00:18:50.000+0000",
	"project": {
		"name": "My first translation project",
		"id": 119,
		"path": "https://api.cloudwords.com/1/project/951.json"
	},
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 6,
			"firstName": "Joe",
			"lastName": "Johnson",
			"path": "",
			"email" : "jjohnson@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Cloud",
			"id": 3000,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"targetLanguage": {
		"display": "German",
		"languageCode": "de"
	},
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Turk Translations",
			"id": 3296,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 6,
		"firstName": "Joe",
		"lastName": "Johnson",
		"path": "",
		"email" : "jjohnson@example.org"
	},
	"creatorCustomer": {
		"name": "Acme, Inc.",
		"id": 3001,
		"path": ""
	},
	"createdDate": "2012-07-13T00:18:50.000+0000",
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/951/task/6693.json"
}]

Get All Project Tasks

Get the list of all tasks across all projects.

URL Structure
<base_uri>/<version>/task.json

Version(s)
1

Method(s)
GET

Returns
A list of all tasks across all projects.

Sample JSON response:

[{
	"name": "Build German QA environment",
	"id": 6693,
	"type": {
		"code": "custom",
		"display": "Custom"
	},
	"description": "Joe, please build the German QA environment with the delivered German translation from Turk Translation. Please post a comment to this task with the proper endpoint and credentials when ready.",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-07-20T00:18:50.000+0000",
	"emailReminderDay": "2012-07-18T00:18:50.000+0000",
	"startDate": "2012-07-14T00:18:50.000+0000",
	"project": {
		"name": "My first translation project",
		"id": 119,
		"path": "https://api.cloudwords.com/1/project/951.json"
	},
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 6,
			"firstName": "Joe",
			"lastName": "Johnson",
			"path": "",
			"email" : "jjohnson@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Cloud",
			"id": 3000,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"targetLanguage": {
		"display": "German",
		"languageCode": "de"
	},
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Turk Translations",
			"id": 3296,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 6,
		"firstName": "Joe",
		"lastName": "Johnson",
		"path": "",
		"email" : "jjohnson@example.org"
	},
	"creatorCustomer": {
		"name": "Acme, Inc.",
		"id": 3001,
		"path": ""
	},
	"createdDate": "2012-07-13T00:18:50.000+0000",
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/951/task/6693.json"
}, {
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 3,
			"firstName": "John",
			"lastName": "Lennon",
			"path": "",
			"email" : "jlennon@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 51,
			"firstName": "George",
			"lastName": "Harrison",
			"path": "",
			"email" : "gharrison@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 237,
			"firstName": "Ringo",
			"lastName": "Star",
			"path": "",
			"email" : "rstar@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 413,
			"firstName": "Mike",
			"lastName": "Lassetter",
			"path": "",
			"email" : "mlassetter@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 3,
		"firstName": "John",
		"lastName": "Lennon",
		"path": "",
		"email" : "jlennon@example.org"
	},
	"name": "Bad character encodings found",
	"id": 1747,
	"type": {
		"code": "revise_language",
		"display": "Revise Language"
	},
	"description": "Please fixup these translations",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-05-21T22:17:31.000+0000",
	"emailReminderDay": "",
	"startDate": "",
	"project": {
		"name": "My second translation project!",
		"id": 2545,
		"path": "https://api.cloudwords.com/1/project/2545.json"
	},
	"targetLanguage": {
		"display": "Chinese (Traditional)",
		"languageCode": "zh-tw"
	},
	"createdDate": "2012-05-21T22:17:31.000+0000",
	"creatorCustomer": {
		"name": "Acme, Inc",
		"id": 3001,
		"path": ""
	},
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/2545/task/1747.json"
}]

Get All Project Tasks With Status

Get the list of all tasks across all projects with the specified status. See the Project Task "status" and "type" values section to see the list of valid statuses.

URL Structure
<base_uri>/<version>/task/status/<status>.json

Version(s)
1

Method(s)
GET

Returns
Get the list of all tasks across all projects with the specified status.

Sample JSON response:

[{
	"name": "Build German QA environment",
	"id": 6693,
	"type": {
		"code": "custom",
		"display": "Custom"
	},
	"description": "Joe, please build the German QA environment with the delivered German translation from Turk Translation. Please post a comment to this task with the proper endpoint and credentials when ready.",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-07-20T00:18:50.000+0000",
	"emailReminderDay": "2012-07-18T00:18:50.000+0000",
	"startDate": "2012-07-14T00:18:50.000+0000",
	"project": {
		"name": "My first translation project",
		"id": 119,
		"path": "https://api.cloudwords.com/1/project/951.json"
	},
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 6,
			"firstName": "Joe",
			"lastName": "Johnson",
			"path": "",
			"email" : "jjohnson@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Cloud",
			"id": 3000,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"targetLanguage": {
		"display": "German",
		"languageCode": "de"
	},
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Turk Translations",
			"id": 3296,
			"path": "https://api.cloudwords.com/1/vendor/3000.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 6,
		"firstName": "Joe",
		"lastName": "Johnson",
		"path": "",
		"email" : "jjohnson@example.org"
	},
	"creatorCustomer": {
		"name": "Acme, Inc.",
		"id": 3001,
		"path": ""
	},
	"createdDate": "2012-07-13T00:18:50.000+0000",
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/951/task/6693.json"
}, {
	"followers": [{
		"vendor": "",
		"customerUser": {
			"id": 3,
			"firstName": "John",
			"lastName": "Lennon",
			"path": "",
			"email" : "jlennon@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 51,
			"firstName": "George",
			"lastName": "Harrison",
			"path": "",
			"email" : "gharrison@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 237,
			"firstName": "Ringo",
			"lastName": "Star",
			"path": "",
			"email" : "rstar@example.org"
		},
		"path": ""
	}, {
		"vendor": "",
		"customerUser": {
			"id": 413,
			"firstName": "Mike",
			"lastName": "Lassetter",
			"path": "",
			"email" : "mlassetter@example.org"
		},
		"path": ""
	}, {
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
		"customerUser": "",
		"path": ""
	}],
	"assignee": {
		"customer": "",
		"projectFollowers": "",
		"vendor": {
			"name": "Decca International",
			"id": 3021,
			"path": "https://api.cloudwords.com/1/vendor/3021.json"
		},
		"customerUser": "",
		"path": ""
	},
	"creatorUser": {
		"id": 3,
		"firstName": "John",
		"lastName": "Lennon",
		"path": "",
		"email" : "jlennon@example.org"
	},
	"name": "Bad character encodings found",
	"id": 1747,
	"type": {
		"code": "revise_language",
		"display": "Revise Language"
	},
	"description": "Please fixup these translations",
	"status": {
		"code": "open",
		"display": "Open"
	},
	"dueDate": "2012-05-21T22:17:31.000+0000",
	"emailReminderDay": "",
	"startDate": "",
	"project": {
		"name": "My second translation project!",
		"id": 2545,
		"path": "https://api.cloudwords.com/1/project/2545.json"
	},
	"targetLanguage": {
		"display": "Chinese (Traditional)",
		"languageCode": "zh-tw"
	},
	"createdDate": "2012-05-21T22:17:31.000+0000",
	"creatorCustomer": {
		"name": "Acme, Inc",
		"id": 3001,
		"path": ""
	},
	"closedDate": "",
	"path": "https://api.cloudwords.com/1/project/2545/task/1747.json"
}]

Create Project Task

Create a new task for the specified project.

Note, only project tasks of type "custom" or "revise_language" may be created.

URL Structure
<base_uri>/<version>/project/<project_id>/task

Version(s)
1

Method(s)
POST

Returns
A metadata resource for the newly created task.

Required Fields
name, type, assignee

Not Settable Fields
id, createdDate, status

Sample JSON request:

{
	"name":"Review German translations on staging",
	"description":"some description",
	"type" : "custom",
	"assignee": {"customerUser":{"id":6}},
	"followers": [{"customerUser":{"id":9}},{"vendor":{"id":3000}}],
	"targetLanguage" : {"code":"de"},
	"startDate":"2012-07-18T22:15:59.000+0000",
	"dueDate":"2013-06-18T22:15:59.000+0000",
	"emailReminderDay":10
}

Note, the "emailReminderDay" field specifies how many days before the "dueDate" a reminder email should be sent to the specified assignee.

Update Project Task

Update a specified task for the specified project.

Note, only project tasks of type "custom" or "revise_language" may be updated.

URL Structure
<base_uri>/<version>/project/<project_id>/task/<task_id>

Version(s)
1

Method(s)
PUT

Returns
A metadata resource for the newly updated task.

Updateable Fields
name, status, description, assignee, followers, targetLanguage, startDate, dueDate, emailReminderDay

Sample JSON request:

{
	"name":"Review German translation on staging - REVISED",
	"status": "open",
	"description":"some description - WITH MORE DETAILS",
	"assignee": {"customerUser":{"id":6}},
	"followers": [{"customerUser":{"id":9}},{"vendor":{"id":3000}}],
	"targetLanguage" : {"code":"de"},
	"startDate":"2012-07-18T22:15:59.000+0000",
	"dueDate":"2013-06-18T22:17:59.000+0000",
	"emailReminderDay":11
}

Upload Task Attachment

Upload an attachment for the task.
Note: An attachment me only be uploaded once against a task.

URL Structure
<base_uri>/<version>/project/<project_id>/task/<task_id>/file/attachment/content

Version(s)
1

Method(s)
PUT

Returns
A new/updated metadata file resource for the task's attachment.

Request Body
A multipart upload which consists of a file to attach to the Task. The multipart parameter name for the file being uploaded is "file".

Sample JSON response:

{
	"filename": "qa_credentials.zip",
	"id": 1121,
	"contentPath": "https://api.cloudwords.com/1/project/951/task/1121/file/attachment/content,
	"sizeInKilobytes": 3243,
	"fileContents": "login_info.txt",
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/task/1121/file/attachment.json"
}

Get Task Attachment

Get the attachment for the specified task.

URL Structure
<base_uri>/<version>/project/<project_id>/task/<task_id>/file/attachment/content.json

Version(s)
1

Method(s)
GET

Returns
A metadata file resource for the task's attachment.

Sample JSON response:

{
	"filename": "qa_credentials.zip",
	"id": 1121,
	"contentPath": "https://api.cloudwords.com/1/project/951/task/1121/file/attachment/content,
	"sizeInKilobytes": 3243,
	"fileContents": "login_info.txt",
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/task/1121/file/attachment.json"
}

Intended Use Methods

Get Intended Uses

Get a list of all intended uses configured for the account.

URL Structure
<base_uri>/<version>/org/settings/project/intended-use.json

Version(s)
1

Method(s)
GET

Returns
All intended uses.

Sample JSON response:

[{
	"name": "Documentation",
	"id": 1
}, {
	"name": "Marketing",
	"id": 3
}, {
	"name": "Training",
	"id": 5
}, {
	"name": "UI",
	"id": 7
}, {
	"name": "Website",
	"id": 9
}]

Vendor Methods

Get Preferred Vendors

Get all preferred Vendors.

URL Structure
<base_uri>/<version>/vendor/preferred.json

Version(s)
1

Method(s)
GET

Returns
A list of all preferred vendors.

Fields

Field Name	Version(s)	Note
requiresBidding	1.19	Gets whether this preferred vendor is required to submit bid before translations can proceed. If false, bid submissions aren't mandatory by the vendor, customers can request translations without requiring the vendor to submit quotes. See Translation Requests for more information.

Sample JSON response:

[{
	"name": "Global R' Us",
	"id": 3021,
	"path": "https://api.cloudwords.com/1/vendor/3021.json",
	"requiresBidding" : true
}, {
	"name": "We Translate You",
	"id": 3025,
	"path": "https://api.cloudwords.com/1/vendor/3025.json",
	"requiresBidding" : false
}, {
	"name": "Turk Translations",
	"id": 3037,
	"path": "https://api.cloudwords.com/1/vendor/3037.json",
	"requiresBidding" : true
}]

Get a Vendor

Get a Vendor.

URL Structure
<base_uri>/<version>/vendor/.json

Version(s)
1

Method(s)
GET

Returns
A Vendor.

Sample JSON response:

{
	"name": "Turk Translations",
	"id": 3037,
	"path": "https://api.cloudwords.com/1/vendor/3037.json"
}

Source Language Methods

Get Source Languages

Get a list of all source languages configured for the account.

URL Structure
<base_uri>/<version>/org/settings/project/language/source.json

Version(s)
1

Method(s)
GET

Returns
All source languages.

Sample JSON response:

[{
	"display": "English (UK)",
	"languageCode": "en-gb"
}, {
	"display": "English (US)",
	"languageCode": "en-us"
}, {
	"display": "Spanish (Spain)",
	"languageCode": "es-es"
}]

Target Language Methods

Get Target Languages

Get a list of all target languages configured for the account.

URL Structure
<base_uri>/<version>/org/settings/project/language/target.json

Version(s)
1

Method(s)
GET

Returns
All target languages.

Sample JSON response:

[{
	"display": "Arabic (Kuwait)",
	"languageCode": "ar-kw"
}, {
	"display": "German",
	"languageCode": "de"
}, {
	"display": "Greek",
	"languageCode": "el"
}, {
	"display": "French",
	"languageCode": "fr"
}, {
	"display": "French (Canada)",
	"languageCode": "fr-ca"
},{
	"display": "Swedish",
	"languageCode": "sv"
}]

Department Methods

Get Departments

Get a list of all departments the context user is a member of.

Note: A department is a way of subdividing visibility and access to projects in Cloudwords.

URL Structure

<base_uri>/<version>/department.json

Version(s)
1

Method(s)
GET

Returns
All departments the context user is a member of.

Sample JSON response:

[{
	"name": "Training",
	"id": 1
}, {
	"name": "Legal",
	"id": 4
}, {
	"name": "Marketing",
	"id": 3
}]

Create Department

Create a new department

URL Structure

<base_uri>/<version>/department

Version(s)
1

Method(s)
POST

Returns
A metadata file resource for the newly created department

Sample JSON request:

{
	"name": "Legal"
}

Filter By Department

By default, any GET call will return data that belongs to any Cloudwords Department.

If you need to return data that only belongs to a specific Department, a special filtering capability exists to support this. This is achieved by injecting a top-level department filter into the REST URL as shown below.

URL Structure
<base_uri>/<version>/department/<department_id>/<any-normal-get-call-path>

Version(s)
1

Method(s)
GET

Returns
The appropriate resources that belong to the department specified in the URL.

User Methods

Get Current User

Gets the user resource for the user matching the API token in use.

URL Structure
<base_uri>/<version>/user/current.json

Version(s)
1

Method(s)
GET

Returns
The user matching the API token in use.

Sample JSON response:

{
   "firstName": "Magic",
   "lastName": "Johnson",
	"id": 32,
	"email" : "mjohnson@example.org"
}

Get Active Users

Lists all active users.

URL Structure
<base_uri>/<version>/user.json

Version(s)
1

Method(s)
GET

Returns
All active users.

Sample JSON response:

[{
	  "firstName": "Magic",
	  "lastName": "Johnson",
	  "id": 32,
	  "email" : "mjohnson@example.org"
}, {
	"firstName": "James",
	"lastName": "Worthy",
	"id": 42,
	"email" : "jworthy@example.org"
}]

Get Available Followers

Lists the users who are available to follow projects.

When a user is added as a follower of a project they will receive all relevant project notification emails and the project and its tasks will appear on their Cloudwords Home page when using the "Project's I Follow" facet.

URL Structure
<base_uri>/<version>/follower/available.json

Version(s)
1

Method(s)

GET

Note: If Departments are enabled and if no department filter is specified (see "Filter by Department" section), this call defaults to the special Unassigned department. If departments are not enabled, all followers in the org are listed.

Sample JSON response:

[{
	  "firstName": "Magic",
	  "lastName": "Johnson",
	  "id": 32,
	  "email" : "mjohnson@example.org"
}, {
	"firstName": "James",
	"lastName": "Worthy",
	"id": 42,
	"email" : "jworthy@example.org"
}]

Get Project Owners

Lists the users who can be associated as a project owner.

When a user is added as a owner of a project, the user receives all relevant project notification emails.

URL Structure
<base_uri>/<version>/project-owner.json

Version(s)
1.16

Method(s)

GET

Sample JSON response:

[{
	  "id": 7, 
	  "firstName": "Jesse", 
	  "lastName": "James", 
	  "email": "jesse.james@example.org"
}, {
	  "id": 9, 
	  "firstName": "James",
	  "lastName": "Worthy",
	  "email" : "jworthy@example.org"
}]

Change Order Methods

Change Order "Status" Values

A change order is a request to alter the project requirements, such as adding languages, files, or both, after the project has been assigned to a specific vendor and translation is underway. Since these changes affect a vendor's bid, they must be requested by you, quoted by the provider, and approved by you in a similar manner to what happens when you first requested bids for the project.

Status field

Change Orders can go through various stages or statuses as they are managed. Below is the set of all change order status values, and what they mean.
The field contains two attributes: 1) "code" which is a stable field you can program against and 2) "display" which is meant to be human readable.

Status Code	Status Description
creating	Once a change order is created it moves to 'creating' state. You can uplooad/overwrite source material for the change order as many times as you want during this state.
preparing_tm	This is a temporary state which occurs as soon as a customer requests/submits a change order to a vendor. A background job prepares TM for this change order while its in this state.
requested	This state implies that the change order has been requested/submitted by the customer to the vendor for bidding.
vendor_in_creation	The change order has been accepted by the vendor but is yet to submit the bids.
vendor_bid	The vendor has completed and submitted the bids for the change order.
vendor_rejected	The change order is rejected by the vendor and no further action is needed.
customer_accepted	The change order and associated bid submitted by the vendor is accepted by the customer and no further action is needed.
cancelled	The change order has been cancelled by the customer and no further action is needed.

Get Project Change Order(s)

Lists all change order(s) for the project specified.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder.json

Version(s)
1.12

Method(s)
GET

Returns
List of all change order(s) associated with the project specified.

Note: If a change order is with 'creating' status, it won't be returned by the API.

Sample JSON response:

[
    {
        "path": "http://api.cloudwords.com/1.12/project/2/changeOrder.json",
        "id": 109,
        "name": "sq",
        "project": {
            "path": "http://api.cloudwords.com/1.12/project/2.json",
            "id": 2,
            "name": "Test2"
        },
        "createdDate": "2014-04-18T20:02:33.000+0000",
        "languagesToAdd": [],
        "languagesToRemove": [],
        "status": {
            "display": "Vendor In Creation",
            "code": "vendor_in_creation"
        },
        "autoAccept": false
    },
    {
        "path": "http://api.cloudwords.com/1.12/project/2/changeOrder.json",
        "id": 106,
        "name": "CO106",
        "project": {
            "path": "http://api.cloudwords.com/1.12/project/2.json",
            "id": 2,
            "name": "Test2"
        },
        "createdDate": "2014-04-14T21:43:47.000+0000",
        "languagesToAdd": [
            {
                "display": "Japanese",
                "languageCode": "ja"
            }
        ],
        "languagesToRemove": [
            {
                "display": "French (Canada)",
                "languageCode": "fr-ca"
            },
            {
                "display": "French (France)",
                "languageCode": "fr-fr"
            }
        ],
        "status": {
            "display": "Customer Accepted",
            "code": "customer_accepted"
        },
        "autoAccept": false
    }
}]

Get Change Order

Gets the specified change order resource for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>.json

Version(s)
1.12

Method(s)
GET

Returns
The specified change order for the specified project.

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/106.json",
    "id": 106,
    "name": "CO106",
    "project": {
        "path": "http://api.cloudwords.com/1.12/project/2.json",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-14T21:43:47.000+0000",
    "languagesToAdd": [
        {
            "display": "Japanese",
            "languageCode": "ja"
        }
    ],
    "languagesToRemove": [
        {
            "display": "French (Canada)",
            "languageCode": "fr-ca"
        },
        {
            "display": "French (France)",
            "languageCode": "fr-fr"
        }
    ],
    "status": {
        "display": "Customer Accepted",
        "code": "customer_accepted"
    },
    "autoAccept": false
}

Create Change Order

Creates a change order in context of the specified project.

Note: If there exists an open change order or the current project status is not 'in_translation' state, a new change order can't be created.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder

Version(s)
1.12

Method(s)

POST

Returns
A metadata resource for the newly created change order.

Required Field(s)
name

Not Settable Field(s)
id, createdDate, project, status

Field Restrictions

Field Name	Version(s)	Note
name	1.12	Must be 50 characters or less in length.
description	1.12	Must be 250 characters or less in length.
languagesToAdd	1.12	List of languages to be added in this change order. The value must match the "languageCode" attribute that can be found in the Source Language resource.
languagesToRemove	1.12	List of languages to be removed in this change order. This list cannot contain any of the languages added added to the change order (see above). The values must match the "languageCode" attribute that can be found in the Target Language resource.
autoAccept	1.12	Must be a boolean value. Default value is 'false'. Specifies whether the change order bid submitted by the vendor must be auto-accepted or not.

Sample JSON request:

{
        "name": "CO55",
    	"autoAccept": false,
    	"description": "Change Order",
        "languagesToAdd": [

        ],
        "languagesToRemove": [
            {
                "display": "Chinese (Traditional)",
                "languageCode": "zh-tw"
            },
            {
                "display": "Chinese (Traditional)",
                "languageCode": "zh-cn"
            }
        ]
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/122.json",
    "id": 122,
    "name": "CO55",
    "project": {
        "path": "http://api.cloudwords.com/1.12/project/2.json",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-19T01:40:12.000+0000",
    "description": "Change Order",
    "languagesToAdd": [],
    "languagesToRemove": [
        {
            "display": "Chinese (Traditional)",
            "languageCode": "zh-tw"
        },
        {
            "display": "Chinese (Simplified)",
            "languageCode": "zh-cn"
        }
    ],
    "status": {
        "display": "Creating",
        "code": "creating"
    },
    "autoAccept": false
}

Change Order Project Workflows

Get the list of initialized project workflows for the change order. Workflows will only be initialized if new languages are being added via the change order.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<change_order_id>/workflow.json

Version(s)
1.12

Method(s)
GET

Returns
The list of initialized workflows, one per added target language.

Sample JSON response:

[
  {
    "language": {
      "display": "French",
      "languageCode": "fr"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/changeOrder/27/workflow/fr.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "language": {
      "display": "Dutch",
      "languageCode": "nl"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/changeOrder/27/workflow/nl.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customer": {
                "id": 3006,
                "name": "Crestas",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  },
  {
    "language": {
      "display": "German",
      "languageCode": "de"
    },
    "path": "http://api.cloudwords.com/1.12/project/288/changeOrder/27/workflow/de.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2014-05-14T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 1,
            "phaseType": {
              "code": "work",
              "display": "Work"
            }
          },
          {
            "allowRevision": true,
            "assignee": {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            "assigneeType": {
              "code": "customer_user",
              "display": "Internal"
            },
            "dueDate": "2014-05-16T00:00:00.000+0000",
            "path": "",
            "phaseNumber": 2,
            "phaseType": {
              "code": "review",
              "display": "Review"
            }
          }
        ],
        "stepNumber": 1
      }
    ],
    "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
    "templateName": "Basic 1-Step Workflow",
    "templateType": {
      "code": "builtin_single_step",
      "display": "Built-in Single Step"
    }
  }
]

Change Order Project Workflow by Language

Get an initialized change order project workflow by target language.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<change_order_id>/workflow/<language>.json

Version(s)
1.12

Method(s)
GET

Returns
The workflow by language

Sample JSON response:

{
  "language": {
    "display": "German",
    "languageCode": "de"
  },
  "path": "http://api.cloudwords.com/1.12/project/288/changeOrder/27/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2014-05-14T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 1,
          "phaseType": {
            "code": "work",
            "display": "Work"
          }
        },
        {
          "allowRevision": true,
          "assignee": {
            "customerUser": {
              "email": "pm@crestas.com",
              "firstName": "Project ",
              "id": 33,
              "lastName": "Manager",
              "path": ""
            },
            "path": ""
          },
          "assigneeType": {
            "code": "customer_user",
            "display": "Internal"
          },
          "dueDate": "2014-05-16T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 2,
          "phaseType": {
            "code": "review",
            "display": "Review"
          },
          "possibleAssignees": [
            {
              "customerUser": {
                "email": "admin@notcrestas.com",
                "firstName": "NewUser",
                "id": 20,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "user@crestas.com",
                "firstName": "User",
                "id": 26,
                "lastName": "Request",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "translator@crestas.com",
                "firstName": "Translator",
                "id": 40,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            }
          ]
        }
      ],
      "stepNumber": 1
    }
  ],
  "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
  "templateName": "Basic 1-Step Workflow",
  "templateType": {
    "code": "builtin_single_step",
    "display": "Built-in Single Step"
  }
}

Update Change Order Project Workflow

Update the assignee and due dates of individual phases. The due date of the first phase of the first step cannot be modified (it is always the project delivery due date) and the assignee cannot be updated for phases with an assigneeType of "VENDOR". Change Order project workflows can only be updated before the change order is submitted. If the Change Order bid is accepted by the customer, then the updated workflows will be added to the project.

URL Structure
<base_uri>/<version>/project/<project_id>/workflow/<language>.json

Version(s)
1.12

Method(s)
PUT

Returns
The updated workflow

Sample JSON request:

{
  "steps": [
    {
      "phases": [
        {
          "phaseNumber": 2,
          "assigneeUser" : {"customerUser" : {"id" : 33}},
          "dueDate" : "2014-05-16T00:00:00.000+0000"
        }
      ],
      "stepNumber": 1
    }
  ]
}

Sample JSON response:

{
  "language": {
    "display": "German",
    "languageCode": "de"
  },
  "path": "http://api.cloudwords.com/1.12/project/288/changeOrder/27/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2014-05-14T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 1,
          "phaseType": {
            "code": "work",
            "display": "Work"
          }
        },
        {
          "allowRevision": true,
          "assignee": {
            "customerUser": {
              "email": "pm@crestas.com",
              "firstName": "Project ",
              "id": 33,
              "lastName": "Manager",
              "path": ""
            },
            "path": ""
          },
          "assigneeType": {
            "code": "customer_user",
            "display": "Internal"
          },
          "dueDate": "2014-05-16T00:00:00.000+0000",
          "path": "",
          "phaseNumber": 2,
          "phaseType": {
            "code": "review",
            "display": "Review"
          },
          "possibleAssignees": [
            {
              "customerUser": {
                "email": "admin@notcrestas.com",
                "firstName": "NewUser",
                "id": 20,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "reviewer@crestas.com",
                "firstName": "Reviewer",
                "id": 21,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "user@crestas.com",
                "firstName": "User",
                "id": 26,
                "lastName": "Request",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "pm@crestas.com",
                "firstName": "Project ",
                "id": 33,
                "lastName": "Manager",
                "path": ""
              },
              "path": ""
            },
            {
              "customerUser": {
                "email": "translator@crestas.com",
                "firstName": "Translator",
                "id": 40,
                "lastName": "Crestas",
                "path": ""
              },
              "path": ""
            }
          ]
        }
      ],
      "stepNumber": 1
    }
  ],
  "templateDescription": "Whenever the Vendor delivers the translation for a language, a review task is automatically created and assigned to the project owner or a reviewer for that language. You can then approve the translation or send back to the vendor for corrections.",
  "templateName": "Basic 1-Step Workflow",
  "templateType": {
    "code": "builtin_single_step",
    "display": "Built-in Single Step"
  }
}

Submit Change Order

Submits a change order request to the vendor.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>.json

Version(s)
1.12

Method(s)
PUT

Returns
The specified change order with updated status.

Note: As soon as you submit a change order to a vendor, it moves to temporary 'preparing_tm' state. Once the TM is prepared with the change order changes, state changes to 'requested'.

Sample JSON request:

{
    "status": {
        "code": "requested"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/123.json",
    "id": 123,
    "name": "CO55",
    "project": {
        "path": "http://api.cloudwords.com/1.12/project/2.json",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-19T02:14:18.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [
        {
            "display": "Chinese (Simplified)",
            "languageCode": "zh-cn"
        },
        {
            "display": "Chinese (Traditional)",
            "languageCode": "zh-tw"
        }
    ],
    "status": {
        "display": "Preparing TM",
        "code": "preparing_tm"
    },
    "autoAccept": false
}

Accept Change Order

Accepts a change order request submitted by the vendor after bidding.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>.json

Version(s)
1.12

Method(s)
PUT

Returns
The specified change order with updated status.

Only change orders in 'vendor_bid' state can be accepted.

Sample JSON request:

{
    "status": {
        "code": "customer_accepted"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/127.json",
    "id": 127,
    "name": "CO55",
    "project": {
        "path": "http://api.cloudwords.com/1.12/project/2.json",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-22T19:06:33.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [],
    "status": {
        "display": "Customer Accepted",
        "code": "customer_accepted"
    },
    "autoAccept": false
}

Cancel Change Order

Cancels an existing open change order.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>.json

Version(s)
1.12

Method(s)
PUT

Returns
The specified change order with cancelled status.

Note: Only change orders in open state (editable) can be cancelled.

Sample JSON request:

{
    "status": {
        "code": "cancelled"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/123.json",
    "id": 123,
    "name": "CO55",
    "project": {
        "path": "http://api.cloudwords.com/1.12/project/2.json",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-19T02:14:18.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [
        {
            "display": "Chinese (Simplified)",
            "languageCode": "zh-cn"
        },
        {
            "display": "Chinese (Traditional)",
            "languageCode": "zh-tw"
        }
    ],
    "status": {
        "display": "Canceled",
        "code": "cancelled"
    },
    "autoAccept": false
}

Get Change Order Source Material

Get the attachment metadata for the specified change order if it exists.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>/file/attachment.json

Version(s)
1.12

Method(s)
GET

Returns
A metadata file resource for the change order's attachment.

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/92/file/attachment.json",
    "id": 38,
    "filename": "Download_Excel_Macro_Sample.xls",
    "contentPath": "http://api.cloudwords.com/1.12/project/2/changeOrder/92/file/attachment/content",
    "sizeInKilobytes": 344,
    "fileContents": "",
    "createdDate": "2014-04-10T17:29:43.000+0000"
}

Download Change Order Source Material

Get the change order's source material's binary data for the specified project.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>/file/attachment/content

Version(s)
1.12

Method(s)

GET

Returns
A stream containing a binary file (zip) that contains the change order's source material.

Upload Change Order Source Material

Upload or update/overwrite the source material for the specified change order.

Note: Source materials may only be uploaded/updated before a change order has been submitted for bids.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>/file/attachment

Version(s)
1.12

Method(s)

PUT

Request Body
A multipart upload which consists of a zip file that contains the change order's source material. The multipart parameter name for the file being uploaded is "file".

Returns
A new/updated metadata file resource for the change order's source material.

Note: Source materials can be uploaded only when change order is in 'creating' status.

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/125/file/attachment.json",
    "id": 40,
    "filename": "CEACAA003L1IFS.PDF",
    "contentPath": "http://api.cloudwords.com/1.12/project/2/changeOrder/125/file/attachment/content",
    "sizeInKilobytes": 113,
    "fileContents": "",
    "createdDate": "2014-04-22T17:27:05.000+0000"
}

Get Change Order Bid

Get the vendor bid for the specified change order.

URL Structure
<base_uri>/<version>/project/<project_id>/changeOrder/<changeOrder_id>/bid.json

Version(s)
1.12

Method(s)

GET

Returns
The specified vendor change order bid resource if it exists.

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/104/bid.json",
    "id": 40,
    "description": "",
    "amount": 449.82,
    "bidItems": [
        {
            "path": "",
            "id": 139,
            "bidItemTasks": [
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "project_management",
                        "parentType": "",
                        "display": "Project Management"
                    },
                    "cost": 0,
                    "id": 1217
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation",
                        "parentType": "",
                        "display": "Translation"
                    },
                    "cost": 441,
                    "id": 1222
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_new_words",
                        "parentType": "translation",
                        "display": "New Words"
                    },
                    "cost": 0,
                    "id": 1221,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_repeated_words",
                        "parentType": "translation",
                        "display": "Repeated Words"
                    },
                    "cost": 0,
                    "id": 1216,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "desktop_publishing",
                        "parentType": "",
                        "display": "Desktop Publishing"
                    },
                    "cost": 0,
                    "id": 1220
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_translated_words",
                        "parentType": "translation",
                        "display": "Translated Words"
                    },
                    "cost": 441,
                    "id": 1218,
                    "attributes": {
                        "numWords": 21
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "review",
                        "parentType": "",
                        "display": "Review"
                    },
                    "cost": 0,
                    "id": 1214
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_fuzzy_match_words",
                        "parentType": "translation",
                        "display": "Fuzzy Match Words"
                    },
                    "cost": 0,
                    "id": 1215,
                    "attributes": {
                        "numWords": 0
                    }
                }
            ],
            "language": {
                "display": "Bulgarian",
                "languageCode": "bg"
            },
            "isLanguageRemoved": false
        }
    ],
	"status": {
        "display": "Vendor Submitted",
        "code": "submitted"
}

Webhook Methods

Webhook Events

A webhook can be registered to be notified of certain events that occur within Cloudwords. This eliminates the tedious process of polling to know when something has occurred. When an event occurs within Cloudwords that is webhook enabled, and a webhook has been registered for that event, a message will be posted to the registered URI, and additional information pertaining to the specific event will be included in the body of the post in JSON format.

Event type

The event type of the webhook is the key to knowing when the webhook post will be sent.

Deliverable Added

Event Type
deliverable_added

Version(s)
1.15+

Event Trigger
A translated asset is uploaded, including the initial translation and any revision.

Required Fields for Creation
eventType, uri, entityType, entityId

POST Body

{
    "event_type":"deliverable_added",
    "project_id":<project_id>,
    "target_language":"<language_code>",
    "document_ids":[<comma separated list of document ids>]
}

Project Cancelled

Event Type
project_cancelled

Version(s)
1.17+

Event Trigger
A project is cancelled.

Required Fields for Creation
eventType, uri, entityType, entityId

POST Body

{
    "event_type":"project_cancelled",
    "project_id":<project_id>"
}

Project Status Updated

Event Type
project_status_updated

Version(s)
1.19+

Event Trigger
The project status has changed.

Required Fields for Creation
eventType, uri, entityType, entityId

POST Body

{
    "event_type":"project_status_updated",
    "project_id":<project_id>,
    "project_status": { "code":"<project_status_code>", "display":"<project_status_display>" }
}

Get List of Webhooks

Lists all existing webhook(s).

URL Structure
<base_uri>/<version>/webhook.json

Version(s)
1.15

Method(s)
GET

Returns
List of all webhook(s) that have been created.

Sample JSON response:

[
    {
        "path": "https://api.cloudwords.com/1.15/webhook/1.json",
        "id": 1,
        "uri": "https://example.com/notification",
        "status": "active",
        "lastModifiedDate": "2014-12-18T20:02:33.000+0000",
        "entityId": 109,
        "entityType": "project",
        "contextId": "",
        "contextType": "",
        "eventType": "deliverable_added"
    },
    {
       "path": "https://api.cloudwords.com/1.15/webhook/2.json",
        "id": 2,
        "uri": "https://example.com/notification",
        "status": "active",
        "lastModifiedDate": "2014-12-18T20:12:33.000+0000",
        "entityId": 110,
        "entityType": "project",
        "contextId": "fr",
        "contextType": "language",
        "eventType": "deliverable_added"
    }
}]

Get Webhook

Gets the specified webhook resource.

URL Structure
<base_uri>/<version>/webhook/<webhook_id>.json

Version(s)
1.15

Method(s)
GET

Returns
The specified webhook.

Sample JSON response:

{
    "path": "https://api.cloudwords.com/1.15/webhook/1.json",
    "id": 1,
    "uri": "https://example.com/notification",
    "status": "active",
    "lastModifiedDate": "2014-12-18T20:02:33.000+0000",
    "entityId": 109,
    "entityType": "project",
    "contextId": "",
    "contextType": "",
    "eventType": "deliverable_added"
}

Create Webhook

Creates a webhook for the specified event type.

Note: If there exists a webhook with the same parameters (eventType, entityType, entityId, contextType, contextId, uri), then the existing webhook will be returned instead of creating a duplicate. Some eventTypes have additional required fields.

URL Structure
<base_uri>/<version>/webhook

Version(s)
1.15

Method(s)
POST

Returns
A metadata resource for the newly created webhook.

Required Field(s)
eventType, uri

Not Settable Field(s)
id, lastModifiedDate, status

Field Restrictions

Field Name	Version(s)	Note
uri	1.15	Must be 1000 characters or less in length. Must use HTTPS protocol. Cannot contain cloudwords.com domain.
eventType	1.15	Must be an eventType that is webhook-enabled within Cloudwords. See Webhook Events
entityType	1.15	The entity type of the associated entityId. Possible values: "project"
entityId	1.15	The integer id of the entity of type entityType. If entityId is specified, entityType is required.
contextType	1.15	The context type of the associated contextId. Possible values: "language"
contextId	1.15	The string name of context of the associated contextType. Possible values: Cloudwords language codes

Sample JSON request:

{
    "uri": "https://example.com/notification",
    "entityId": 109,
    "entityType": "project",
    "contextId": "fr",
    "contextType": "language",
    "eventType": "deliverable_added"
}

Sample JSON response:

{
    "path": "https://api.cloudwords.com/1.15/webhook/2.json",
    "id": 2,
    "uri": "https://example.com/notification",
    "status": "active",
    "lastModifiedDate": "2014-12-18T20:02:33.000+0000",
    "entityId": 109,
    "entityType": "project",
    "contextId": "fr",
    "contextType": "language",
    "eventType": "deliverable_added"
}

Delete Webhook

Deletes a specified webhook.

URL Structure
<base_uri>/<version>webhook/<webhook_id>.json

Version(s)
1.15

Method(s)
DELETE

Returns
HTTP status code only (200 for success)

Webhook Signatures

All webhook messages are signed with a hash-based message authentication code that can be used to verify that the message was sent by Cloudwords. The signature exists as a message header under the field name "Cloudwords-Signature".

Sample header:

Cloudwords-Signature: ce0d7696b802508ebbfcda9d508bde73b59bcee4eafb604433669fe433b9d6ac

To verify the signature, create the hash-based message authentication (HMAC) using the SHA256 algorithm, using your API token as the secret key, and the POST body as the message. The API token used to generate the signature is for the user account used to register the webhook. If the HMAC matches the signature, then the message is considered to be authentic.

Translation Requests

Translation Request

Translation Request are sent to the vendor(s) to request translations of the source assets. The customer may either send request to preferred vendor(s) and request bids for the same or may send a request directly to a preferred vendor without involving the bidding phase (without the preferred vendor needing to specify quotes and submit bid).

Create Translation Request

Creates a Translation Request

URL Structure
<base_uri>/<version>/project/<project_id>/translation-request

Version(s)
1.19

Method(s)
POST

Returns
A metadata resource for the newly created translation request.

Field Restrictions

Method 1 : Create Translation Request by requesting bids from vendor(s)

Required Field(s)
requiresBidding, options

Method 2 : Create Translation Request by requesting to a preferred vendor (without involving bidding phase)

Required Field(s)
requiresBidding, preferredVendors

Method 3 : Create Translation Request by requesting machine translation

Required Field(s)
requiresBidding, performMachineTranslation

Field Name	Version(s)	Note
performMachineTranslation	1.20	Setting this flag to true shall request machine translation if a machine translation provider has been configured.
requiresBidding	1.19	Setting this flag to true shall request translations from vendor(s) and expect them to sumbit bids before proceeding with the translation process. When set to false, the translation request shall be sent to a single selected preferred vendor without involving the bidding phase.
preferredVendors	1.19	A translation request can be sent only to preferred vendors configured to receive such requests for that department. See preferred vendors for more information.
options	1.19	A BidOptions object is to be set only when vendors are expected to submit bids for the translation request. (i.e requiresBidding flag is set to true). See Bid Options for more information.

Method 1 : Create Translation Request by requesting bids

Sample JSON request:

{
	"requiresBidding":true,
	"preferredVendors":[
		{"id":4907},
		{"id":4908},
		{"id":4909}
		],
	"options": {
		"doLetCloudwordsChoose":true,
		"doAutoSelectBidFromVendor":false,
		"winningBidId":null
		}
}

Method 2 : Create Translation Request by requesting to a preferred vendor

Sample JSON request:

{
	"requiresBidding":false,
	"preferredVendors":[
		{"id":4875}
	]
}

Method 3 : Create Translation Request by requesting machine translation, auto-selecting the quote.

Sample JSON request:

{
	"requiresBidding":false,
	"performMachineTranslation":true,
	"options": {
		"doAutoSelectBidFromVendor":true
		}
}

Bid Options

Bid Options should always be sent along with translation request, whenever requiresBidding is set to true.

Field Name	Version(s)	Note
doLetCloudwordsChoose	1.19	When set to true, Cloudwords shall automatically choose vendor(s) in marketplace to whom translation requests will be sent.
doAutoSelectBidFromVendor	1.19	When set to true, Cloudwords shall automatically accept the bid submitted by the vendor. This flag can be set to true only when translation request is sent to only one vendor.
winningBidId	1.19	Use this field to select the winning bid amongst all the bid(s) submitted by vendor(s). See Bid Methods for more information.

Get Translation Request

Get the most recently created translation request resource.

URL Structure
<base_uri>/<version>/project/<project_id>/translation-request/current.json

Version(s)
1.19

Method(s)
GET

Returns
The most recently created translation request resource.

Sample JSON response:

{
	"requiresBidding":true,
	"createdDate":null,
  	"description":"",
	"preferredVendors":[
		{
		 "id":4907,
		 "name"="Test Vendor Company",
		 "requiresBidding"=false
		},
		{
		 "id":4908
		..
		},
		{
		 "id":4909
		 ..
		}
	],
	"options": {
		"doLetCloudwordsChoose":true,
		"doAutoSelectBidFromVendor":false,
		"winningBidId":null
	}
}

Select Winning Translation Request

Based on all the bids submitted by the vendor(s), select the winning translation request.

URL Structure
<base_uri>/<version>/project/<project_id>/translation-request

Version(s)
1.19

Method(s)
PUT

Returns
The translation request with winning bid selected.

Sample JSON request:

{
	"requiresBidding":true,
	"options": {
		"winningBidId":2343
		}
}

Translation Units Review

Gets the Translation Units Review resource, which allows you to access detailed review information such as comments and translation feedback which includes severity and category.

URL Structure
<base_uri>/<version>/project/<project_id>/translated/language/<language_code>/document/<document_id>/review.json

Version(s)
1.24

Method(s)
GET

Returns
The specified review resource.

Sample JSON response:

[  
   {  
      "srcLang":"",
      "srcText":"Welcome to Cloudwords Sitecore Integration",
      "trgLang":"",
      "createdDate":"2018-07-27T21:10:46.776+0000",
      "translations":[  
         {  
            "text":"Bienvenue à l’intégration de Cloudwords Sitecore",
            "createdDate":"2018-07-27T21:10:46.776+0000",
            "comments":[  
               {  
                  "text":"Here is some feedback.",
                  "createdDate":"2018-07-30T23:23:07.941+0000",
                  "userId":7829,
                  "feedback":{  
                     "severity":"Neutral Error",
                     "categoryType":"Style",
                     "category":"Unidiomatic"
                  }
               }
            ]
         }
      ]
   },
   {  
      "srcLang":"",
      "srcText":"Welcome to Sitecore.",
      "trgLang":"",
      "createdDate":"2018-07-27T21:10:46.853+0000",
      "translations":[  
         {  
            "text":"Bienvenue chez Sitecore.",
            "createdDate":"2018-07-27T21:10:46.853+0000",
            "comments":[  
               {  
                  "text":"This is another feedback on the French translation.",
                  "createdDate":"2018-07-30T23:25:03.860+0000",
                  "userId":7829,
                  "feedback":{  

                  }
               }
            ]
         }
      ]
   }
]