Touchplan API

Touchplan API

Information on the use of Touchplan API endpoints.
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) 2023 MOCA Systems, Inc. All rights reserved.

Access

Methods

[ Jump to Models ]

Table of Contents

Auth

GenerateCustomToken

Plans

Projects

Swimlanes

Tickets

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

AuthResponseDto

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

AuthResponseDto

401

Authentication failed. Client ID or client secret is incorrect. ErrorResponseDto

default

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

AuthResponseDto

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

AuthResponseDto

default

An object containing just one field 'token' which is the custom token generated for the given user. AuthResponseDto

GenerateCustomToken

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

AuthResponseDto

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

AuthResponseDto

default

An object containing just one field 'token' which is the custom token generated for the given user. AuthResponseDto

Plans

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

PlanModel

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

PlanResponseModel

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

PlanModel

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

Projects

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

AddMemberResponseDto

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

AddMemberResponseDto

400

Invalid parameter value ErrorResponseDto

default

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

ProjectDetailsModel

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

ProjectMemberResponseModel

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

ProjectResponseModel

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

RemoveMemberResponseDto

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

RemoveMemberResponseDto

default

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

ExportResponseModel

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

ReportResponseModel

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 ReportResponseModel

Swimlanes

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

SwimlaneResponseModel

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 SwimlaneResponseModel

Tickets

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

TicketResponseModel

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

TicketResponseModel

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

TicketCustomFieldUpdateResponseModel

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 TicketCustomFieldUpdateResponseModel

Models

[ Jump to Methods ]

Table of Contents

  1. AddMemberDto
  2. AddMemberResponseDto
  3. AuthDto
  4. AuthResponseDto
  5. CustomFieldDefinitionModel
  6. CustomFieldDropDownListItemFieldsModel
  7. CustomFieldListOfValuesModel
  8. ErrorResponseDto
  9. EsidData
  10. ExportModel
  11. ExportRequest
  12. ExportResponseModel
  13. LocationModel
  14. MultipartBody
  15. PlanModel
  16. PlanResponseModel
  17. ProjectDetailsModel
  18. ProjectExceptionDayModel
  19. ProjectMemberResponseModel
  20. ProjectMembersModel
  21. ProjectModel
  22. ProjectResponseModel
  23. PromiseModel
  24. RemoveMemberResponseDto
  25. ReportModel
  26. ReportRequest
  27. ReportResponseModel
  28. RoleModel
  29. SwimlaneModel
  30. SwimlaneRequestModel
  31. SwimlaneResponseModel
  32. TickImportMultipartBody
  33. TicketCustomFieldModel
  34. TicketCustomFieldUpdateErrorModel
  35. TicketCustomFieldUpdateModel
  36. TicketCustomFieldUpdateRequestModel
  37. TicketCustomFieldUpdateResponseModel
  38. TicketModel
  39. TicketPredecessorModel
  40. TicketRequest
  41. TicketResponse
  42. TicketResponseModel
  43. TicketsRequestModel
  44. ValidationError
  45. VarianceModel

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

AuthDto Up

clientId
String Client ID
example: z7CaxzRXmjSzAw897JMWqrZKhKZ2
clientSecret
String Client secret
example: some-client-secret
tenantId (optional)
String Tenant id
example: my-custom-tenant-hhjj

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

ErrorResponseDto Up

errorDescription
String
example: Invalid username and/or password

EsidData Up

externalScheduleId
String An external schedule Id
ticketIds
array[String] An array of ticket Ids that contain this same external schedule 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

LocationModel Up

id
String The location id
name (optional)
String The location name
color (optional)
String The locations hex color code

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

ProjectExceptionDayModel Up

date (optional)
date The exception date format: date
description (optional)
String The exception date description

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

RemoveMemberResponseDto Up

status
String Result status
example: success
message
String Result status message
example: Successfully removed user from project

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>Only PPC reports are currently available, the option to break up the report by role is not supported.
Enum:
ppcChartsByWeek
ppcChartsByTradeToDate
ppcChartsByVarianceReason
ppcVarianceByRole
ppcVarianceByWeek
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
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

SwimlaneRequestModel Up

id
String The swimlane Id
planId
String ID for the plan the swimlane is in

SwimlaneResponseModel Up

swimlanes (optional)
array[SwimlaneModel] A list of swimlanes

TickImportMultipartBody Up

file (optional)
Object file data format: binary
planName (optional)
String plan name format: string

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)
Boolean
outOfOrder (optional)
Boolean

TicketRequest Up

type (optional)
String Type of ticket. Can be &quot;task&quot;, &quot;milestone&quot; or &quot;constraint&quot;
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 &quot;active&quot; or &quot;pull&quot;
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 &quot;task&quot;, &quot;milestone&quot; or &quot;constraint&quot;
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 &quot;active&quot; or &quot;pull&quot;
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
array[array[ValidationError]]

TicketResponseModel Up

tickets (optional)
array[TicketModel] A list of tickets

TicketsRequestModel Up

ticketIds (optional)
array[String] Ticket ids to filter on

ValidationError Up

errorMessage
String
fieldName
String

VarianceModel Up

id
String The variance id
reason (optional)
String The variance reason
color (optional)
String The variance color in hex
key (optional)
Integer The variance key used for ordering format: int32