Cloudwords Vendor 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

NameRequiredDefaultValue
offsetfalse0Start results at offset (starts at 0)
limitfalse20Limit result count to limit (max 200)
projectContentTypefalsenone Only include projects with a content type of projectContentType, case sensitive. Pass parameter multiple times for OR query.
statusfalsenone 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".
sortByfalseid Sort the result by a project property. Possible values: id, name, createdDate, bidDueDate, bidSelectDeadlineDate, deliveryDueDate, currency, sourceLanguage
sortOrderfalseascSort 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":[  
      {  
         "customer":{  
            "name":"The Jimmy Hendrix Experience",
            "id":3045,
            "path":""
         },
         "description":"blah eñe",
         "status":{  
            "code":"in_review",
            "display":"In Review"
         },
         "sourceLanguage":{  
            "display":"Bulgarian",
            "languageCode":"bg"
         },
         "targetLanguages":[  
            {  
               "display":"Turkish",
               "languageCode":"tr"
            }
         ],
         "deliveryDueDate":"2011-03-07T01:00:00.000+0000",
         "bidDueDate":"2011-02-27T19:00:00.000+0000",
         "intendedUse":{  
            "name":"UI",
            "id":117
         },
         "followers":[  

         ],
         "notes":"fghj",
         "createdDate":"2011-02-25T00:26:19.000+0000",
         "bidSelectDeadlineDate":"2011-03-01T19:00:00.000+0000",
         "amount":379.00,
         "name":"test revision request",
         "id":807,
         "path":"https://api.cloudwords.com/1/project/807.json"
      },
      {  
         "customer":{  
            "name":"Wynn",
            "id":3091,
            "path":""
         },
         "description":"",
         "status":{  
            "code":"in_review",
            "display":"In Review"
         },
         "sourceLanguage":{  
            "display":"Danish",
            "languageCode":"da"
         },
         "targetLanguages":[  
            {  
               "display":"Estonian",
               "languageCode":"et"
            },
            {  
               "display":"French",
               "languageCode":"fr"
            },
            {  
               "display":"Hungarian",
               "languageCode":"hu"
            },
            {  
               "display":"Latvian",
               "languageCode":"lv"
            }
         ],
         "deliveryDueDate":"2011-09-08T00:00:00.000+0000",
         "bidDueDate":"2011-09-04T00:00:00.000+0000",
         "intendedUse":{  
            "name":"Training",
            "id":285
         },
         "followers":[  

         ],
         "notes":"",
         "createdDate":"2011-08-29T18:58:44.000+0000",
         "bidSelectDeadlineDate":"2011-09-06T00:00:00.000+0000",
         "amount":13600.00,
         "name":"Upload Revision Request Deliverables Bug",
         "projectContentType":"STANDARD",
         "id":1321,
         "path":"https://api.cloudwords.com/1/project/1321.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:

[{
    "customer": {
        "name": "The Jimmy Hendrix Experience",
        "id": 3045,
        "path": ""
    },
    "description": "blah eñe",
    "status": {
        "code": "in_review",
        "display": "In Review"
    },
    "sourceLanguage": {
        "display": "Bulgarian",
        "languageCode": "bg"
    },
    "targetLanguages": [{
        "display": "Turkish",
        "languageCode": "tr"
    }],
    "deliveryDueDate": "2011-03-07T01:00:00.000+0000",
    "bidDueDate": "2011-02-27T19:00:00.000+0000",
    "intendedUse": {
        "name": "UI",
        "id": 117
    },
    "followers": [],
    "notes": "fghj",
    "createdDate": "2011-02-25T00:26:19.000+0000",
    "bidSelectDeadlineDate": "2011-03-01T19:00:00.000+0000",
    "amount": 379.00,
    "name": "test revision request",
    "id": 807,
    "path": "https://api.cloudwords.com/1/project/807.json"
}, {
    "customer": {
        "name": "Wynn",
        "id": 3091,
        "path": ""
    },
    "description": "",
    "status": {
        "code": "in_review",
        "display": "In Review"
    },
    "sourceLanguage": {
        "display": "Danish",
        "languageCode": "da"
    },
    "targetLanguages": [{
        "display": "Estonian",
        "languageCode": "et"
    }, {
        "display": "French",
        "languageCode": "fr"
    }, {
        "display": "Hungarian",
        "languageCode": "hu"
    }, {
        "display": "Latvian",
        "languageCode": "lv"
    }],
    "deliveryDueDate": "2011-09-08T00:00:00.000+0000",
    "bidDueDate": "2011-09-04T00:00:00.000+0000",
    "intendedUse": {
        "name": "Training",
        "id": 285
    },
    "followers": [],
    "notes": "",
    "createdDate": "2011-08-29T18:58:44.000+0000",
    "bidSelectDeadlineDate": "2011-09-06T00:00:00.000+0000",
    "amount": 13600.00,
    "name": "Upload Revision Request Deliverables Bug",
    "projectContentType" : "STANDARD",
    "id": 1321,
    "path": "https://api.cloudwords.com/1/project/1321.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:

[{
    "customer": {
        "name": "The Beatles",
        "id": 3001,
        "path": ""
    },
    "description": "this is going to be revolutionary",
    "status": {
        "code": "project_closed",
        "display": "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-21T13:00:00.000+0000",
    "intendedUse": {
        "name": "Marketing",
        "id": 3
    },
    "followers": [],
    "notes": "Notes and instructions for the providers ",
    "createdDate": "2011-01-19T17:37:08.000+0000",
    "bidSelectDeadlineDate": "2011-01-23T13:00:00.000+0000",
    "amount": 551894.00,
    "name": "white album",
    "projectContentType" : "STANDARD",
    "id": 129,
    "path": "https://api.cloudwords.com/1/project/129.json"
}, {
    "customer": {
        "name": "The Beatles",
        "id": 3001,
        "path": ""
    },
    "description": "this is going to be our biggest project so far - maybe ever",
    "status": {
        "code": "cancelled",
        "display": "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-26T13:00:00.000+0000",
    "intendedUse": {
        "name": "Documentation",
        "id": 1
    },
    "followers": [],
    "notes": "note that this is a note",
    "createdDate": "2011-01-24T17:08:38.000+0000",
    "bidSelectDeadlineDate": "2011-01-28T13:00:00.000+0000",
    "amount": 39222.00,
    "name": "let it be",
    "projectContentType" : "Drupal",
    "id": 237,
    "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:

{
    "customer": {
        "name": "The Jimmy Hendrix Experience",
        "id": 3045,
        "path": ""
    },
    "description": "blah ene",
    "status": {
        "code": "in_review",
        "display": "In Review"
    },
    "sourceLanguage": {
        "display": "Bulgarian",
        "languageCode": "bg"
    },
    "targetLanguages": [{
        "display": "Turkish",
        "languageCode": "tr"
    }],
    "deliveryDueDate": "2011-03-07T01:00:00.000+0000",
    "bidDueDate": "2011-02-27T19:00:00.000+0000",
    "intendedUse": {
        "name": "UI",
        "id": 117
    },
    "followers": [],
    "notes": "fghj",
    "createdDate": "2011-02-25T00:26:19.000+0000",
    "bidSelectDeadlineDate": "2011-03-01T19:00:00.000+0000",
    "amount": 379.00,
    "name": "test revision request",
    "projectContentType" : "STANDARD",
    "id": 807,
    "path": "https://api.cloudwords.com/1/project/807.json"
}

Project Workflows

Get the list of project workflows for the given project.

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": "Czech",
      "languageCode": "cs"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/workflow/cs.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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": "Bulgarian",
      "languageCode": "bg"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/workflow/bg.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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/257/workflow/de.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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": "Arabic",
      "languageCode": "ar"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/workflow/ar.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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 Workflow by Language

Get the 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/257/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2013-12-27T01: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
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.
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.

Close Project

After uploading the translation memory for a project, you must close it before the project is forwarded to our billing department. To do this, update the project status to project_closed.

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

Version(s)
1

Method(s)
PUT

Returns
The updated project (as with Get Project).

Sample JSON request:

{
    status: "project_closed"
}

Project Source Material Methods

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.

Get Customer Company TM Metadata

Get the metadata for the project-specific Customer Company TM.

URL Structure
<base_uri>/<version>/project/<project_id>/file/customer-tm.json

Version(s)
1

Method(s)
GET

Returns
Metadata for the project-specific Customer Company Translation Memory file.

Sample JSON response:

{
	"filename": "project-tm.zip",
	"id": 2855,
	"contentPath": "https://api.cloudwords.com/1/project/1025/file/customer-tm/content",
	"sizeInKilobytes": 1,
	"fileContents": "project-en-US-fr-fr.tmx",
	"createdDate": "2011-07-11T18:45:12.000+0000",
	"path": "https://api.cloudwords.com/1/project/1025/file/customer-tm.json"
}

Get Customer Department TM Metadata

Get the metadata for the project-specific Customer Department TM.

URL Structure
<base_uri>/<version>/project/<project_id>/file/customer-department-tm.json

Version(s)
1.22

Method(s)
GET

Returns
Metadata for the project-specific Customer Department Translation Memory file.

Sample JSON response:

{
	"filename": "project-tm.zip",
	"id": 2855,
	"contentPath": "https://api.cloudwords.com/1/project/1025/file/customer-department-tm/content",
	"sizeInKilobytes": 1,
	"fileContents": "project-en-US-fr-fr.tmx",
	"createdDate": "2011-07-11T18:45:12.000+0000",
	"path": "https://api.cloudwords.com/1/project/1025/file/customer-department-tm.json"
}

Download Customer Company TM

Get a snapshot of the relevant customer Company TM for this project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/customer-tm/content

Version(s)
1

Method(s)
GET

Returns
A stream containing a binary file (zip) of the Company Translation Memory.

Download Customer Department TM

Get a snapshot of the relevant customer Department TM for this project.

URL Structure
<base_uri>/<version>/project/<project_id>/file/customer-department-tm/content

Version(s)
1.22

Method(s)
GET

Returns
A stream containing a binary file (zip) of the Department Translation Memory.

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.zip",
	"id": 2396,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2396/content",
	"sizeInKilobytes": 12,
	"fileContents": "what_we_are_about.doc, cool_facts.xls",
	"createdDate": "2011-05-18T00:54:34.000+0000",
	"path": "https://api.cloudwords.com/1/project/951/file/reference/2396.json"
},
{
	"filename": "fun_facts.zip",
	"id": 2397,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2397/content",
	"sizeInKilobytes": 12,
	"fileContents": "what_we_do_in_10_pages_or_less.txt",
	"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.zip",
	"id": 2396,
	"contentPath": "https://api.cloudwords.com/1/project/951/file/reference/2396/content",
	"sizeInKilobytes": 12,
	"fileContents": "what_we_are_about.doc, cool_facts.xls",
	"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 a binary file (zip) that contains the project's source material.

Bid Methods

Get Bid

Get the bid for the specified project.

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

Method(s)
GET

Returns
The specified bid resource.

Sample JSON response:

{
    "bidItems": [{
        "language": {
            "display": "Turkish",
            "languageCode": "tr"
        },
        "id": 3209,
        "bidItemTasks": [{
            "id": 11391,
            "projectTaskType": {
                "type": "project_management",
                "display": "Project Management",
                "parentType": ""
            },
            "cost": 34.00,
            "path": ""
        }, {
            "id": 7275,
            "projectTaskType": {
                "type": "desktop_publishing",
                "display": "Desktop Publishing",
                "parentType": ""
            },
            "cost": 0.00,
            "path": ""
        }, {
            "id": 15507,
            "projectTaskType": {
                "type": "review",
                "display": "Review",
                "parentType": ""
            },
            "cost": 0.00,
            "path": ""
        }, {
            "id": 3159,
            "projectTaskType": {
                "type": "translation",
                "display": "Translation",
                "parentType": ""
            },
            "cost": 345.00,
            "path": ""
        }],
        "isLanguageRemoved": false,
        "path": ""
    }],
    "id": 925,
    "description": "dfgsdfg",
    "status": {
        "code": "customer_accepted",
        "display": "Customer Accepted"
    },
    "amount": 379.00,
    "path": "https://api.cloudwords.com/1/project/807/bid.json"
}

Accept/Reject Bid

Accept or Reject the request to bid on a project. Note: Until you accept a bid request, the bidItems property of a bid will not be available.

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

Method(s)
POST

Returns
The specified bid resource (see 'Get Bid' for example).

Sample JSON request body:

{
	"status": {
		"code": "vendor_accepted" (OR "vendor_rejected")
	}
}

Bid "Status" Values

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

Submit Bid

Submit bid for the specified project. Note: this request body should be generated by fetching the bid on the server (using the request above) and then filling in the 'cost'.

Translation Cost Breakdown

For bidItemTasks with a parentType of 'translation', an additional numWords value should be added. This is done by adding a an attributes property to the task, and adding a numWords property to the attributes object. See the snippet below. 

...
{
"id": 69803,
"attributes": {
	"numWords": 10
},
"projectTaskType": {
	"type": "translation_translated_words",
	"display": "Translated Words",
	"parentType": "translation"
},
"cost": 100.00,
"path": ""
}
...

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

Method(s)
PUT

Returns
The specified bid resource.

Sample JSON response:

{
    "bidItems": [{
        "language": {
            "display": "French (France)",
            "languageCode": "fr-fr"
        },
        "id": 9721,
        "bidItemTasks": [{
            "id": 69793,
            "projectTaskType": {
                "type": "testing",
                "display": "Testing",
                "parentType": ""
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69801,
            "projectTaskType": {
                "type": "translation_repeated_words",
                "display": "Repeated Words",
                "parentType": "translation"
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69787,
            "projectTaskType": {
                "type": "desktop_publishing",
                "display": "Desktop Publishing",
                "parentType": ""
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69797,
            "projectTaskType": {
                "type": "translation_fuzzy_match_words",
                "display": "Fuzzy Match Words",
                "parentType": "translation"
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69795,
            "projectTaskType": {
                "type": "translation",
                "display": "Translation",
                "parentType": ""
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69803,
            "projectTaskType": {
                "type": "translation_translated_words",
                "display": "Translated Words",
                "parentType": "translation"
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69791,
            "projectTaskType": {
                "type": "review",
                "display": "Review",
                "parentType": ""
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69789,
            "projectTaskType": {
                "type": "post_edition",
                "display": "Post Editing",
                "parentType": ""
            },
            "cost": 0,
            "path": ""
        }, {
            "id": 69799,
            "projectTaskType": {
                "type": "translation_new_words",
                "display": "New Words",
                "parentType": "translation"
            },
            "cost": 0,
            "path": ""
        }],
        "isLanguageRemoved": false,
        "path": ""
    }],
    "id": 7843,
    "description": "",
    "status": {
        "code": "vendor_accepted",
        "display": "Needs Completion"
    },
    "amount": 0,
    "path": "https://api.cloudwords.com/1/project/10309/bid.json"
}

Translated Materials Methods

Upload Language Deliverable

Upload or update/overwrite the translated material for the specified project and language.

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

Version(s)
1

Method(s)
PUT

Returns
A new/updated metadata file resource for the project's language deliverable.

Request Body
A multipart upload which consists of a zip file that contains the translations for the specified language. 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/translated/language/fr/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/translated/language/fr.json"
}

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.

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

Version(s)
1.14+

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 properties to specify workflow status.

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/32044/file/translated/language/de/document/276.json",
    "id": 276,
    "file": {
        "path": "",
        "id": 523,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/content",
        "sizeInKilobytes": 8,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:20.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 520,
        "filename": "File-by-FileReview-ProjectWorkflow.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/xliff",
        "sizeInKilobytes": 9,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:06.000+0000"
    },
    "status": {
        "display": "In Revision",
        "code": "in_revision"
    },
    "sourceDocumentId": 273,
    "revisionRequest": {
        "path": "",
        "comment": "revise",
        "creator": {
            "path": "",
            "customer": {
                "path": "",
                "id": 8236,
                "name": ""
            }
        }
    },
    "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"
            }
        }
    }
}, {
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279.json",
    "id": 279,
    "file": {
        "path": "",
        "id": 830,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279/content",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-07T18:34:53.000+0000"
    },
    "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": "In Review",
        "code": "in_review"
    },
    "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"
            }
        }
    }
}, {
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/282.json",
    "id": 282,
    "file": {
        "path": "",
        "id": 525,
        "filename": "PaymentCards.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/282/content",
        "sizeInKilobytes": 64,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:23.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 522,
        "filename": "PaymentCards.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/282/xliff",
        "sizeInKilobytes": 55,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:09.000+0000"
    },
    "status": {
        "display": "In Review",
        "code": "in_review"
    },
    "sourceDocumentId": 275,
    "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"
            }
        }
    }
}
]

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/32044/file/translated/language/de/document/279.json",
    "id": 279,
    "file": {
        "path": "",
        "id": 830,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279/content",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-07T18:34:53.000+0000"
    },
    "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": "In Review",
        "code": "in_review"
    },
    "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"
            }
        }
    }
}

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 #931). 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="sample.txt"
Content-Type: text/plain


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

