Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.

If a new or existing project please use version 3.0 of this API.

HTTP Status Codes

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

Request Resources

Create a new Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
userId path string The unique identifier of the Request owner for whom the Request will be created.
The corresponding user name will be displayed in the audit trail of the Request
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
POST /v4/requests

Payload

Request

HTTP Response

Payload

Request - The created Request

Example

Example

Additional information

Since this endpoint is performing a Request creation, specifying an “id” field in the payload is not allowed.
A newly allocated “id” value will be returned upon successful Request creation

Get the list of existing Requests

HTTP Request

Parameters

Name Parameter Type Data Type Description
view path string Name of the perimeter defining the requests to get.
Possible values: ALL, ACTIVE, UNSUBMITTED, PENDING, VALIDATED, APPROVED, CANCELED, CLOSED, SUBMITTED, TOAPPROVE, PENDINGEBOOKING. When connecting with a User Token, additional values are possible: PENDINGPROPOSAL, PROPOSALAPPROVED, PROPOSALCANCELED.
If no view value is sent, the default view ALL will be used
userId path string The unique identifier of the Request owner to use when searching for Requests
start path Integer Pagination: index of the first record (default 0)
limit path Integer Number of records to return per page (default 10) - maximum limit is 100, if higher value or digit value is set, a 400 error code will be displayed
modifiedBefore path DateTime This returns Requests in which the associated dependents (Header, Expected Expenses, Segments, Allocations, Attendees, Comments) were modified before the specified date and time.
This search term can be used along with other search terms to narrow the results.
The date and time (if desired) should be in UTC.
Both ISO format (yyyy-MM-dd’T’HH:mm:ss.SSS’Z’) and yyyy-MM-dd format are accepted, when time is missing it is defaulted to midnight.
modifiedAfter path DateTime This returns Requests in which the associated dependents (Header, Expected Expenses, Segments, Allocations, Attendees, Comments) were modified after the specified date and time.
This search term can be used along with other search terms to narrow the results.
The date and time (if desired) should be in UTC.
Both ISO format (yyyy-MM-dd’T’HH:mm:ss.SSS’Z’) and yyyy-MM-dd format are accepted, when time is missing it is defaulted to midnight.
sortField path string The name of the field on which to sort.
Possible values: startDate, approvalStatus, requestId.
If no view value is sent, the default sortField startDate will be used
sortOrder path string Sort order.
Possible values: ASC, DESC.
If no view value is sent, the default sortOrder DESC will be used
URI Template
GET /v4/requests

Payload

None

HTTP Response

Payload

List of Request

Example

Example

Get the content of an existing Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
URI Template
GET /v4/requests/{requestUuid}

Payload

None

HTTP Response

Payload

Request - The Request having {requestUuid} as unique identifier

Example

Example

Update the content of an existing Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
userId path string The unique identifier of the user performing the update.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
PUT /v4/requests/{requestUuid}

Payload

Request

HTTP Response

Payload

Request - The Request having {requestUuid} as unique identifier after update

Example

Example

Additional information

Update of the following fields is supported : policy, comment, startDate, startTime, endDate, endTime, expensePolicy, name, businessPurpose, mainDestination, travelAgency, custom fields. Other fields will be ignored.
This endpoint supports partial update. You may submit only the fields to update in the body, fields not present in the body will remain unchanged.
To clear a field use the value null (without quotes)
“id” field is not mandatory in the payload, if provided the value must match the requestUuid parameter.

Delete an existing Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
userId path string The unique identifier of the user performing the deletion.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
DELETE /v4/requests/{requestUuid}

Payload

None

HTTP Response

Payload

None

Example

Example

Create an Expense Report linked to an approved Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
URI Template
POST /v4/requests/{requestUuid}/reports

Payload

None

HTTP Response

Payload

ResourceLink - The resource link leading to the created report

Example

Example

Workflow Resources

Manage workflow transitions for a Request document.

Move an existing Request in the approval workflow

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
action path string Required The state transition to be executed (submit, approve, recall, sendback, cancel, close or reopen)
comment path 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 path string The unique identifier of the user performing the status transition.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
companyID path string The unique identifier of the company

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
  • Approver / Processor actions
    • approve: move the Request to the next approval step
    • sendback: reject the Request and send back to the Traveler
URI Template
POST /v4/requests/{requestUuid}/{action}

Payload

None

HTTP Response

Payload

Request - The Request having {requestUuid} as unique identifier

