Reports v4

The Reports v4 API can be used to read and modify an expense report header of an existing expense report. This API can be used to change attributes like report name, business purpose, etc.

Prior Versions

  • Report Header v1 (Deprecated) documentation is available here
  • Reports v3 documentation is available here

Limitations

Access to this documentation does not provide access to the API.

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH, POST
expense.report.workflowstatus.write Approve or Send Back the Report in the workflow PATCH
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve a Report by ID

Retrieves the details of the specific report header.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, MANAGER, PROCESSOR, PROXY
reportId string - Required The unique identifier of the report that is being read.

Headers

Response

Status Codes

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'

Response

200 OK

{
    "approvalStatus": "Not Submitted",
    "approvalStatusId": "A_NOTF",
    "concurAuditStatus": "NOTR",
    "customData": [
        {
            "id": "custom15",
            "value": "4366A89A916F074099A971B000989A94",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=4366A89A916F074099A971B000989A94"
        },
        {
            "id": "custom16",
            "value": "Test33224ASDF",
            "isValid": true,
            "listItemUrl": null
        },
        {
            "id": "custom3",
            "value": "582AE31D0F506C4BAA97573F2A90F03B",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=582AE31D0F506C4BAA97573F2A90F03B"
        },
        {
            "id": "custom4",
            "value": "79AE45D0F6757946AC2B01CDFA6CA326",
            "isValid": true,
            "listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=79AE45D0F6757946AC2B01CDFA6CA326"
        }
    ],
    "ledger": "DEFAULT",
    "ledgerId": "2703E3FBD393DA4484ED3CB07303407C",
    "paymentStatus": "Not Paid",
    "paymentStatusId": "P_NOTP",
    "submitDate": null,
    "approvedAmount": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "claimedAmount": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "amountCompanyPaid": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "paymentConfirmedAmount": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueCompany": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueCompanyCard": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "amountDueEmployee": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "personalAmount": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "reportTotal": {
        "value": 525.00000000,
        "currencyCode": "USD"
    },
    "amountNotApproved": {
        "value": 0E-8,
        "currencyCode": "USD"
    },
    "isFinancialIntegrationEnabled": false,
    "canReopen": false,
    "isReopened": false,
    "isReceiptImageAvailable": false,
    "isReceiptImageRequired": true,
    "isPaperReceiptsReceived": false,
    "reportId": "764428DD6A664AF0BFCB",
    "currency": "US, Dollar",
    "currencyCode": "USD",
    "analyticsGroupId": "C8CB395275EC4FE9AF6CD5B535EA2B17",
    "hierarchyNodeId": "0F941E0B0A2C974EB2B06CDA67973052",
    "allocationFormId": "FD7E9C6389EF495B85042319D58CAE53",
    "links": [
        {
            "rel": "self",
            "href": "https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null,
            "method": "GET",
            "isTemplated": false
        }
    ],
    "reportDate": "2020-03-25",
    "reportFormId": "674B67F0C6BD4E9CA5D91AFB82CC8ABB",
    "businessPurpose": "Facility cleaning and renovation",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "policyId": "EE095F66AEF52B4A9CE62952601E5CB1",
    "startDate": "2020-03-10",
    "endDate": "2020-03-14",
    "name": "March Expenses",
    "policy": "JH - US Expense Policy",
    "country": "UNITED STATES",
    "userId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
    "reportType": "Regular",
    "redirectFund": null,
    "creationDate": "2020-03-25T20:42:39Z",
    "canRecall": false,
    "reportVersion": 0
}

Create a New Report

Creates a new report

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY

Headers

Payload

Response

Status Codes

Example

Request

curl --location --request POST 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"customData": [
        {
            "id": "custom15",
            "value": "E31CB42509F9FF408BA7DD6713AB49BD"
        }
    ],
    "businessPurpose":"Office Facility Supplies",
    "comment": "Monthly recurring supplies",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "name": "July Office Facility Supplies",
    "policyId": "0a3f90a7-2feb-47fa-972c-7ddf7f1eb1f7"
}'

Response

201 Created
{
	"uri": "https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/826FB0A052BD41E48CE6"
}

Update a Specific Report

Updates the attributes of a specific report.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report that is being modified.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"customData": [
        {
            "id": "custom15",
            "value": "E31CB42509F9FF408BA7DD6713AB49BD"
        }
    ],
    "businessPurpose":"Office Facility Supplies",
    "reportSource":"OTHER"
}'