931
------WebKitFormBoundaryY7hFuRT1hogyCWVA--

Sample JSON response:

{
    "path": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279.json",
    "id": 279,
    "file": {
        "path": "",
        "id": 830,
        "filename": "ProjectSearchViewArchitecture.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/279/content",
        "sizeInKilobytes": 7,
        "fileContents": "",
        "createdDate": "2015-08-07T18:34:53.000+0000"
    },
    "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": "In Review",
        "code": "in_review"
    },
    "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.cloudwords.com/1.14/project/428/file/translated/language/de-ch/document/1059.json",
    "id": 1059,
    "draft": {
        "path": "",
        "id": 2290,
        "filename": "sample.txt",
        "contentPath": "https://api.cloudwords.com/1.14/project/428/file/translated/language/de-ch/document/1059/draft",
        "sizeInKilobytes": 1,
        "fileContents": "",
        "createdDate": "2014-09-24T19:55:18.000+0000"
    },
    "sourceDocumentId": 931
}

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-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276.json",
    "id": 276,
    "file": {
        "path": "",
        "id": 523,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/content",
        "sizeInKilobytes": 8,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:20.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 520,
        "filename": "File-by-FileReview-ProjectWorkflow.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/xliff",
        "sizeInKilobytes": 9,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:06.000+0000"
    },
    "status": {
        "display": "In Revision",
        "code": "in_revision"
    },
    "sourceDocumentId": 273,
    "revisionRequest": {
        "path": "",
        "comment": "revise",
        "creator": {
            "path": "",
            "customer": {
                "path": "",
                "id": 8236,
                "name": ""
            }
        }
    }

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/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-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276.json",
    "id": 276,
    "file": {
        "path": "",
        "id": 523,
        "filename": "File-by-FileReview-ProjectWorkflow.docx",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/content",
        "sizeInKilobytes": 8,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:20.000+0000"
    },
    "xliff": {
        "path": "",
        "id": 520,
        "filename": "File-by-FileReview-ProjectWorkflow.docx.xlf",
        "contentPath": "https://api-sandbox.cloudwords.com/1.18/project/32044/file/translated/language/de/document/276/xliff",
        "sizeInKilobytes": 9,
        "fileContents": "",
        "createdDate": "2015-07-31T18:38:06.000+0000"
    },
    "status": {
        "display": "In Revision",
        "code": "in_revision"
    },
    "sourceDocumentId": 273,
    "revisionRequest": {
        "path": "",
        "comment": "revise",
        "creator": {
            "path": "",
            "customer": {
                "path": "",
                "id": 8236,
                "name": ""
            }
        }
    }]

