Create

To create a resource, the resource representation (either xml or json depending on Content-Type header) should be POSTed to the collection URL.

For example, to create a Project with XML, the following request could be used:

POST /api/v1/Projects
Content-Type: application/xml
 
<Project Name="Some Project"/>

If a resource was created successfully, the response will include resource represenation and has HTTP status 201. Otherwise the response will include a description of the error.

Here is example of successful creation responce:

HTTP/1.1 201 Created
Content-Length: 505
Content-Type: application/xml; charset=utf-8
 
<Project Id="378" Name="Some Project">
 <Description nil="true" />
 <StartDate nil="true" />
 <EndDate nil="true" />
 <CreateDate>2011-09-01T18:33:17</CreateDate>
 <ModifyDate>2011-09-01T18:33:17</ModifyDate>
 <LastCommentDate nil="true" />
 <Tags></Tags>
 <IsActive>true</IsActive>
 <IsProduct>false</IsProduct>
 <Owner Id="316" />
 <Project nil="true" />
 <Program nil="true" />
 <Process Id="1" Name="All Practices" />
 <Company nil="true" />
 <CustomFields />
</Project>

Same can be done in JSON format as well:

POST /api/v1/Projects
Content-Type: application/json

{
 "Name":"Some Project"
}

🚧

Custom numeric IDs are not supported

ID of any created items are assigned and set automatically. It's not possible to set a custom ID for a newly created item.
In fact, if you put ID in your POST request, you'll perform UPDATE action instead of Create.

Control parameters of response with output data

You can control the results representation using resultFormat, resultInclude, resultExclude and resultAppend URL parameters.

Required (mandatory) fields

When you create an entity, make sure you provide all required (mandatory) fields. For example, for new User Story mandatory fields are Name and Project ID. All other fields are optional and can be left blank.

POST /api/v1/UserStories?resultFormat=json&resultInclude=[Id,Name,Project]
Content-Type: application/json
 
{
  "Name":"New User Story",
  "Project":{"Id":2}
}

Result response:

HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
 
{
 "Id": 379,
 "Name": "New User Story",
 "Project": {
 "Id": 2,
 "Name": "Some Project"
 }
}

Use resources meta info to get list of required fields per each entity type.

Batch create entities within a single POST

It is possible to create several Targetprocess entities within single POST request sent to REST API.

For example, let's create two user stories with names "New Story Name 1" and "New Story Name 2" inside project with ID #2.

POST /api/v1/UserStories/bulk
Content-Type: application/json

[
	{
		"Name":"New Story Name 1",
		"Project":{"Id":2}
	},
	{
		"Name":"New Story Name 2",
		"Project":{"Id":2}
	}
]

Batch actions have limitations. Please do not create more than 500 entities in the single API call.

Create entities with nested ones

It is possible to create nested (child) items together with parent ones in a single API call. For example, create User Story with Tasks:

POST /api/v1/UserStories
Content-Type: application/json

{
  "Name":"New Story",
  "Project":{"ID":2},
  "Tasks":{
   "Items":[
    {"Name":"Task 1","Project":{"ID":2}},
    {"Name":"Task 2","Project":{"ID":2}},
    {"Name":"Task 3","Project":{"ID":2}}
   ]
  }
}