Response

204 No Content

Update a Submitted Report

Updates the report header in an unsubmitted or submitted expense report specified and is restricted to modify Business Purpose, Comment, Custom/Org unit, Name and Paper Receipt Received fields only (only Company JWT Allowed).

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/reports/{reportId}

Parameters

Name Type Format Description
reportId string - Required The unique identifier of the report to which this expense entry belongs.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Payload

Update Report Compact Schema

Name Type Format Description
businessPurpose string - The text input for the business purpose by the user. Maximum length: 64 characters.
comment string - The expense report comment added by the user.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
name string - The expense report name input by the user.
isPaperReceiptsReceived boolean true/false Whether paper receipts have been received for the report.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "businessPurpose":"Office Supplies",
  "comment": "Monthly recurring supplies",  
	"customData": [
        {
            "id": "custom09",
            "value": "81188b39-605d-2d4f-b80b-43efa84a7b49",
            "isValid": true
        }
    ],
    "name": "July Office Facility Supplies",
    "isPaperReceiptsReceived": false
}'

Response

204 No Content

Get Reports To Approve

This endpoint retrieves all reports that a user can approve of as either an approver or delegate for an approver.

Scopes

expense.report.read - Refer to Scope Usage for full details.

expense.report.readwrite - Refer to Scope Usage for full details.

URI Template

https://{datacenterURI}/expensereports/v4/users/{userId}/context/{contextType}/reportsToApprove

Parameters

Name Type Format Description
userId string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the Concur user, which determines the form fields they can view/modify.
sort string - The name of the report field on which to sort.
order string - The order to sort the field by.
includeDelegateApprovals boolean - Boolean field indicating whether or not include reports you could approve as a delegate.

Headers

Request

curl --location --request GET https://integration.api.concursolutions.com/expensereports/v4/users/aa024d31-95eb-4270-b9yz-cb6b5f558a7c/context/MANAGER/reportsToApprove?sort=reportDate&order=desc&includeDelegateApprovals=true
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'

Response

[
  {
    "name": "string",
    "reportDate": "2023-05-09",
    "reportId": "string",
    "reportNumber": "string",
    "submitDate": "2023-05-09",
    "approver": {
      "employeeId": "string",
      "employeeUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "employee": {
      "employeeId": "string",
      "employeeUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "amountDueEmployee": {
      "value": 0,
      "currencyCode": "string"
    },
    "claimedAmount": {
      "value": 0,
      "currencyCode": "string"
    },
    "totalApprovedAmount": {
      "value": 0,
      "currencyCode": "string"
    },
    "hasExceptions": true,
    "reportType": "'Regular' or 'Reconciliation' or 'Statement' or 'AutoCreated'"
  }
]

Exception Response

{
  "timestamp": "2023-05-09T15:14:35.296Z",
  "httpStatus": "string",
  "errorMessage": "string",
  "errorId": "string",
  "validationErrors": [
    {
      "source": "string",
      "message": "string",
      "id": "string"
    }
  ],
  "customResponseData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "path": "string"
}

Status Codes

Schema

ReportDetails