Deliver Translated Documents

The status of a translated material can be updated to '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).

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.

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.
not_ready The deliverable for the specified language is currently being synced to an external system.
ready_for_review The deliverable is ready for review, but has not yet been sent to the reviewer.
in_review The deliverable has been sent to the reviewer.

Translation Memory Methods

Upload Translation Memory

Upload the translation memory metadata for the specified project. The TM may be broken into multiple TMX files or be contained in a single TMX file. In either case, all of the TMX files must be zipped and uploaded as a single ZIP.

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

Version(s)
1

Method(s)
PUT

Returns
A new/updated metadata file resource for the project's translation memory.

Request Body
A multipart upload which consists of a zip file that contains one or more TMX files. The multipart parameter name for the file being uploaded is "file".

Sample JSON response:

{
    "id": 3391,
    "filename": "temp.tmx.zip",
    "createdDate": "2013-07-15T22:20:39.000+0000",
    "sizeInKilobytes": 2,
    "fileContents": "temp.tmx",
    "contentPath": "https://api.cloudwords.com/1/project/1257/file/tm/content",
    "path": "https://api.cloudwords.com/1/project/1257/file/tm.json"
}

Get TM Metadata

Get the metdata for the vendor-uploaded translation memory for this project

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

Version(s)
1

Method(s)
GET