Example

Example

Expense Resources

Manage expected expense entries attached to a Request document.

Create a new expected expense

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request to which the Expense is attached
userId path string The unique identifier of the user performing the expense creation.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
POST /v4/requests/{requestUuid}/expenses

Payload

Expense

HTTP Response

Payload

None

Example

Example

Get expected Expenses attached to a Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
requestUuid path string Required The unique identifier of the Request
userId path string The unique identifier of the user viewing the expected expenses attached to a Request.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
GET /v4/requests/{requestUuid}/expenses

Payload

None

HTTP Response

Payload

Expense - List of entries attached to a Request.

operations - RFC 5988 Pagination links to next/prev/first/last page.

Example

Example

Get an existing expected Expense

HTTP Request

Parameters

Name Parameter Type Data Type Description
expenseUuid path string Required The unique identifier of the Expense
userId path string The unique identifier of the user viewing the expected expense.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
GET /v4/expenses/{expenseUuid}

Payload

None

HTTP Response

Payload

Expense - The Expense having {expenseUuid} as unique identifier

Example

Example

Update the content of an existing expected Expense

HTTP Request

Parameters

Name Parameter Type Data Type Description
expenseUuid path string Required The unique identifier of the Expense to update
userId path string The unique identifier of the user performing the expense update.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
PUT /v4/expenses/{expenseUuid}

Payload

Expense

HTTP Response

Payload

Expense - The Expense having {expenseUuid} as unique identifier after update

Example

Example

Delete an expected Expense from the Request

HTTP Request

Parameters

Name Parameter Type Data Type Description
expenseUuid path string Required The unique identifier of the Expense to delete
userId path string The unique identifier of the user performing the deletion of the expense.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed
URI Template
DELETE /v4/expenses/{expenseUuid}

Payload

None

HTTP Response

Payload

None

Example

Example

Request Policy Resources

Get the list of existing Request policies for a given user

HTTP Request

Parameters

Name Parameter Type Data Type Description
userId path string The unique identifier of the user for whom the list of Request policies will be retrieved.
Required when connecting with a Company token, if empty a 400 missingRequiredParam error
URI Template
GET /v4/userpolicies

Payload

None

HTTP Response

Payload

Name Type Format Description
href string RFC 3986 Hyperlink to the resource for this Request policy
id string - The Request policy unique identifier
name string - The name of the Request policy

Example

Example

Travel Agency Resources

Manage the configuration for travel agencies integrated with Concur Request.

Get the description of a travel agency office

HTTP Request

Parameters

Name Parameter Type Data Type Description
agencyUuid path string Required The unique identifier of the Travel Agency
URI Template
GET /v4/travelagencies/{agencyUuid}

Payload

None

HTTP Response

Payload

Name Type Format Description
emailAddress string - The travel agency email address
id string - The travel agency unique identifier
name string - The travel agency office name
proposalType string - The travel agency proposal type. Possible value: CWT, CWTF, AEBT or API

Example

Example

Schema

Request

