Workflow Resources

Manage workflow transitions for a Request.

Move an existing Request in the approval workflow

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

The HATEOAS links for actions available given the current user and state are listed in the operations of the Request resource.

Traveler actions

  • submit: initiate the approval workflow.
  • recall: get back the Request, usually to modify the content.
  • cancel: cancel the Request and attached itineraries.
  • close: archive the Request.
  • reopen: get back an archived Request.

Non traveler actions (Approver / Processor / External Validation / TMC Agent)

  • approve: move the Request to the next approval step.
  • sendback: reject the Request and send back to the traveler.
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/{action}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
action string - Required The state transition to be executed. Supported values: submit, approve, recall, sendback, cancel, close, or reopen
comment string - Only works with when the workflow action is sendback. This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.
userId string - The unique identifier of the user performing the status transition. Required when connecting with a Company token for traveler actions only. If empty, a 400 missingRequiredParam error code will be displayed. For non traveler actions, if not provided, “System, Concur” will be displayed in the Audit Trail of the Request.
companyID string - The unique identifier of the company.

Payload

None, except when the workflow action is sendback where an optional comment may be submitted

{ "comment" : "My Comment" }

This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.

HTTP Response

HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "approvalStatus": {
    "code": "SUBMITTED",
    "name": "Submitted & Pending Approval"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "canceledPostApproval": false,
  "closed": false,
  "creationDate": "2018-05-25T09:17:25.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "everSentBack": false,
  "expenses": [
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/47C8AD9E382B5143BB54DC3090577C60",
      "id": "47C8AD9E382B5143BB54DC3090577C60",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    }
  ],
  "lastModified": "2018-05-25T09:38:02.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": true,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333X",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "submitDate": "2018-05-25T09:38:02.000Z",
  "totalApprovedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "operations": [
    {
      "rel": "recall",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/recall"
    },
    {
      "rel": "cancel",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/cancel"
    }
  ]
}