Returns
Metadata for the vendor-provided translation memory.

Sample JSON response:

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

Download TM

Get the most recently uploaded TM for the project.
Note: This is the TM uploaded by the vendor near the close of the project.

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

Version(s)
1

Method(s)
GET

Returns
A stream containing a binary file (zip) uploaded Translation Memory.

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 customer 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": "revision with attachment",
    "id": 1705,
    "type": {
        "code": "revise_language",
        "display": "Revise Language"
    },
    "description": "description",
    "status": {
        "code": "closed",
        "display": "Closed"
    },
    "startDate": "2012-05-16T22:54:25.000+0000",
    "project": {
        "name": "test rev request",
        "id": 2655,
        "path": ""
    },
    "targetLanguage": {
        "display": "Chinese (Simplified)",
        "languageCode": "zh-cn"
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2012-05-16T22:54:25.000+0000",
    "closedDate": "2012-08-07T18:08:30.000+0000",
    "path": "https://api.cloudwords.com/1/project/2655/task/1705.json"
}, {
    "name": "revision with attachment",
    "id": 1707,
    "type": {
        "code": "revise_language",
        "display": "Revise Language"
    },
    "description": "description",
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T17:34:17.154+0000",
    "startDate": "2012-05-16T22:54:25.000+0000",
    "project": {
        "name": "test rev request",
        "id": 2655,
        "path": ""
    },
    "targetLanguage": {
        "display": "German",
        "languageCode": "de"
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2012-05-16T22:54:25.000+0000",
    "path": "https://api.cloudwords.com/1/project/2655/task/1707.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": "revision with attachment",
    "id": 1705,
    "type": {
        "code": "revise_language",
        "display": "Revise Language"
    },
    "description": "description",
    "status": {
        "code": "closed",
        "display": "Closed"
    },
    "startDate": "2012-05-16T22:54:25.000+0000",
    "project": {
        "name": "test rev request",
        "id": 2655,
        "path": ""
    },
    "targetLanguage": {
        "display": "Chinese (Simplified)",
        "languageCode": "zh-cn"
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2012-05-16T22:54:25.000+0000",
    "closedDate": "2012-08-07T18:08:30.000+0000",
    "path": "https://api.cloudwords.com/1/project/2655/task/1705.json"
}, {
    "name": "revision with attachment",
    "id": 1707,
    "type": {
        "code": "revise_language",
        "display": "Revise Language"
    },
    "description": "description",
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T17:34:17.154+0000",
    "startDate": "2012-05-16T22:54:25.000+0000",
    "project": {
        "name": "test rev request",
        "id": 2655,
        "path": ""
    },
    "targetLanguage": {
        "display": "German",
        "languageCode": "de"
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2012-05-16T22:54:25.000+0000",
    "path": "https://api.cloudwords.com/1/project/2655/task/1707.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": "revision with attachment",
    "id": 1707,
    "type": {
        "code": "revise_language",
        "display": "Revise Language"
    },
    "description": "description",
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T17:46:32.073+0000",
    "startDate": "2012-05-16T22:54:25.000+0000",
    "project": {
        "name": "test rev request",
        "id": 2655,
        "path": ""
    },
    "targetLanguage": {
        "display": "German",
        "languageCode": "de"
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2012-05-16T22:54:25.000+0000",
    "path": "https://api.cloudwords.com/1/project/2655/task/1707.json"
}

Get All Project Tasks

Get the list of all tasks across all projects. (Note: The set of all tasks across all projects can grow quickly, it is better to select by project or by status).

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:

[{
    "id": 935,
    "type": {
        "code": "upload_tm",
        "display": "Tm Uploaded"
    },
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T18:06:37.395+0000",
    "project": {
        "name": "test leveragin",
        "id": 1683,
        "path": ""
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "path": "https://api.cloudwords.com/1/project/all/task/935.json"
}, {
    "id": 27257,
    "type": {
        "code": "finish_project_cancellation_costs",
        "display": "Project Cancellation Bid"
    },
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T18:06:37.395+0000",
    "project": {
        "name": "Legal - Terms of Service",
        "id": 1735,
        "path": ""
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2013-06-20T18:48:20.000+0000",
    "path": "https://api.cloudwords.com/1/project/all/task/27257.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:

[{
    "id": 935,
    "type": {
        "code": "upload_tm",
        "display": "Tm Uploaded"
    },
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T18:06:37.395+0000",
    "project": {
        "name": "test leveragin",
        "id": 1683,
        "path": ""
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "path": "https://api.cloudwords.com/1/project/all/task/935.json"
}, {
    "id": 27257,
    "type": {
        "code": "finish_project_cancellation_costs",
        "display": "Project Cancellation Bid"
    },
    "status": {
        "code": "open",
        "display": "Open"
    },
    "dueDate": "2013-08-05T18:06:37.395+0000",
    "project": {
        "name": "Legal - Terms of Service",
        "id": 1735,
        "path": ""
    },
    "assignee": {
        "vendor": {
            "name": "Apple Localization",
            "id": 3037,
            "path": ""
        },
        "path": ""
    },
    "createdDate": "2013-06-20T18:48:20.000+0000",
    "path": "https://api.cloudwords.com/1/project/all/task/27257.json"
}]

Update Project Task

Update a specified task for the specified project.

Note: Vendors can use this only to change the status of a custom task that is assigned to the vendor.

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
status

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
}

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"
}

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 your bid, they must be requested by the customer, quoted by you, and approved by the customer in a similar manner to what happens when projects are created.

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

Sample JSON response:

[
    {
        "path": "http://api.cloudwords.com/1.12/project/2/changeOrder.json",
        "id": 3,
        "name": "CO3",
        "project": {
            "path": "",
            "id": 2,
            "name": "Test2"
        },
        "createdDate": "2014-03-24T21:44:16.000+0000",
        "description": "",
        "languagesToAdd": [
            {
                "display": "English",
                "languageCode": "en"
            }
        ],
        "languagesToRemove": [],
        "status": {
            "display": "Canceled",
            "code": "cancelled"
        }
    },
    {
        "path": "http://api.cloudwords.com/1.12/project/2/changeOrder.json",
        "id": 1,
        "name": "CO1",
        "project": {
            "path": "",
            "id": 2,
            "name": "Test2"
        },
        "createdDate": "2014-03-21T00:51:49.000+0000",
        "languagesToAdd": [
            {
                "display": "Chinese (Simplified)",
                "languageCode": "zh-cn"
            }
        ],
        "languagesToRemove": [],
        "status": {
            "display": "Customer Accepted",
            "code": "customer_accepted"
        }
    }
]

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/1.json",
    "id": 1,
    "name": "CO1",
    "project": {
        "path": "",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-03-21T00:51:49.000+0000",
    "languagesToAdd": [
        {
            "display": "Chinese (Simplified)",
            "languageCode": "zh-cn"
        }
    ],
    "languagesToRemove": [],
    "status": {
        "display": "Customer Accepted",
        "code": "customer_accepted"
    }
}

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": "Czech",
      "languageCode": "cs"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/changeOrder/27/workflow/cs.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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": "Bulgarian",
      "languageCode": "bg"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/changeOrder/27/workflow/bg.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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/257/changeOrder/27/workflow/de.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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": "Arabic",
      "languageCode": "ar"
    },
    "path": "http://api.cloudwords.com/1.12/project/257/changeOrder/27/workflow/ar.json",
    "steps": [
      {
        "name": "Translation",
        "path": "",
        "phases": [
          {
            "allowRevision": false,
            "assigneeType": {
              "code": "vendor",
              "display": "Vendor"
            },
            "dueDate": "2013-12-27T01: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"
    }
  }
]

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/257/changeOrder/27/workflow/de.json",
  "steps": [
    {
      "name": "Translation",
      "path": "",
      "phases": [
        {
          "allowRevision": false,
          "assigneeType": {
            "code": "vendor",
            "display": "Vendor"
          },
          "dueDate": "2013-12-27T01: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"
  }
}

Accept Change Order

Accepts a change order request submitted by the customer for 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 'requested' state can be accepted.

Sample JSON request:

{
    "status": {
        "code": "vendor_accepted"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/125.json",
    "id": 125,
    "name": "CO55",
    "project": {
        "path": "",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-22T16:52:15.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [],
    "status": {
        "display": "Vendor In Creation",
        "code": "vendor_in_creation"
    }
}

Submit Change Order

Submits a change order to the customer along with the associated bid.

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: Before you submit a change order to the customer, make sure you update the change order bid for the associated change order. Also, only the change order vendor_in_creation state can be submitted.

Sample JSON request:

{
    "status": {
        "code": "vendor_bid"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/125.json",
    "id": 125,
    "name": "CO55",
    "project": {
        "path": "",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-22T16:52:15.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [],
    "status": {
        "display": "Vendor Bid",
        "code": "vendor_bid"
    }
}

Cancel Change Order

Cancels/Rejects 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: Change orders can be cancelled only before submitting the bids to the customer.

Sample JSON request:

{
    "status": {
        "code": "vendor_rejected"
    }
}

Sample JSON response:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/126.json",
    "id": 126,
    "name": "CO55",
    "project": {
        "path": "",
        "id": 2,
        "name": "Test2"
    },
    "createdDate": "2014-04-22T18:31:24.000+0000",
    "description": "Created",
    "languagesToAdd": [],
    "languagesToRemove": [
        {
            "display": "Chinese (Simplified)",
            "languageCode": "zh-cn"
        },
        {
            "display": "Chinese (Traditional)",
            "languageCode": "zh-tw"
        }
    ],
    "status": {
        "display": "Vendor Rejected",
        "code": "vendor_rejected"
    }
}

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.

Get Change Order Bid

Gets the 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/125/bid.json",
    "id": 56,
    "description": "",
    "amount": 441,
    "bidItems": [
        {
            "path": "",
            "id": 191,
            "bidItemTasks": [
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "project_management",
                        "parentType": "",
                        "display": "Project Management"
                    },
                    "cost": 0,
                    "id": 1685
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_translated_words",
                        "parentType": "translation",
                        "display": "Translated Words"
                    },
                    "cost": 441,
                    "id": 1686,
                    "attributes": {
                        "numWords": 21
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "review",
                        "parentType": "",
                        "display": "Review"
                    },
                    "cost": 0,
                    "id": 1682
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_repeated_words",
                        "parentType": "translation",
                        "display": "Repeated Words"
                    },
                    "cost": 0,
                    "id": 1684,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_new_words",
                        "parentType": "translation",
                        "display": "New Words"
                    },
                    "cost": 0,
                    "id": 1689,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation",
                        "parentType": "",
                        "display": "Translation"
                    },
                    "cost": 441,
                    "id": 1690
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_fuzzy_match_words",
                        "parentType": "translation",
                        "display": "Fuzzy Match Words"
                    },
                    "cost": 0,
                    "id": 1683,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "desktop_publishing",
                        "parentType": "",
                        "display": "Desktop Publishing"
                    },
                    "cost": 0,
                    "id": 1688
                }
            ],
            "language": {
                "display": "Bulgarian",
                "languageCode": "bg"
            },
            "isLanguageRemoved": false
        },
        {
            "path": "",
            "id": 196,
            "bidItemTasks": [
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation",
                        "parentType": "",
                        "display": "Translation"
                    },
                    "cost": 0,
                    "id": 1735
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_repeated_words",
                        "parentType": "translation",
                        "display": "Repeated Words"
                    },
                    "cost": 0,
                    "id": 1729,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "desktop_publishing",
                        "parentType": "",
                        "display": "Desktop Publishing"
                    },
                    "cost": 0,
                    "id": 1733
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "review",
                        "parentType": "",
                        "display": "Review"
                    },
                    "cost": 0,
                    "id": 1727
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_new_words",
                        "parentType": "translation",
                        "display": "New Words"
                    },
                    "cost": 0,
                    "id": 1734,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_translated_words",
                        "parentType": "translation",
                        "display": "Translated Words"
                    },
                    "cost": 0,
                    "id": 1731,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "project_management",
                        "parentType": "",
                        "display": "Project Management"
                    },
                    "cost": 0,
                    "id": 1730
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_fuzzy_match_words",
                        "parentType": "translation",
                        "display": "Fuzzy Match Words"
                    },
                    "cost": 0,
                    "id": 1728,
                    "attributes": {
                        "numWords": 0
                    }
                }
            ],
            "language": {
                "display": "French (France)",
                "languageCode": "fr-fr"
            },
            "isLanguageRemoved": true
        }
    ]
}

