Touchplan API
Information on the use of Touchplan API endpoints.
Urls should be in the format https://api.touchplan.io/vX/resource
Urls should be in the format https://api.touchplan.io/vX/resource
More information: https://www.touchplan.io
Contact Info: Touchplan live chat
Version: 1.0
Copyright (c) 2024 MOCA Systems, Inc. All rights reserved.
Access
Methods
[ Jump to Models ]Table of Contents
Auth
GenerateCustomToken
Plans
post /v1/plans/{projectId}
delete /v1/plans/{projectId}/{planId}
get /v1/plans/{projectId}
put /v1/plans/{projectId}
Projects
post /v1/projects/{projectId}/members
get /v1/projects/{projectId}
get /v1/projects/{projectId}/members
get /v1/projects
delete /v1/projects/{projectId}/members/{memberId}
post /v1/projects/{projectId}/exports
post /v1/projects/{projectId}/reports
Swimlanes
Tickets
get /v1/tickets/{projectId}/{planId}
post /v1/tickets/{projectId}/{planId}
post /v1/tickets/{projectId}/customFields
Auth
Up
post /v1/auth
Takes login credentials as parameters and returns an authentication token, for use in other API requests (authControllerLogin)
This takes client ID and client secret parameters and – if valid – returns a JWT token that can be used as an authentication token in other API requests. That token has a limited lifetime (about an hour). If the given credentials are invalid, an error is returned with an error message explaining the specific problem.
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body AuthDto (required)
Body Parameter —
Request headers
Return type
Example data
Content-Type: application/json
{
"token" : "token"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
201
AuthResponseDto401
Authentication failed. Client ID or client secret is incorrect. ErrorResponseDtodefault
A result JWT token AuthResponseDto
Up
post /v1/auth/customToken/{userId}
Creates a custom token for a given user (authCustomTokenGeneratorControllerGetCustomToken)
Validates if the requester is authorized to generate a custom token for the given user.
if the requester is authorized, it generates a custom token for the given user.
Path parameters
userId (required)
Path Parameter —
Request headers
Return type
Example data
Content-Type: application/json
{
"token" : "token"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
201
AuthResponseDtodefault
An object containing just one field 'token' which is the custom token generated for the given user. AuthResponseDtoGenerateCustomToken
Up
post /v1/auth/customToken/{userId}
Creates a custom token for a given user (authCustomTokenGeneratorControllerGetCustomToken)
Validates if the requester is authorized to generate a custom token for the given user.
if the requester is authorized, it generates a custom token for the given user.
Path parameters
userId (required)
Path Parameter —
Request headers
Return type
Example data
Content-Type: application/json
{
"token" : "token"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
201
AuthResponseDtodefault
An object containing just one field 'token' which is the custom token generated for the given user. AuthResponseDtoPlans
Up
post /v1/plans/{projectId}
Create plan (createPlan)
Creates the plan specified by the request body and returns it.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body PlanModel (required)
Body Parameter — Plan data to be created
Return type
Example data
Content-Type: application/json
{
"milestoneDate" : "2000-01-23",
"milestoneName" : "milestoneName",
"name" : "name",
"finishDate" : "2000-01-23",
"id" : "id",
"projectId" : "projectId",
"startDate" : "2000-01-23",
"currentPromisePeriodStartDate" : "2000-01-23",
"activeLineDate" : "2000-01-23"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK PlanModel
Up
delete /v1/plans/{projectId}/{planId}
Delete plan (deletePlan)
Deletes the plan specified by the project Id and plan Id. No-op if a plan is not found.
Path parameters
planId (required)
Path Parameter —
projectId (required)
Path Parameter —
Responses
204
No Content
Up
get /v1/plans/{projectId}
Get plan (getPlans)
Returns a plan given the projectId and planName. If no plan is specified, all plans will be returned.
Path parameters
projectId (required)
Path Parameter —
Query parameters
planName (optional)
Query Parameter —
Return type
Example data
Content-Type: application/json
{
"plans" : [ {
"milestoneDate" : "2000-01-23",
"milestoneName" : "milestoneName",
"name" : "name",
"finishDate" : "2000-01-23",
"id" : "id",
"projectId" : "projectId",
"startDate" : "2000-01-23",
"currentPromisePeriodStartDate" : "2000-01-23",
"activeLineDate" : "2000-01-23"
}, {
"milestoneDate" : "2000-01-23",
"milestoneName" : "milestoneName",
"name" : "name",
"finishDate" : "2000-01-23",
"id" : "id",
"projectId" : "projectId",
"startDate" : "2000-01-23",
"currentPromisePeriodStartDate" : "2000-01-23",
"activeLineDate" : "2000-01-23"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK PlanResponseModel
Up
put /v1/plans/{projectId}
Update plan (updatePlan)
Update the plan specified by the request body and returns it.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body PlanModel (required)
Body Parameter — Plan data to be updated. Note some fields will be ignored e.g. id.
Return type
Example data
Content-Type: application/json
{
"milestoneDate" : "2000-01-23",
"milestoneName" : "milestoneName",
"name" : "name",
"finishDate" : "2000-01-23",
"id" : "id",
"projectId" : "projectId",
"startDate" : "2000-01-23",
"currentPromisePeriodStartDate" : "2000-01-23",
"activeLineDate" : "2000-01-23"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK PlanModelProjects
Up
post /v1/projects/{projectId}/members
Adds a new member to the project and optionally sends a project invitation (addMemberControllerAddMember)
Adds a new member to the project and optionally sends a project invitation via the given email address. The "accessLevel" parameter must be either "Admin" or "General" (ignoring case). And ID parameter must be a valid reference, e.g. the "projectId" must reference an existing project.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body AddMemberDto (required)
Body Parameter —
Request headers
Return type
Example data
Content-Type: application/json
{
"userWasInvited" : true,
"userWasAdded" : true,
"projectMemberId" : "-Mz_qJWfPbOSZ9cipJG5",
"userId" : "6ZG0ZfMzwUxEWcESZN1ME7925ff1"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
201
AddMemberResponseDto400
Invalid parameter value ErrorResponseDtodefault
Information about the "addMember" results AddMemberResponseDto
Up
get /v1/projects/{projectId}
Get project details (getProjectDetails)
Returns details for a project given its projectId
Path parameters
projectId (required)
Path Parameter —
Return type
Example data
Content-Type: application/json
{
"owner" : "owner",
"country" : "country",
"marketSector" : "marketSector",
"address" : "address",
"city" : "city",
"timezone" : "timezone",
"roles" : [ {
"schedule" : [ 1.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0 ],
"color" : "color",
"name" : "name",
"id" : "id"
}, {
"schedule" : [ 1.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0 ],
"color" : "color",
"name" : "name",
"id" : "id"
} ],
"exceptionDays" : [ {
"date" : "2000-01-23",
"description" : "description"
}, {
"date" : "2000-01-23",
"description" : "description"
} ],
"postcode" : "postcode",
"type" : "type",
"url" : "url",
"schedule" : [ 1.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0 ],
"createdDate" : "2000-01-23",
"scheduleDateRange" : "[2020-01-01, 2020-02-15]",
"name" : "name",
"variances" : [ {
"reason" : "reason",
"color" : "color",
"id" : "id",
"key" : 0
}, {
"reason" : "reason",
"color" : "color",
"id" : "id",
"key" : 0
} ],
"customFieldDefinitions" : [ {
"unit" : "unit",
"dataType" : "dataType",
"roles" : {
"key" : true
},
"ticketTypes" : {
"key" : true
},
"customFieldListOfValues" : "",
"id" : "id",
"label" : "label",
"type" : "text",
"enabled" : true,
"order" : 6.027456183070403
}, {
"unit" : "unit",
"dataType" : "dataType",
"roles" : {
"key" : true
},
"ticketTypes" : {
"key" : true
},
"customFieldListOfValues" : "",
"id" : "id",
"label" : "label",
"type" : "text",
"enabled" : true,
"order" : 6.027456183070403
} ],
"locations" : [ {
"color" : "color",
"name" : "name",
"id" : "id"
}, {
"color" : "color",
"name" : "name",
"id" : "id"
} ],
"id" : "id",
"status" : "active",
"territory" : "territory"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK ProjectDetailsModel
Up
get /v1/projects/{projectId}/members
Get members of a project (getProjectMembersDetails)
Returns members of a project with user information
Path parameters
projectId (required)
Path Parameter —
Return type
Example data
Content-Type: application/json
{
"projectMembers" : [ {
"primaryRoleId" : "primaryRoleId",
"emailAddress" : "emailAddress",
"secondaryRoleIds" : [ "secondaryRoleIds", "secondaryRoleIds" ],
"isAdmin" : true,
"projectId" : "projectId",
"userId" : "userId",
"memberId" : "memberId"
}, {
"primaryRoleId" : "primaryRoleId",
"emailAddress" : "emailAddress",
"secondaryRoleIds" : [ "secondaryRoleIds", "secondaryRoleIds" ],
"isAdmin" : true,
"projectId" : "projectId",
"userId" : "userId",
"memberId" : "memberId"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK ProjectMemberResponseModel
Up
get /v1/projects
Get projects (getProjects)
Returns a list of projects to which the authenticated user is a member of the project.
Return type
Example data
Content-Type: application/json
{
"projects" : [ {
"owner" : "owner",
"createdDate" : "2000-01-23",
"scheduleDateRange" : "[2020-01-01, 2020-02-15]",
"name" : "name",
"id" : "id",
"type" : "type",
"url" : "url",
"status" : "active"
}, {
"owner" : "owner",
"createdDate" : "2000-01-23",
"scheduleDateRange" : "[2020-01-01, 2020-02-15]",
"name" : "name",
"id" : "id",
"type" : "type",
"url" : "url",
"status" : "active"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK ProjectResponseModel
Up
delete /v1/projects/{projectId}/members/{memberId}
Removes a member from a project (removeMemberControllerRemoveMember)
Removes a member from the project, given the user’s "memberId" in the project.
Path parameters
projectId (required)
Path Parameter —
memberId (required)
Path Parameter —
Request headers
Return type
Example data
Content-Type: application/json
{
"message" : "Successfully removed user from project",
"status" : "success"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
RemoveMemberResponseDtodefault
A status string and status description RemoveMemberResponseDto
Up
post /v1/projects/{projectId}/exports
Run an export against the project (runExport)
Runs the requested export inline. Will block and wait for the request to finish before returning.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body ExportRequest (required)
Body Parameter — The request body
Return type
Example data
Content-Type: application/json
{
"exports" : [ {
"completedAt" : "2000-01-23T04:56:07.000+00:00",
"data" : {
"key" : "data"
},
"errorMessage" : "errorMessage",
"startedAt" : "2000-01-23T04:56:07.000+00:00"
}, {
"completedAt" : "2000-01-23T04:56:07.000+00:00",
"data" : {
"key" : "data"
},
"errorMessage" : "errorMessage",
"startedAt" : "2000-01-23T04:56:07.000+00:00"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK ExportResponseModel
Up
post /v1/projects/{projectId}/reports
Run a report against the project (runReport)
Runs the requested report inline. Will block and wait for the request to finish before returning.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body ReportRequest (required)
Body Parameter — The request body
Return type
Example data
Content-Type: application/json
{
"reports" : [ {
"completedAt" : "2000-01-23T04:56:07.000+00:00",
"data" : {
"key" : "data"
},
"errorMessage" : "errorMessage",
"startedAt" : "2000-01-23T04:56:07.000+00:00"
}, {
"completedAt" : "2000-01-23T04:56:07.000+00:00",
"data" : {
"key" : "data"
},
"errorMessage" : "errorMessage",
"startedAt" : "2000-01-23T04:56:07.000+00:00"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK ReportResponseModelSwimlanes
Up
get /v1/swimlanes/{projectId}
Get swimlanes for a project (getSwimlanes)
Returns swimlanes given the projectId. If no planId is specified, all swimlanes will be returned.
Path parameters
projectId (required)
Path Parameter —
Query parameters
planId (optional)
Query Parameter —
Return type
Example data
Content-Type: application/json
{
"swimlanes" : [ {
"upperY" : 0,
"color" : "color",
"lowerY" : 6,
"name" : "name",
"planId" : "planId",
"id" : "id"
}, {
"upperY" : 0,
"color" : "color",
"lowerY" : 6,
"name" : "name",
"planId" : "planId",
"id" : "id"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK SwimlaneResponseModelTickets
Up
get /v1/tickets/{projectId}/{planId}
Get tickets (getTickets)
Returns all tickets for the given project, plan. "filter" query parameter can be "active" or "pull" and results will only return tickets in the active space or tickets in the pull space respectively.
Path parameters
planId (required)
Path Parameter —
projectId (required)
Path Parameter —
Query parameters
filter (optional)
Query Parameter —
Return type
Example data
Content-Type: application/json
{
"tickets" : [ {
"createdAtDate" : "2000-01-23",
"predecessors" : [ {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
}, {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
} ],
"createdByProjectMemberId" : "createdByProjectMemberId",
"customFields" : [ {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
}, {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
} ],
"yPosition" : 6,
"actualWorkingDays" : [ true, true ],
"plannedWorkingDays" : [ true, true ],
"actualDuration" : 2.5,
"description" : "description",
"type" : "task",
"duration" : 1.5,
"locationId" : "locationId",
"actualStartDate" : "2000-01-23",
"planId" : "planId",
"id" : "id",
"promises" : {
"key" : {
"varianceNote" : "varianceNote",
"promiseDate" : "2000-01-23",
"varianceId" : "varianceId",
"stateDisplay" : "stateDisplay",
"finishDate" : "2000-01-23",
"state" : "state",
"varianceReason" : "varianceReason"
}
},
"actualCrewSize" : 4.5,
"roleId" : "roleId",
"needByDate" : "2000-01-23",
"requestedByMemberId" : "requestedByMemberId",
"assignedToMemberId" : "assignedToMemberId",
"crewSize" : 5.5,
"externalScheduleId" : "externalScheduleId",
"plannedStartDate" : "2000-01-23",
"plannedFinishDate" : "2000-01-23",
"actualFinishDate" : "2000-01-23",
"projectId" : "projectId",
"status" : "COMPLETE"
}, {
"createdAtDate" : "2000-01-23",
"predecessors" : [ {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
}, {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
} ],
"createdByProjectMemberId" : "createdByProjectMemberId",
"customFields" : [ {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
}, {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
} ],
"yPosition" : 6,
"actualWorkingDays" : [ true, true ],
"plannedWorkingDays" : [ true, true ],
"actualDuration" : 2.5,
"description" : "description",
"type" : "task",
"duration" : 1.5,
"locationId" : "locationId",
"actualStartDate" : "2000-01-23",
"planId" : "planId",
"id" : "id",
"promises" : {
"key" : {
"varianceNote" : "varianceNote",
"promiseDate" : "2000-01-23",
"varianceId" : "varianceId",
"stateDisplay" : "stateDisplay",
"finishDate" : "2000-01-23",
"state" : "state",
"varianceReason" : "varianceReason"
}
},
"actualCrewSize" : 4.5,
"roleId" : "roleId",
"needByDate" : "2000-01-23",
"requestedByMemberId" : "requestedByMemberId",
"assignedToMemberId" : "assignedToMemberId",
"crewSize" : 5.5,
"externalScheduleId" : "externalScheduleId",
"plannedStartDate" : "2000-01-23",
"plannedFinishDate" : "2000-01-23",
"actualFinishDate" : "2000-01-23",
"projectId" : "projectId",
"status" : "COMPLETE"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK TicketResponseModel
Up
post /v1/tickets/{projectId}/{planId}
Get ticket details (getTicketsDetails)
Returns details for the tickets specified by the ticketIds field of the required body object. List of ticketIds is limited to 1000.
Path parameters
planId (required)
Path Parameter —
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body TicketsRequestModel (optional)
Body Parameter —
Return type
Example data
Content-Type: application/json
{
"tickets" : [ {
"createdAtDate" : "2000-01-23",
"predecessors" : [ {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
}, {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
} ],
"createdByProjectMemberId" : "createdByProjectMemberId",
"customFields" : [ {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
}, {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
} ],
"yPosition" : 6,
"actualWorkingDays" : [ true, true ],
"plannedWorkingDays" : [ true, true ],
"actualDuration" : 2.5,
"description" : "description",
"type" : "task",
"duration" : 1.5,
"locationId" : "locationId",
"actualStartDate" : "2000-01-23",
"planId" : "planId",
"id" : "id",
"promises" : {
"key" : {
"varianceNote" : "varianceNote",
"promiseDate" : "2000-01-23",
"varianceId" : "varianceId",
"stateDisplay" : "stateDisplay",
"finishDate" : "2000-01-23",
"state" : "state",
"varianceReason" : "varianceReason"
}
},
"actualCrewSize" : 4.5,
"roleId" : "roleId",
"needByDate" : "2000-01-23",
"requestedByMemberId" : "requestedByMemberId",
"assignedToMemberId" : "assignedToMemberId",
"crewSize" : 5.5,
"externalScheduleId" : "externalScheduleId",
"plannedStartDate" : "2000-01-23",
"plannedFinishDate" : "2000-01-23",
"actualFinishDate" : "2000-01-23",
"projectId" : "projectId",
"status" : "COMPLETE"
}, {
"createdAtDate" : "2000-01-23",
"predecessors" : [ {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
}, {
"isCyclic" : true,
"isOutOfOrder" : true,
"linkageType" : "FS",
"outOfOrder" : true,
"planId" : "planId",
"lagDays" : 0,
"ticketId" : "ticketId",
"cyclic" : true
} ],
"createdByProjectMemberId" : "createdByProjectMemberId",
"customFields" : [ {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
}, {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 1.4658129805029452,
"id" : "id"
} ],
"yPosition" : 6,
"actualWorkingDays" : [ true, true ],
"plannedWorkingDays" : [ true, true ],
"actualDuration" : 2.5,
"description" : "description",
"type" : "task",
"duration" : 1.5,
"locationId" : "locationId",
"actualStartDate" : "2000-01-23",
"planId" : "planId",
"id" : "id",
"promises" : {
"key" : {
"varianceNote" : "varianceNote",
"promiseDate" : "2000-01-23",
"varianceId" : "varianceId",
"stateDisplay" : "stateDisplay",
"finishDate" : "2000-01-23",
"state" : "state",
"varianceReason" : "varianceReason"
}
},
"actualCrewSize" : 4.5,
"roleId" : "roleId",
"needByDate" : "2000-01-23",
"requestedByMemberId" : "requestedByMemberId",
"assignedToMemberId" : "assignedToMemberId",
"crewSize" : 5.5,
"externalScheduleId" : "externalScheduleId",
"plannedStartDate" : "2000-01-23",
"plannedFinishDate" : "2000-01-23",
"actualFinishDate" : "2000-01-23",
"projectId" : "projectId",
"status" : "COMPLETE"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK TicketResponseModel
Up
post /v1/tickets/{projectId}/customFields
Update ticket custom field values (updateTicketCustomFields)
Tickets from multiple different plans can be updated with a single request. If there are errors found and some of the updates fail validation, the rest will be attempted. Failures will be returned.
Path parameters
projectId (required)
Path Parameter —
Consumes
This API call consumes the following media types via the Content-Type request header:application/json
Request body
body TicketCustomFieldUpdateRequestModel (optional)
Body Parameter —
Return type
Example data
Content-Type: application/json
{
"errors" : [ {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 0.8008281904610115,
"planId" : "planId",
"id" : "id",
"error" : "error",
"ticketId" : "ticketId"
}, {
"listId" : "listId",
"listValue" : "listValue",
"stringValue" : "stringValue",
"name" : "name",
"numericValue" : 0.8008281904610115,
"planId" : "planId",
"id" : "id",
"error" : "error",
"ticketId" : "ticketId"
} ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.application/json
Responses
200
OK TicketCustomFieldUpdateResponseModelModels
[ Jump to Methods ]Table of Contents
AddMemberDto
AddMemberResponseDto
AuthDto
AuthResponseDto
CobblestoneUploadMultipartBody
CustomFieldDefinitionModel
CustomFieldDropDownListItemFieldsModel
CustomFieldListOfValuesModel
ErrorResponseDto
EsidAssociatedTickets
EsidData
EsidTicketUpdate
ExportModel
ExportRequest
ExportResponseModel
LocationModel
MultipartBody
PlanModel
PlanResponseModel
ProjectDetailsModel
ProjectExceptionDayModel
ProjectMemberResponseModel
ProjectMembersModel
ProjectModel
ProjectResponseModel
PromiseModel
RemoveMemberResponseDto
ReportModel
ReportRequest
ReportResponseModel
RoleModel
SwimlaneModel
SwimlaneRequestModel
SwimlaneResponseModel
TickImportMultipartBody
TicketCustomFieldModel
TicketCustomFieldUpdateErrorModel
TicketCustomFieldUpdateModel
TicketCustomFieldUpdateRequestModel
TicketCustomFieldUpdateResponseModel
TicketModel
TicketOverrideAction
TicketPredecessorModel
TicketRequest
TicketResponse
TicketResponseModel
TicketsRequestModel
ValidationError
Variance
VarianceModel
VarianceReason
fullClientDecoratedEsid
AddMemberDto
Up
email
String Email address
example: johnsmith@example.com
primaryRoleId
String Primary role ID
example: -MgMFuq8pCQcJyrhzMvQ
accessLevel
String Access level string; must be 'Basic' or 'Admin' (case insensitive)
example: Admin
secondaryRolesIds (optional)
array[String] Optional array of secondary role ID strings
@type string[]
example: ["-KgMG1V9D_LOM-5Llxyz","-MgMGuYP0jjNY12SEUU1"]
AddMemberResponseDto
Up
userId (optional)
String ID of user of the added member
example: 6ZG0ZfMzwUxEWcESZN1ME7925ff1
projectMemberId (optional)
String ID of the added member
example: -Mz_qJWfPbOSZ9cipJG5
userWasInvited (optional)
Boolean Whether the user was sent email and invited to the project
example: true
userWasAdded (optional)
Boolean Whether the member was added to the project
example: true
AuthResponseDto
Up
token
String A JWT to use to call APIs
CustomFieldDefinitionModel
Up
id
String The custom field definition id
dataType (optional)
String The custom field definition data type
enabled (optional)
Boolean True if the custom field definition is enabled
unit (optional)
String The custom field definition unit
label (optional)
String The custom field definition label
order (optional)
BigDecimal The custom field ordering as shown in the console
type (optional)
String The custom field definition type
Enum:
text
number
dropDownList
link
ticketTypes (optional)
map[String, Boolean] The custom field ticket types
roles (optional)
map[String, Boolean] The custom field definition roles by role id
customFieldListOfValues (optional)
Object The custom field definition's listOfValues definition
CustomFieldDropDownListItemFieldsModel
Up
id
String The list item id
label (optional)
String The user-facing label
enabled (optional)
Boolean True if visible on ticket edit
order (optional)
BigDecimal The order in which the item is shown in the dropdown
CustomFieldListOfValuesModel
Up
id
String The custom field list of values id
dataType
String The custom field definition list of values data type
Enum:
string
number
any
list (optional)
array[CustomFieldDropDownListItemFieldsModel] The custom field list of values drop down list
EsidAssociatedTickets
Up
tickets (optional)
map[String, EsidDisambiguationAction] Dynamic properties representing ticket IDs with associated actions ('update', 'ignore', 'unset').
example: {"ticketId1":{"action":"ignore"},"ticketId2":{"action":"update"},"ticketId3":{"action":"unset"}}
externalScheduleId
String An external schedule ID shared among multiple tickets.
example: ABC123
createNew (optional)
Boolean Flag indicating whether to create a new entry.
example: true
EsidData
Up
externalScheduleId
String The external schedule Id
createNew (optional)
Boolean True if a new ticket should be created
tickets (optional)
map[String, EsidTicketUpdate] A map of esid ticket update actions by ticket Id
ExportModel
Up
completedAt (optional)
Date Date time when the report was completed format: date-time
startedAt (optional)
Date Date time when the report was started format: date-time
errorMessage (optional)
String If the report completed with an error condition
data (optional)
map[String, String] Any associated data files that were processed during the report as downloadable URLs
ExportRequest
Up
exportTicketsFormat (optional)
String Determines the export format. Default is csv.
Enum:
csv
touchplan
planIds (optional)
array[String] The plan Ids to include
roleIds (optional)
array[String] The role Ids to include
locationIds (optional)
array[String] The location Ids to include
swimlaneIds (optional)
array[SwimlaneRequestModel] The swimlane Ids to include as a list of maps of plan [{k=planId, v=swimlaneId}]
asOfDate
date Beginning date range. Required. format: date
upToDate
date Ending date range. Required. format: date
includePullTickets (optional)
Boolean True if pull tickets should be included
externalLinkage (optional)
String Determines if the export shall include tickets which contain External Schedule Ids. Default is all ('any') tickets.
Enum:
any
linked
unlinked
ExportResponseModel
Up
exports (optional)
array[ExportModel] A list of exports
MultipartBody
Up
file (optional)
Object file data format: binary
PlanModel
Up
id (optional)
String The plan Id. Will be ignored in the case of a plan create, update.
name (optional)
String The plan name. Required for a plan create.
projectId (optional)
String The plan's project id.
startDate (optional)
date The plan start date. format: date
finishDate (optional)
date The plan finish date. format: date
milestoneDate (optional)
date The plan milestone date format: date
milestoneName (optional)
String The plan milestone name. Will be ignored in the case of a plan update.
activeLineDate (optional)
date The plan active line date format: date
currentPromisePeriodStartDate (optional)
date The plan promise period start date. Will be ignored in the case of a plan update. format: date
PlanResponseModel
Up
plans (optional)
array[PlanModel] A list of plans
ProjectDetailsModel
Up
id
String The project id
name (optional)
String The project name
createdDate (optional)
date Date when the project was created format: date
scheduleDateRange (optional)
array[String] Schedule date range as an array of dates in yyyy-MM-dd format. The first value is the earliest planned start date among all plans. The second value is the latest planned finish date or latest actual finish date among all the plans.
example: [2020-01-01, 2020-02-15]
owner (optional)
String The project owner
url (optional)
String The project url
type (optional)
String The project type
status (optional)
String The project status
Enum:
active
archived
address (optional)
String The project address
city (optional)
String The project city
territory (optional)
String The project territory
postcode (optional)
String The project postcode
country (optional)
String The project country
timezone (optional)
String The project timezone
marketSector (optional)
String The project market sector
locations (optional)
array[LocationModel] The project locations
roles (optional)
array[RoleModel] The project roles
schedule (optional)
array[Integer] The project work schedule by day of week using ISO 8601 ie. Monday(0), Sunday(6). format: int32
example: [1.0,1.0,1.0,1.0,1.0,0.0,0.0]
exceptionDays (optional)
array[ProjectExceptionDayModel] The project exception days
variances (optional)
array[VarianceModel] The project variances
customFieldDefinitions (optional)
array[CustomFieldDefinitionModel] The project custom field definitions
ProjectMemberResponseModel
Up
projectMembers (optional)
array[ProjectMembersModel] A list of members of a project
ProjectMembersModel
Up
projectId
String Id of the project the member is in
memberId
String Id of the member in the project
userId
String The user's id
emailAddress (optional)
String Email address of the member
isAdmin (optional)
Boolean Whether the member is an admin on the project or not
primaryRoleId (optional)
String Id of the role the member is assigned
secondaryRoleIds (optional)
array[String] Secondary roles of the member
ProjectModel
Up
id
String The project id
name (optional)
String The project name
createdDate (optional)
date Date when the project was created format: date
scheduleDateRange (optional)
array[String] Schedule date range as an array of dates in yyyy-MM-dd format. The first value is the earliest planned start date among all plans. The second value is the latest planned finish date or latest actual finish date among all the plans.
example: [2020-01-01, 2020-02-15]
owner (optional)
String The project owner
url (optional)
String The project url
type (optional)
String The project type
status (optional)
String The project status
Enum:
active
archived
ProjectResponseModel
Up
projects (optional)
array[ProjectModel] A list of projects
PromiseModel
Up
promiseDate (optional)
date Date the ticket was promised to finish format: date
finishDate (optional)
date Date the ticket was finished format: date
varianceId (optional)
String The promise variance Id
varianceReason (optional)
String The promise variance reason
varianceNote (optional)
String The promise variance note
state (optional)
String The promise state
stateDisplay (optional)
String The promise state display string
ReportModel
Up
completedAt (optional)
Date Date time when the report was completed format: date-time
startedAt (optional)
Date Date time when the report was started format: date-time
errorMessage (optional)
String If the report completed with an error condition
data (optional)
map[String, String] Any associated data files that were processed during the report as downloadable URLs
ReportRequest
Up
reportName
String The report name. Each report available corresponds to a report in the Touchplan application.<br>ppcChartsByWeek='PPC by Week'<br>ppcChartsByTradeToDate='PPC by Role'<br>ppcChartsByVarianceReason='PPC by Variance Reason'<br>ppcVarianceByRole='Variance by Role'<br>ppcVarianceByWeek='Variance by Week'<br>varianceReview='Advanced Variance Reason'<br>The option to break up the report by role is not supported.<br>
Enum:
ppcChartsByWeek
ppcChartsByTradeToDate
ppcChartsByVarianceReason
ppcVarianceByRole
ppcVarianceByWeek
varianceReview
planIds (optional)
array[String] The plan Ids
roleIds (optional)
array[String] The role Ids
locationIds (optional)
array[String] The location Ids
includeNoLocation (optional)
Boolean Indicates if reported tickets (constraints) should include those which lack an association to any location
swimlaneIds (optional)
array[SwimlaneRequestModel] The swimlane Ids
includeNoSwimlane (optional)
Boolean Indicates if reported tickets (constraints) should include those which lack an association to any swimlane
customFieldFilters (optional)
array[String] Custom field filter descriptors
asOfDate (optional)
date Beginning date range, defaults to earliest active date format: date
upToDate (optional)
date Ending date range, defaults to latest active date format: date
includeCompleted (optional)
Boolean Indicates if tickets which have been completed are included in reports
groupByLocation (optional)
Boolean Indicates if tickets should be grouped and aggregated by location
orderLocationByName (optional)
Boolean Orders by location name if true, orders by start date if false
ReportResponseModel
Up
reports (optional)
array[ReportModel] A list of reports
RoleModel
Up
id
String The role id
name (optional)
String The role name
color (optional)
String The role color as a hex value
schedule (optional)
array[Integer] The role schedule by day of week using ISO 8601 ie. Monday(0), Sunday(6). format: int32
example: [1.0,1.0,1.0,1.0,1.0,0.0,0.0]
SwimlaneModel
Up
id
String The swimlane Id
planId
String ID for the plan the swimlane is in
name
String The swimlane name
color (optional)
String Swimlane color hex code
upperY (optional)
Integer Y coordinate of the top of the swimlane in the plan view format: int32
lowerY (optional)
Integer Y coordinate of the bottom of the swimlane in the plan view format: int32
SwimlaneResponseModel
Up
swimlanes (optional)
array[SwimlaneModel] A list of swimlanes
TicketCustomFieldModel
Up
id
String The custom field Id.
name (optional)
String The custom field name. Not used for ticket custom field updates.
stringValue (optional)
String Value for the custom field if it's of type string. Must be specified for non-drop-down lists of type string during ticket custom field updates.
numericValue (optional)
BigDecimal Value for the custom field if it's of type numeric. Must be specified for non-drop-down lists of type numeric during ticket custom field updates.
listId (optional)
String The custom field drop-down Id. Must be specified for drop-down lists during ticket custom field updates as one of the available options. Use getTicketDetails to discover available LOV Ids.
listValue (optional)
String Value for the custom field if it's a drop-down. Not used for ticket custom field updates.
TicketCustomFieldUpdateErrorModel
Up
id
String The custom field Id.
name (optional)
String The custom field name. Not used for ticket custom field updates.
stringValue (optional)
String Value for the custom field if it's of type string. Must be specified for non-drop-down lists of type string during ticket custom field updates.
numericValue (optional)
BigDecimal Value for the custom field if it's of type numeric. Must be specified for non-drop-down lists of type numeric during ticket custom field updates.
listId (optional)
String The custom field drop-down Id. Must be specified for drop-down lists during ticket custom field updates as one of the available options. Use getTicketDetails to discover available LOV Ids.
listValue (optional)
String Value for the custom field if it's a drop-down. Not used for ticket custom field updates.
planId
String The plan id
ticketId
String The ticket id
error
String An error message that occurred when updating this custom field value
TicketCustomFieldUpdateModel
Up
id
String The custom field Id.
name (optional)
String The custom field name. Not used for ticket custom field updates.
stringValue (optional)
String Value for the custom field if it's of type string. Must be specified for non-drop-down lists of type string during ticket custom field updates.
numericValue (optional)
BigDecimal Value for the custom field if it's of type numeric. Must be specified for non-drop-down lists of type numeric during ticket custom field updates.
listId (optional)
String The custom field drop-down Id. Must be specified for drop-down lists during ticket custom field updates as one of the available options. Use getTicketDetails to discover available LOV Ids.
listValue (optional)
String Value for the custom field if it's a drop-down. Not used for ticket custom field updates.
planId
String The plan id
ticketId
String The ticket id
TicketCustomFieldUpdateRequestModel
Up
updates
array[TicketCustomFieldUpdateModel] Ticket custom field values
TicketCustomFieldUpdateResponseModel
Up
errors (optional)
array[TicketCustomFieldUpdateErrorModel] A list of ticket custom field update error models
TicketModel
Up
id
String The ticket Id
description (optional)
String The ticket description
planId (optional)
String The ticket plan id
projectId (optional)
String The ticket project id
type
String The ticket type
Enum:
task
milestone
constraint
plannedStartDate (optional)
date The ticket planned start date format: date
plannedFinishDate (optional)
date The ticket planned finish date format: date
roleId (optional)
String The ticket role Id. Not returned for constraints.
locationId (optional)
String The ticket location Id
duration (optional)
BigDecimal The ticket planned duration in days
example: 1.5
crewSize (optional)
BigDecimal The ticket planned crew size
example: 5.5
createdByProjectMemberId (optional)
String The ticket creator member Id
createdAtDate (optional)
date The ticket created date format: date
actualFinishDate (optional)
date The ticket actual finish date format: date
actualDuration (optional)
BigDecimal The ticket actual duration in days
example: 2.5
predecessors (optional)
array[TicketPredecessorModel] List of ticket predecessors
promises (optional)
map[String, PromiseModel] Map of PromiseModel objects by Id
yPosition (optional)
Integer The ticket y position format: int32
customFields (optional)
array[TicketCustomFieldModel] List of values of custom fields on the ticket
actualWorkingDays (optional)
array[Boolean] List of [true|false] for which days between actual start and finish count toward durationDays, accounting for all the exception days and work weeks.
plannedWorkingDays (optional)
array[Boolean] List of [true|false] for which days between planned start and finish count toward durationDays, accounting for all the exception days and work weeks.
actualStartDate (optional)
date The ticket actual start date format: date
actualCrewSize (optional)
BigDecimal The ticket actual crew size
example: 4.5
externalScheduleId (optional)
String The ticket external schedule Id
requestedByMemberId (optional)
String The ticket 'requested by member' Id
assignedToMemberId (optional)
String The ticket 'assigned to member' Id
needByDate (optional)
date The ticket 'need by' date format: date
status (optional)
String The ticket status
Enum:
COMPLETE
ASSIGNED
ACCEPTED
UNASSIGNED
INVALID
TicketPredecessorModel
Up
planId
String The predecessor Plan Id
ticketId
String The predecessor Ticket Id
isCyclic
Boolean Indicates if the given precedence relation participates in a graph theoretic precedence cycle
isOutOfOrder
Boolean Indicates if the successor and predecessor fail to satisfy the precedence relationship described by linkageType and lagDays
linkageType (optional)
String The dependency type: 'Finish to Start', 'Start to Start', 'Finish to Finish', Start to Finish'
Enum:
FS
SS
FF
SF
lagDays (optional)
Integer Lag in calendar days between predecessor and successor. Negative lag indicates lead format: int32
cyclic (optional)
outOfOrder (optional)
TicketRequest
Up
type (optional)
String Type of ticket. Can be "task", "milestone" or "constraint"
description (optional)
String Ticket description
locationName (optional)
String Location name
roleName (optional)
String Role name
duration (optional)
String Duration in days
crewSize (optional)
String Crew size
plannedStartDate (optional)
String Planned start date
plannedFinishDate (optional)
String Planned finish date
actualStartDate (optional)
String Actual start date
actualFinishDate (optional)
String Actual finish date
needByDate (optional)
String Date requested
requestedByMemberEmail (optional)
String Email address of the project member that requested this ticket
assignedToMemberEmail (optional)
String Email address of project member that is assigned to this ticket
ticketPosition (optional)
String Location of the ticket, which should either be "active" or "pull"
externalScheduleId (optional)
String External schedule id
customFields
Object Custom fields values keyed by the custom field name, and the value we want to set
TicketResponse
Up
type (optional)
String Type of ticket. Can be "task", "milestone" or "constraint"
description (optional)
String Ticket description
locationName (optional)
String Location name
roleName (optional)
String Role name
duration (optional)
String Duration in days
crewSize (optional)
String Crew size
plannedStartDate (optional)
String Planned start date
plannedFinishDate (optional)
String Planned finish date
actualStartDate (optional)
String Actual start date
actualFinishDate (optional)
String Actual finish date
needByDate (optional)
String Date requested
requestedByMemberEmail (optional)
String Email address of the project member that requested this ticket
assignedToMemberEmail (optional)
String Email address of project member that is assigned to this ticket
ticketPosition (optional)
String Location of the ticket, which should either be "active" or "pull"
externalScheduleId (optional)
String External schedule id
customFields
Object Custom fields values keyed by the custom field name, and the value we want to set
errors
TicketResponseModel
Up
tickets (optional)
array[TicketModel] A list of tickets
TicketsRequestModel
Up
ticketIds (optional)
array[String] Ticket ids to filter on
fullClientDecoratedEsid
Up
externalScheduleId
String An external schedule ID shared among multiple tickets.
example: ABC123
ticketIds (optional)
example: ["ticketId1","ticketId2"]