Troubleshooting REST API issues

401 error (authentication error)

Possible reason

Solution

Wrong URL

Make sure you're using real URL of your account, and not https://restapi.tpondemand.com/, https://md5.tpondemand.com/, or any other URL from the examples

Wrong token

Make sure you've copied the token completely, without leaving out any symbols

Mix up of token and personal token

Depending what what kind of token you've generated, make sure you're either using token or access_token parameter

SSO is enabled

https://www.targetprocess.com/guide/settings/sso/single-sign-on-in-targetprocess/#REST_API_usage

Incomplete result

Possible reason

Solution

Lack of paging

If you do not specify take parameter, you'll only get 25 items. Use paging to get up to 1000 items per API call with APIv1 or APIv2.

Some field are empty and you're using APIv2

With APIv2 if the field is empty, it will not be present in the response at all

You're not specifying which fields you'd like to pull

If you do not specify include in APIv1 or select in APIv2, only some basic fields be returned in the response. Please make sure to enumerate all the fields that you'd like to get

Mix up of APIv1 and APIv2 syntax

If you make APIv1 query, and you use API2 parameter select, it will be ignored. The same goes for API2 query with APIv1 selector include. Please make sure you're using appropriate the syntax for your API version.

Using or in APIv1 filter

If you try to combine two conditions with or in APIv1, only the first one will be applied. or in filters is only supported in APIv2.

Pulling two fields with the same name with APIv2

For example: select={id,project.id}
It will try to pull two fields - id of the entity, and id of its project - with the same name id
Solution is to define a custom name for at least one of them (or both of them):
select={entityId:id,project.id}
select={id,projectId:project.id}
select={entityId:id,projectId:project.id}

500 error (bad request) - for GET requests

🚧

Always double-check the structure of data (field names, object names, collection names, connections between different object) in meta: https://md5.tpondemand.com/api/v1/index/meta

Possible reason

Solution

Mix up of APIv1 and APIv2 syntax

APIv1 and APIv2 have different syntax. For example, to filter an item by Project in APIv1 we would use where=(project.name eq "Mobile"), while in APIv2 it would be where=(project.name="Mobile"). Please make sure you're using appropriate the syntax for your API version.

Using a term instead of the real entity name, e.g trying to pull Portfolio instead of Project (error message: "Property 'Portfolio' does not exist in 'UserStory'.")

Make sure you're using real entity type names, and not terms. You should get the name of the field that not exist (the term) in the response.

Pulling a field that does not exist (error message: "Property 'field' does not exist in 'UserStory'.")

Make sure you only pull the fields that actually exist in this entity. You should get the name of the field that not exist in the response.

Using invalid quotes (very popular among Mac users)

Make sure you're only using ' or " as quotes, and never ` or any other type of quotes.

Using a complex selector in APIv2 without defining a custom name for it (error message: "Expression is missing an 'as' clause.")

Example: select={id,name,Comments.Where(Owner.Kind="User").Max(CreateDate)}
Solution: define a custom name
select={id,name,lastcommented:Comments.Where(Owner.Kind="User").Max(CreateDate)}

Trying to aggregate an aggregation (reaching for a collection of a collection)

Examples:
select={effort:UserStories.Sum(Tasks.Sum(Effort))}
select={maxdate:UserStories.Max(Tasks.Max(PlannedEndDate))}
select={count:UserStories.Sum(Tasks.Count)}
Solution: create a custom field and a metric and store the intermediate result there

500 error (bad request) - for POST requests

🚧

Always double-check the structure of data (field names, object names, collection names, connections between different object) in meta: https://md5.tpondemand.com/api/v1/index/meta

Possible reason

Solution

Using a term instead of the real entity name

Make sure you're using real entity type names, and not terms.

Trying to set an object (like EntityState, Release, Project, Team, etc.) using its name (instead of its ID), e.g.
EntityState:"Done"

Always use ID to set an object value:
EntityState:{Id:123}
If you do not know its ID - make GET API call to put it beforehand.

Trying to set a collection (like Assigned Teams, Assignments, Comments) incorrectly, e.g.
AssignedTeams:"Team Alpha"
AssignedTeams:{Id:123}

Use an array to set a collection. Inside this array every value is an object, so it has to be set using its ID:
AssignedTeams:[{Team:{Id:123}}]

403 error (not allowed)

Make sure that the user that you're using for Authentication have permission to perform the action that you're trying to do: https://www.targetprocess.com/guide/settings/users-roles-permissions/roles-permissions/