Update Change Order Bid

Updates/over-writes existing change order bid associated with the specified change order

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

Version(s)
1.12

Method(s)

PUT

Required Field(s)
bidItems, bidItems.id, bidItems.bidItemTasks, bidItems.bidItemTasks.id, bidItems.bidItemTasks.cost

Returns
The updated bid resource for the specified change order.

Sample JSON request:

{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/127/bid.json",
    "id": 57,
    "description": "",
    "amount": 441,
    "bidItems": [
        {
            "path": "",
            "id": 197,
            "bidItemTasks": [
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_translated_words",
                        "parentType": "translation",
                        "display": "Translated Words"
                    },
                    "cost": 441,
                    "id": 1740,
                    "attributes": {
                        "numWords": 21
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_repeated_words",
                        "parentType": "translation",
                        "display": "Repeated Words"
                    },
                    "cost": 22,
                    "id": 1738,
                    "attributes": {
                        "numWords": 200
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation",
                        "parentType": "",
                        "display": "Translation"
                    },
                    "cost": 463,
                    "id": 1744
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "project_management",
                        "parentType": "",
                        "display": "Project Management"
                    },
                    "cost": 0,
                    "id": 1739
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "review",
                        "parentType": "",
                        "display": "Review"
                    },
                    "cost": 0,
                    "id": 1736
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_new_words",
                        "parentType": "translation",
                        "display": "New Words"
                    },
                    "cost": 0,
                    "id": 1743,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "desktop_publishing",
                        "parentType": "",
                        "display": "Desktop Publishing"
                    },
                    "cost": 10,
                    "id": 1742
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_fuzzy_match_words",
                        "parentType": "translation",
                        "display": "Fuzzy Match Words"
                    },
                    "cost": 0,
                    "id": 1737,
                    "attributes": {
                        "numWords": 0
                    }
                }
            ],
            "language": {
                "display": "Bulgarian",
                "languageCode": "bg"
            },
            "isLanguageRemoved": false
        }
    ]
}