Name Type Format Description
allocationFormId string - The unique identifier of the allocation form.
amountCompanyPaid Amount - Required The amount paid by the company.
amountDueCompany Amount - Required The amount that the employee owes the company.
amountDueCompanyCard Amount - Required The amount that the employee/company owes the corporate card.
amountDueEmployee Amount - Required The amount that the company owes the employee.
amountNotApproved Amount - Required The amount that was not approved for the report.
analyticsGroupId string - Required The unique identifier of the business intelligence hierarchy node.
approvalStatus string - Required The report’s approval status, in the user’s language.
approvalStatusId string - Required The unique identifier of the approval status.
approvedAmount Amount - Required The total amount of approved expenses in the report.
businessPurpose string - The text input for the business purpose by the user.
canRecall boolean true/false Required Whether the report can be recalled by the current user.
canReopen boolean true/false Whether the report can be reopened after payment.
cardProgramStatementPeriodId string - The unique identifier of card program statement period on the report.
claimedAmount Amount - Required The total amount of all non-personal expenses in the report.
concurAuditStatus string - Required The status of audit for the report.
country string - The country name associated with the report (localized as per accept-language header).
countryCode string ISO 3166-1 alpha-2 country code The report country. Maximum characters: 2. Example: US - United States
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
creationDate string YYYY-MM-DDTHH:mm:ssZ Required The UTC datetime when the user created the report.
currency string - Required The currency name for the report (localized as per accept-language header).
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
endDate string YYYY-MM-DD The end date (ISO-8601) of the report as used for trip-based reporting.
hierarchyNodeId string - Required The unique identifier of the group hierarchy node for the report resource.
isFinancialIntegrationEnabled boolean true/false Required Whether the Financial Integration setting has been enabled for this report.
isPaperReceiptsReceived boolean true/false Required Whether paper receipts have been received for the report.
isReceiptImageAvailable boolean true/false Required Whether the receipt image is available at the report level.
isReceiptImageRequired boolean true/false Required Whether the receipt image is required at the report level.
isReopened boolean true/false Whether the report is reopened.
ledger string - Required The ledger name to which the report belongs (localized as per accept-language header).
ledgerId string - Required The unique identifier of the ledger.
links Link - Resource links related to this call.
name string - Required The expense report name input by the user.
paymentConfirmedAmount Amount - Required The amount that was paid on the report.
paymentStatus string - Required The report’s payment status in the user’s language.
paymentStatusId string - Required The unique identifier of the payment status of the report.
personalAmount Amount - Required The total amount of expenses marked as personal on the report.
policy string - Required The policy name to which the report adheres (localized as per accept-language header).
policyId string - Required The unique identifier of the policy that applies to this report.
redirectFund RedirectFund - Funds redirected to IBCP card.
reportDate string YYYY-MM-DD The date assigned to the report by the user.
reportFormId string - Required The unique identifier of the report form.
reportId string - Required The unique identifier for the report resource.
reportNumber string - User friendly unique identifier for the report.
reportTotal Amount - Required The total amount on the report.
reportType string - This value identifies the method used to create the report. Statement refers to company billed statement reports and auto-created refers to reports created by Expense Assistant.
reportVersion integer int32 Required The current version of the report.
startDate string YYYY-MM-DD The start date of the report as used for trip-based reporting.
submitDate string YYYY-MM-DDTHH:mm:ssZ The UTC datetime when the user submitted the report.
submitterId string - The unique identifier of the employee who submitted the report.
taxConfigId string - The The tax config ID of the report.
userId string - Required The unique identifier of the Concur user who is the report owner.

NewReport

Name Type Format Description
businessPurpose string - The text input for the business purpose by the user.
comment string - The expense report comment added by the user.
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
endDate string YYYY-MM-DD The end date of the report as used for trip-based reporting.
name string - The expense report name input by the user.
policyId string - The unique identifier of the policy that applies to this report.
reportDate string YYYY-MM-DD The date assigned to the report by the user.
startDate string YYYY-MM-DD The start date of the report as used for trip-based reporting.

UpdateReport

Name Type Format Description
businessPurpose string - The text input for the business purpose by the user.
comment string - The expense report comment added by the user.
country string - The country name associated with the report (localized as per accept-language header).
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
endDate string YYYY-MM-DD The end date of the report as used for trip-based reporting.
isCopyDownInherited boolean true/false If true, any change in the report header fields will be copied down to expenses, itemizations and allocations, as per the configuration. Usage of this flag should be deliberate as data corruption could result.
isPaperReceiptsReceived boolean true/false Whether paper receipts have been received for the report.
name string - The expense report name input by the user.
policy string - The policy name to which the report adheres to.
policyId string - The unique identifier of the policy that applies to this report.
redirectFund RedirectFund - Funds redirected to IBCP card.
reportDate string YYYY-MM-DD The date assigned to the report by the user.
reportSource string - Required The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI
startDate string YYYY-MM-DD The start date of the report as used for trip-based reporting.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user’s assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

RedirectFund

Name Type Format Description
amount Amount - Required The value of funds redirected to the IBCP card account.
creditCardId string - Required The unique identifier of the IBCP card account to which funds need to be redirected.
Name Type Format Description
deprecation string - -
href string - Required The URL of the related HATEOAS link that you can use for subsequent calls.
hreflang string - -
isTemplated boolean true/false Required Whether the href is parameterized.
media string - -
method string - Required The HTTP method required for the related call.
rel string - Required The link relationship that describes how the href relates to the API call.
title string - -
type string - -

ErrorMessage

Name Type Format Description
customResponseData object - The custom parameters related to error.
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.

On this page