Travel Request v4 - Workflow Resources

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 / TMC Agent)

  • approve: move the Request to the next approval step.
  • sendback: reject the Request and send back to the traveler.

External System Validation

  • approve: move the Request to the next approval step.
  • sendback: reject the Request and send back to the traveler.

Required Scope: travelrequest.externalsystemworkflow.write - Refer to Scope Usage for full details.

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 and Non traveler actions only, Not required from External system validation actions. 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.

Headers

concur-correlationid is a specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.

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}
Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f

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"
    }
  ]
}

On this page