Sample JSON response:

{{
    "path": "http://api.cloudwords.com/1.12/project/2/changeOrder/127/bid.json",
    "id": 57,
    "description": "",
    "amount": 473,
    "bidItems": [
        {
            "path": "",
            "id": 197,
            "bidItemTasks": [
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_new_words",
                        "parentType": "translation",
                        "display": "New Words"
                    },
                    "cost": 0,
                    "id": 1743,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_repeated_words",
                        "parentType": "translation",
                        "display": "Repeated Words"
                    },
                    "cost": 22,
                    "id": 1738,
                    "attributes": {
                        "numWords": 200
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation",
                        "parentType": "",
                        "display": "Translation"
                    },
                    "cost": 463,
                    "id": 1744
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_translated_words",
                        "parentType": "translation",
                        "display": "Translated Words"
                    },
                    "cost": 441,
                    "id": 1740,
                    "attributes": {
                        "numWords": 21
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "project_management",
                        "parentType": "",
                        "display": "Project Management"
                    },
                    "cost": 0,
                    "id": 1739
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "translation_fuzzy_match_words",
                        "parentType": "translation",
                        "display": "Fuzzy Match Words"
                    },
                    "cost": 0,
                    "id": 1737,
                    "attributes": {
                        "numWords": 0
                    }
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "desktop_publishing",
                        "parentType": "",
                        "display": "Desktop Publishing"
                    },
                    "cost": 10,
                    "id": 1742
                },
                {
                    "path": "",
                    "projectTaskType": {
                        "type": "review",
                        "parentType": "",
                        "display": "Review"
                    },
                    "cost": 0,
                    "id": 1736
                }
            ],
            "language": {
                "display": "Bulgarian",
                "languageCode": "bg"
            },
            "isLanguageRemoved": false
        }
    ]
}

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>"
}

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>"
}

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)