Name Type Format Description
approvalLimitDate timestamp RFC 3339 The date by which the Request must be approved. This element appears only when integrated with Concur Travel (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
approvalStatus object Approval Status The approval status of the Request
approved boolean - Indicates whether this Request is approved
authorizedDate timestamp RFC 3339 For approved Request, the date at which the approval process was completed (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
businessPurpose string - The business purpose of the Request
canceledPostApproval boolean - Indicates whether this Request was canceled post approval
closed boolean - Indicates whether this Request is closed
comment string - The last comment attached to this Request
creationDate timestamp RFC 3339 The date when the Request was created (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
custom1 to custom20 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration
endDate date ISO 8601 The end date of the Request (in the format yyyy-MM-dd)
endTime time ISO 8601 The end time of the Request (in the format HH:mm)
everSentBack boolean - Indicates whether the Request has ever been sent back to the employee
expenses array ResourceLink Expected Expenses attached to this Request
extensionOf object RequestLink The Request that this Request is an extension of, or addendum to
href string RFC 3986 Hyperlink to the resource for this Request
id string - The unique identifier of the Request
lastModified timestamp RFC 3339 The date the Request was last modified (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
mainDestination object Location The main destination of the Request
name string - The name of the Request
owner object Employee The employee who owns the Request
pendingApproval boolean - Indicates whether this Request is pending approval
policy object ResourceLink The policy that applies to the Request
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer)
startDate date ISO 8601 The start date of the Request (in the format yyyy-MM-dd)
startTime time ISO 8601 The start time of the Request (in the format HH:mm)
submitDate timestamp RFC 3339 The date the Request was submitted (last submit date in case of recall) (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
totalApprovedAmount object Amount The total amount of approved Expenses in the Request, expressed in the reimbursement currency of the employee at the time he created the Request
totalPostedAmount object Amount The total amount of the Request, expressed in the reimbursement currency of the employee at the time he created the Request
totalRemainingAmount object Amount The total amount not included in an Expense report, expressed in the reimbursement currency of the employee at the time he created the Request
travelAgency object ResourceLink The travel agency office that is managing the trip associated to this Request
operations array Link Links to operations available for the Request, depends on the current approval status
type object RequestType The type of the Request, inherited from the Request Policy Type

Amount

Name Type Format Description
value number - Required The amount in the defined currency
currency string ISO 4217:2015 Required The 3-letter ISO 4217 code of the currency in which the amount is expressed

Approval Status

Name Type Format Description
code string - The code of the approval status of the Request.
Possible values: NOT_SUBMITTED, SUBMITTED, APPROVED, CANCELED or SENTBACK
name string - The approval status of the Request in the current user’s language

CustomField

Name Type Format Description
code string - The short code of the list item. For non-list fields, this value will be blank
value string - The value of the non-list item. For list fields, this is the unique id of the item
listItemId string - The unique id of the item in case of a list field
href string - The link to get this list item on the list service. Empty for non-list items

Employee

Name Type Format Description
firstName string - The first name of the employee
href string RFC 3986 Hyperlink to the resource
id string RFC 4122 Unique identifier of the related object
lastName string - The last name of the employee
middleInitial string - The middle initial of the employee
template string - Hyperlink template to the resource
Name Type Format Description
rel string RFC 5988 Relation type as defined by the server. There are registered relation types listed in RFC 5988 6.2.2. Initial Registry Contents including pagination relation types of next, prev, first and last
href string RFC 3986 Hyperlink to the resource

List of Request

Name Type Format Description
data array Request List of Requests in the page requested
operations array Link Links to next, prev, first and last pages

Location

Name Type Format Description
countryCode string ISO 3166-1 The ISO 3166-1 country code
countrySubDivisionCode string ISO 3166-2 The ISO 3166-2 country sub code
city string - The city name of the location
iataCode string - The IATA code of the location
name string - The name of the location
Name Type Format Description
href string RFC 3986 Hyperlink to the resource
id string RFC 4122 Unique identifier of the related object
template string - Hyperlink template to the resource
Name Type Format Description
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer)

Request Type

Name Type Format Description
code string - The code of the type inherited from the Request Policy type
label string - The label of the type inherited from the Request Policy Type

Expense

Name Type Format Description
allocations object Allocation The details of the allocations for this Expense.
approvedAmount object Amount The approved amount of the Expense entry, in the transaction currency of the Request
budgetAccrualDate timestamp RFC 3339 The date to determine which budgets are affected (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
businessPurpose string - The business purpose of the Request entry
custom1 to custom40 object CustomField The details from the Custom fields.
These fields may not have data, depending on the configuration
exchangeRate object Exchange Rate The exchange rate that applies to the entry
expenseType object Expense Type The Expense type of the entry.
Required for expected Expenses, automatically set for segments depending on the SegmentType code.
href string RFC 3986 Hyperlink to the resource for this Request entry
id string - The unique identifier of the Expense entry
lastComment string - The last comment (most recent) of the Expense entry
lastModifiedDate timestamp RFC 3339 The date when this Expense was last modified
location object Location The location of the Expense entry
orgUnit1 to orgUnit6 object Amount The details from the Custom fields.
These fields may not have data, depending on the configuration
postedAmount object Amount The posted amount of the Expense entry, in the transaction currency of the Request
remainingAmount object Amount The remaining amount of the Expense entry, in the transaction currency of the Request
source enum - The source that created the expense. It can be CASH_ADVANCE or TRAVEL_ALLOWANCE.
This field will be empty in any other case
transactionAmount object Amount Required The amount of the Expense entry, in the transaction currency paid to the vendor
transactionDate timestamp RFC 3339 Required The date of the transaction (in the format yyyy-MM-dd’T’HH:mm:ss.SSS’Z’)
travelAllowance object Travel Allowance The Travel allowance
tripData object Trip Data The description of the trip
vendor object Vendor The vendor of the Expense entry

Allocation

Name Type Format Description
allocationAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the transaction amount on the Expense. This amount is given in the transaction’s currency and rounded to 8 decimals after decimal point.
approvedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the approved amount on the Expense. This amount is given in the user’s currency and rounded to 8 decimals after decimal point.
allocationId string - The unique allocation identifier
custom1 to custom20 object CustomField The details from the Custom fields.
These fields may not have data, depending on the configuration
expenseId string - The unique identifier of the Expense associated with the allocation
percentEdited boolean - Whether the allocation percent has been edited
percentage number - The percentage of the total Expense that this allocation represents
postedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the posted amount on the Expense. This amount is given in the user’s currency and rounded to 8 decimals after decimal point.
systemAllocation boolean - Whether the allocation is a system allocation. It is usually hidden or read only for Request users

Exchange Rate

Name Type Format Description
operation string - Exchange rate operation. Possible values are: MULTIPLY or DIVIDE
value number - Exchange rate value

Expense Type

Name Type Format Description
id string - Required Unique identifier of the Expense type
name string - Name of the Expense type
href string RFC 3986 Hyperlink to the resource for the Expense type definition

List Item Field

Name Type Format Description
code string - The short code of the list item
value string - Name of the list item
href string RFC 3986 Hyperlink to the resource for the list item

Segment Leg

Name Type Format Description
class list List Item Field The booking class of the segment leg.
classOfService string - The class of service of the segment leg. For example, in the case of an air segment, this field would contain the one-letter booking code: Y for economy class, or F for first class…
comment string - Contains the last comment saved in this segment leg.
custom1 to custom40 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration
endDate date ISO 8601 The date of the end of this segment leg (in the form YYYY-MM-DD). It represents the arrival date of AIRFR and TRAIN segments, check out date for HOTEL or drop off for CARRT
endLocation object ResourceLink The location where this segment leg arrives. This would be the arrival location for an air segment for example.
endLocationDetail string - Details about the end location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
endTime time ISO 8601 The time for the end of this segment leg (in the form HH:MM)
id string - The unique identifier of the segment leg
returnLeg boolean - Indicates whether this leg is the return leg of a round trip. In case of a ROUND_TRIP, if not explicitly set, the second segment leg will be considered as the return leg.
startDate date ISO 8601 The date of the beginning of this segment leg (in the form YYYY-MM-DD)
startLocation object ResourceLink The start location of this segment leg. This would be the departure location for an air segment for example.
startLocationDetail string - Details about the start location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
startTime time ISO 8601 The time for the beginning of this segment leg (in the form HH:MM)
segmentLocator string - This is the identifier for ConcurTravel segments (if applicable)
vendorName string - Contains the vendor description of the segment leg.

Segment Type

Name Type Format Description
category enum - Describes the category of this segment type. Possible values are: REQ_SEG_AIRFR, REQ_SEG_CARRT, REQ_SEG_HOTEL, REQ_SEG_LIMOF, REQ_SEG_RAILF, REQ_SEG_TAXIF, REQ_SEG_MISC, REQ_SEG_PARKG, REQ_SEG_DININ, REQ_SEG_EVENT
code string - Required The code of the segment type. Possible values are: AIRFR, CARRT, HOTEL, LIMOF, RAILF, TAXIF, MISC, PARKG, DININ, EVENT or custom codes

It can be REQ_SEG_AIRFR / AIRFR for a regular air segment, or REQ_SEG_AIRFR / 10325 for a custom air segment.

Example:

{
  "category": "REQ_SEG_AIRFR",
  "code": "AIRFR"
}

Travel Allowance

Name Type Format Description
dailyTravelAllowanceId string - The fixed daily travel allowance id associated with the Expense

Trip Data

Name Type Format Description
agencyBooked boolean - True if this travel is (or has to be) handled by a travel agency
legs list Segment Leg The list of the legs of the travel
tripType string - Indicates the type of this trip. Should be one of ONE_WAY, ROUND_TRIP or MULTI_STOPS. If not provided, will be detected from the given legs.
segmentType object Segment Type Required The type of the segment
selfBooked boolean - True if this travel has been reserved by Concur Travel, or if Concur Travel has retrieved the trip information in the GDS

Vendor

Name Type Format Description
id string - The vendor identifier of the entry
name string - The vendor description of the entry