Translation Requests

Translation Request "Status" Values

Translation Requests are sent to the vendor(s) by the customers 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 going through the bidding phase (without the preferred vendor needing to specify quotes and submit bid). If the translation request field 'requiresBidding' is set to true, then the vendor is accepted to submit bids for the translation after accepting the translation request. When the 'requiresBidding' is set to false, the vendor can proceed with the translation process by simply accepting the request.

Status field

Translation Request can go through various stages or statuses as they are managed. Below is the set of all translation request 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
waiting_for_vendor This state implies that the translation request is set to bidding phase and the vendor needs to take action for the request.
vendor_rejected This state implies that the translation request is set to bidding phase and the vendor has rejected the translation request.
vendor_accepted This state implies that the translation request is set to bidding phase and the vendor has accepted the translation request.
vendor_in_creation This state implies that the translation request is set to bidding phase and the vendor has accepted the translation request. Currently vendor bid is in progress and has not been submitted yet.
submitted This state implies that the translation request is set to bidding phase and the vendor has submitted the bid after accepting the translation request.
customer_accepted This state implies that the translation request is set to bidding phase and the vendor bid submitted has been accepted by the customer.
customer_rejected This state implies that the translation request is set to bidding phase and the vendor bid submitted has been rejected by the customer.
translation_request_pending This state implies that the translation request is set to non-bidding phase and the vendor needs to take action for the request.
translation_request_accepted This state implies that the translation request is set to non-bidding phase and that the vendor has accepted the translation request and the translation process has began.
translation_request_rejected This state implies that the translation request is set to non-bidding phase and that the vendor has rejected the translation request

 

Get Translation Request

Get the current translation request resource for this project.

URL Structure
<base_uri>/<version>/project/{projectId}/translation-request/current.json

Version(s)
1.19

Method(s)
GET

Returns
The specified translation request.

Sample JSON response:

{
  "createdDate":1441824813000,
  "description":"",
  "requiresBidding":false,
  "status": {
    "display":"Translation Request Pending",
    "code":"translation_request_pending"
    },
  "bidItems":null,
  "amount":null
}

OR

{  
   "createdDate":1441825455000,
   "description":"",
   "requiresBidding":true,
   "status":{  
      "display":"Needs Completion",
      "code":"vendor_accepted"
   },
   "bidItems":[  
      {  
         "path":"",
         "id":2383,
         "bidItemTasks":[  
            {  
               "path":"",
               "projectTaskType":{  
                  "type":"translation_fuzzy_match_words",
                  "parentType":"translation",
                  "display":"Fuzzy Match Words"
               },
               "cost":0,
               "id":22302,
               "attributes":null
            },
            ..
            ..
            ..
            ..
}

Accept Translation Request

Accepts translation request submitted by the customer.

URL Structure
<base_uri>/<version>/project/{projectId}/translation-request

Version(s)
1.19

Method(s)
POST

Returns
The specified translation request.

Sample JSON request body:

{
  "requiresBidding":false,
  "status": {
     "code": "translation_request_accepted"
  }
}

OR

{
  "requiresBidding":true,
  "status": {
    "code": "vendor_accepted"
  }
}

Reject Translation Request

Rejects translation request submitted by the customer.

URL Structure
<base_uri>/<version>/project/{projectId}/translation-request

Version(s)
1.19

Method(s)
POST

Returns
The specified translation request.

Sample JSON request body:

{
  "requiresBidding":false,
  "status": {
     "code": "translation_request_rejected"
  }
  "rejectionReason" : "Spanish tranlsator unavailable"
}

OR

{
  "requiresBidding":true,
  "status": {
    "code": "vendor_rejected"
  }
  "rejectionReason" : "Spanish tranlsator unavailable"
}

Submit Translation Request

This api is applicable only for translation requests which have requiresBidding field set to true. Use this api to submit bid for a translation request. The vendor needs to accept the translation request first, before submitting the bid. Note: The request body for the bidItems should be generated by fetching the bid from the server (using the Get Translation Request above) and then filling in the 'cost'.

URL Structure
<base_uri>/<version>/project/{projectId}/translation-request

Version(s)
1.19

Method(s)
PUT

Returns
The specified translation request with bid status submitted.

Sample JSON request body:

{  
   "description":"Bid description",
   "requiresBidding":true,
   "bidItems":[  
      {  
         "path":"",
         "id":2391,
         "bidItemTasks":[  
            {  
               "path":"",
               "projectTaskType":{  
                  "type":"review",
                  "parentType":"",
                  "display":"Review"
               },
               "cost":37163,
               "id":22372,
               "attributes":null
            },
            {  
               "path":"",
               "projectTaskType":{  
                  "type":"translation_fuzzy_match_words",
                  "parentType":"translation",
                  "display":"Fuzzy Match Words"
               },
               "cost":534,
               "id":22374,
               "attributes":{  
                  "numWords":4872
               }
            },
            {  
               "path":"",
               "projectTaskType":{  
                  "type":"translation_new_words",
                  "parentType":"translation",
                  "display":"New Words"
               },
               "cost":534,
               "id":22375,
               "attributes":{  
                  "numWords":3047
               }
            },
            ..
            ..
            ..
}

Translation Units Review

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":{  

                  }
               }
            ]
         }
      ]
   }
]