openapi: 3.1.0
info:
title: SAP Concur Expense API
description: >-
SAP Concur Expense provides REST APIs for managing the full expense lifecycle
including creating and submitting expense reports, managing individual expense
entries, capturing receipt images, handling quick expenses, managing allocations
across cost centers, and retrieving reimbursement payment batches. Authentication
uses OAuth 2.0 with support for authorization code and refresh token flows.
version: '3.0'
contact:
name: SAP Concur Developer Support
url: https://developer.concur.com/support
termsOfService: https://developer.concur.com/terms-of-use
externalDocs:
description: SAP Concur Expense API Reference
url: https://developer.concur.com/api-reference/expense/
servers:
- url: https://us.api.concursolutions.com/api/v3.0
description: United States Production
- url: https://eu.api.concursolutions.com/api/v3.0
description: Europe Production
- url: https://cn.api.concursolutions.com/api/v3.0
description: China Production
tags:
- name: Expense Reports
description: >-
Create, read, update, and submit expense reports. Manage the full
report lifecycle from draft through approval and reimbursement.
- name: Expense Entries
description: >-
Manage individual expense line items within expense reports including
itemizations, attendees, and custom fields.
- name: Quick Expenses
description: >-
Create and manage quick expenses captured outside of a formal report.
Quick expenses can be promoted to full expense report entries.
- name: Receipt Images
description: >-
Upload and retrieve receipt images associated with expense entries.
Supports PNG, JPG, PDF, and TIFF image formats.
- name: Allocations
description: >-
Manage cost center, project, or GL account allocations for expense entries.
Supports percentage-based and amount-based splits.
- name: Payment Batches
description: >-
Retrieve payment batch information for approved expense reports
ready for reimbursement processing.
- name: Group Configurations
description: >-
Retrieve expense group policy configurations including expense types,
payment types, and workflow settings.
security:
- OAuth2:
- expense.report.read
- expense.report.write
paths:
/expense/reports:
get:
operationId: listExpenseReports
summary: List Expense Reports
description: >-
Returns a collection of expense reports belonging to the current user or
accessible via company-level access. Supports filtering by approval status,
submission date, payment status, and reimbursement method.
tags:
- Expense Reports
parameters:
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page (max 100)
required: false
schema:
type: integer
maximum: 100
- name: approvalStatusCode
in: query
description: >-
Filter by approval status code. Valid values: A_AAFH, A_AAPH,
A_ADMIN, A_APPR, A_EXTV, A_FILE, A_NOTF, A_PBDG, A_PECO,
A_PEND, A_PVAL, A_RESU, A_RHLD, A_TEXP
required: false
schema:
type: string
- name: paymentStatusCode
in: query
description: >-
Filter by payment status code. Valid values: P_HOLD, P_NOTP,
P_PAID, P_PAYC, P_PROC
required: false
schema:
type: string
- name: modifiedDateBefore
in: query
description: Return reports modified before this date (ISO 8601 format)
required: false
schema:
type: string
format: date-time
- name: modifiedDateAfter
in: query
description: Return reports modified after this date (ISO 8601 format)
required: false
schema:
type: string
format: date-time
- name: userID
in: query
description: >-
The login ID of the report owner. May only be used by company-level
access token holders.
required: false
schema:
type: string
- name: reimbursementMethod
in: query
description: >-
Filter by reimbursement method. Valid values: ADPPAYR, APCHECK,
AVI, CNQRPAY, PMTSERV
required: false
schema:
type: string
responses:
'200':
description: Success - Returns list of expense reports
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseReportCollection'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
post:
operationId: createExpenseReport
summary: Create Expense Report
description: >-
Creates a new expense report header. After creating the report header,
expense entries can be added using the expense entries endpoint.
tags:
- Expense Reports
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseReportCreate'
responses:
'200':
description: Success - Returns the created expense report ID
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseReportCreateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/reports/{id}:
get:
operationId: getExpenseReport
summary: Get Expense Report
description: >-
Returns a single expense report by its ID. Includes report header
information such as approval status, totals, and submission date.
tags:
- Expense Reports
parameters:
- name: id
in: path
description: The unique identifier of the expense report
required: true
schema:
type: string
responses:
'200':
description: Success - Returns the expense report
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseReport'
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
put:
operationId: updateExpenseReport
summary: Update Expense Report
description: >-
Updates an existing expense report header. Only draft reports
(not yet submitted) can be updated.
tags:
- Expense Reports
parameters:
- name: id
in: path
description: The unique identifier of the expense report
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseReportUpdate'
responses:
'204':
description: Success - No content returned
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
delete:
operationId: deleteExpenseReport
summary: Delete Expense Report
description: >-
Deletes an expense report. Only draft reports that have never been
submitted can be deleted.
tags:
- Expense Reports
parameters:
- name: id
in: path
description: The unique identifier of the expense report
required: true
schema:
type: string
responses:
'204':
description: Success - No content returned
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
/expense/entries:
get:
operationId: listExpenseEntries
summary: List Expense Entries
description: >-
Returns a collection of expense entries for the specified report ID.
Each entry represents a single expense line item with amount, date,
category, and supporting details.
tags:
- Expense Entries
parameters:
- name: reportID
in: query
description: The unique identifier of the expense report
required: true
schema:
type: string
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page (max 100)
required: false
schema:
type: integer
maximum: 100
responses:
'200':
description: Success - Returns list of expense entries
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseEntryCollection'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
post:
operationId: createExpenseEntry
summary: Create Expense Entry
description: >-
Creates a new expense entry within an expense report. The report must
exist and be in draft state. The entry requires an expense type code,
transaction date, and transaction amount.
tags:
- Expense Entries
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseEntryCreate'
responses:
'200':
description: Success - Returns the created entry ID
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseEntryCreateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/entries/{id}:
get:
operationId: getExpenseEntry
summary: Get Expense Entry
description: >-
Returns a single expense entry by its ID, including all form field
values, itemizations, and attendee information.
tags:
- Expense Entries
parameters:
- name: id
in: path
description: The unique identifier of the expense entry
required: true
schema:
type: string
responses:
'200':
description: Success - Returns the expense entry
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseEntry'
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
put:
operationId: updateExpenseEntry
summary: Update Expense Entry
description: >-
Updates an existing expense entry. Only entries in draft reports
can be modified.
tags:
- Expense Entries
parameters:
- name: id
in: path
description: The unique identifier of the expense entry
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseEntryUpdate'
responses:
'204':
description: Success - No content returned
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
delete:
operationId: deleteExpenseEntry
summary: Delete Expense Entry
description: Deletes an expense entry from a draft expense report.
tags:
- Expense Entries
parameters:
- name: id
in: path
description: The unique identifier of the expense entry
required: true
schema:
type: string
responses:
'204':
description: Success - No content returned
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
/expense/quickexpenses:
get:
operationId: listQuickExpenses
summary: List Quick Expenses
description: >-
Returns quick expenses for the current user. Quick expenses are unassigned
expense records captured before being added to an expense report.
tags:
- Quick Expenses
parameters:
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page (max 100)
required: false
schema:
type: integer
maximum: 100
- name: modifiedDateBefore
in: query
description: Return quick expenses modified before this date
required: false
schema:
type: string
format: date-time
- name: modifiedDateAfter
in: query
description: Return quick expenses modified after this date
required: false
schema:
type: string
format: date-time
responses:
'200':
description: Success - Returns list of quick expenses
content:
application/json:
schema:
$ref: '#/components/schemas/QuickExpenseCollection'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
post:
operationId: createQuickExpense
summary: Create Quick Expense
description: >-
Creates a new quick expense record. Quick expenses can be created without
an associated expense report and promoted to a full report entry later.
tags:
- Quick Expenses
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QuickExpenseCreate'
responses:
'200':
description: Success - Returns the created quick expense ID
content:
application/json:
schema:
$ref: '#/components/schemas/QuickExpenseCreateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/quickexpenses/{id}:
get:
operationId: getQuickExpense
summary: Get Quick Expense
description: Returns a single quick expense by its ID.
tags:
- Quick Expenses
parameters:
- name: id
in: path
description: The unique identifier of the quick expense
required: true
schema:
type: string
responses:
'200':
description: Success - Returns the quick expense
content:
application/json:
schema:
$ref: '#/components/schemas/QuickExpense'
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
put:
operationId: updateQuickExpense
summary: Update Quick Expense
description: Updates an existing quick expense record.
tags:
- Quick Expenses
parameters:
- name: id
in: path
description: The unique identifier of the quick expense
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QuickExpenseUpdate'
responses:
'204':
description: Success - No content returned
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
delete:
operationId: deleteQuickExpense
summary: Delete Quick Expense
description: Deletes a quick expense record.
tags:
- Quick Expenses
parameters:
- name: id
in: path
description: The unique identifier of the quick expense
required: true
schema:
type: string
responses:
'204':
description: Success - No content returned
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
/expense/receiptimages:
get:
operationId: listReceiptImages
summary: List Receipt Images
description: >-
Returns a collection of receipt images associated with expense entries
for the current user.
tags:
- Receipt Images
parameters:
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page (max 100)
required: false
schema:
type: integer
maximum: 100
- name: entryID
in: query
description: Filter receipt images by expense entry ID
required: false
schema:
type: string
responses:
'200':
description: Success - Returns list of receipt images
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptImageCollection'
'401':
description: Unauthorized
'500':
description: Internal Server Error
post:
operationId: createReceiptImage
summary: Upload Receipt Image
description: >-
Uploads a new receipt image. The image can be in PNG, JPG, PDF, or
TIFF format and will be associated with an expense entry.
tags:
- Receipt Images
requestBody:
required: true
content:
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
application/pdf:
schema:
type: string
format: binary
responses:
'200':
description: Success - Returns receipt image ID
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptImageCreateResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/receiptimages/{id}:
get:
operationId: getReceiptImage
summary: Get Receipt Image
description: Returns the receipt image URL for the specified image ID.
tags:
- Receipt Images
parameters:
- name: id
in: path
description: The unique identifier of the receipt image
required: true
schema:
type: string
responses:
'200':
description: Success - Returns the receipt image
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptImage'
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
delete:
operationId: deleteReceiptImage
summary: Delete Receipt Image
description: Deletes a receipt image by its ID.
tags:
- Receipt Images
parameters:
- name: id
in: path
description: The unique identifier of the receipt image
required: true
schema:
type: string
responses:
'204':
description: Success - No content returned
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
/expense/allocations:
get:
operationId: listAllocations
summary: List Expense Allocations
description: >-
Returns expense allocations for the specified entry ID. Allocations
split an expense across multiple cost centers, projects, or GL accounts.
tags:
- Allocations
parameters:
- name: entryID
in: query
description: The expense entry ID to retrieve allocations for
required: true
schema:
type: string
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page (max 100)
required: false
schema:
type: integer
maximum: 100
responses:
'200':
description: Success - Returns list of allocations
content:
application/json:
schema:
$ref: '#/components/schemas/AllocationCollection'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/expensegroupconfigurations:
get:
operationId: listExpenseGroupConfigurations
summary: List Expense Group Configurations
description: >-
Returns expense group policy configurations for the current user.
Configurations define available expense types, payment types, allowable
business purposes, and workflow approval rules.
tags:
- Group Configurations
parameters:
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page
required: false
schema:
type: integer
- name: userID
in: query
description: The login ID of the user to retrieve configurations for
required: false
schema:
type: string
responses:
'200':
description: Success - Returns expense group configurations
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseGroupConfigCollection'
'401':
description: Unauthorized
'500':
description: Internal Server Error
/expense/expensegroupconfigurations/{id}:
get:
operationId: getExpenseGroupConfiguration
summary: Get Expense Group Configuration
description: Returns a single expense group configuration by its ID.
tags:
- Group Configurations
parameters:
- name: id
in: path
description: The unique identifier of the expense group configuration
required: true
schema:
type: string
responses:
'200':
description: Success - Returns the expense group configuration
content:
application/json:
schema:
$ref: '#/components/schemas/ExpenseGroupConfig'
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
/expense/paymentbatches:
get:
operationId: listPaymentBatches
summary: List Payment Batches
description: >-
Returns payment batches for approved expense reports ready for
reimbursement. Payment batches group multiple expense reports into
a single payment run.
tags:
- Payment Batches
parameters:
- name: offset
in: query
description: Starting page offset for pagination
required: false
schema:
type: string
- name: limit
in: query
description: Number of records to return per page
required: false
schema:
type: integer
- name: batchID
in: query
description: Filter by specific payment batch ID
required: false
schema:
type: string
responses:
'200':
description: Success - Returns list of payment batches
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentBatchCollection'
'401':
description: Unauthorized
'500':
description: Internal Server Error
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://us.api.concursolutions.com/oauth2/v0/authorize
tokenUrl: https://us.api.concursolutions.com/oauth2/v0/token
scopes:
expense.report.read: Read expense reports
expense.report.write: Create and modify expense reports
expense.report.delete: Delete expense reports
schemas:
ExpenseReportCollection:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/ExpenseReport'
NextPage:
type: string
description: URL to the next page of results
ExpenseReport:
type: object
properties:
ID:
type: string
description: The unique identifier of the expense report
Name:
type: string
description: The name of the expense report
Total:
type: number
format: double
description: Total amount of all expenses in the report
CurrencyCode:
type: string
description: ISO 4217 currency code for the report total
ApprovalStatusCode:
type: string
description: Current approval status code
ApprovalStatusName:
type: string
description: Human-readable approval status name
PaymentStatusCode:
type: string
description: Current payment status code
PaymentStatusName:
type: string
description: Human-readable payment status name
SubmitDate:
type: string
format: date-time
description: Date the report was submitted for approval
CreateDate:
type: string
format: date-time
description: Date the report was created
ProcessingPaymentDate:
type: string
format: date-time
description: Date payment processing began
OwnerLoginID:
type: string
description: Login ID of the report owner
OwnerName:
type: string
description: Full name of the report owner
PolicyID:
type: string
description: The expense policy ID applied to this report
ReportNumber:
type: string
description: Human-readable report number
HasException:
type: boolean
description: Whether the report has policy exceptions
URI:
type: string
description: URI to retrieve this resource
ExpenseReportCreate:
type: object
required:
- Name
properties:
Name:
type: string
description: The name of the expense report
Comment:
type: string
description: Additional comments for the report
PolicyID:
type: string
description: The expense policy ID to apply
Purpose:
type: string
description: Business purpose for the expenses
UserDefinedDate:
type: string
format: date-time
description: User-defined date for the report
ExpenseReportCreateResponse:
type: object
properties:
ID:
type: string
description: The unique identifier of the created expense report
URI:
type: string
description: URI of the created resource
ExpenseReportUpdate:
type: object
properties:
Name:
type: string
description: Updated name for the expense report
Comment:
type: string
description: Updated comment
Purpose:
type: string
description: Updated business purpose
ExpenseEntryCollection:
type: object
properties:
Items:
type: array
items:
$ref: '#/components/schemas/ExpenseEntry'
NextPage:
type: string
description: URL to the next page of results
ExpenseEntry:
type: object
properties:
ID:
type: string
description: The unique identifier of the expense entry
ReportID:
type: string
description: The parent expense report ID
ExpenseTypeCode:
type: string
description: Expense type code (e.g., BUSML, AIRFR, HOTEL)
ExpenseTypeName:
type: string
description: Human-readable expense type name
TransactionDate:
type: string
format: date
description: Date of the expense transaction
TransactionAmount:
type: number
format: double
description: Amount of the transaction in transaction currency
TransactionCurrencyCode:
type: string
description: ISO 4217 currency code of the transaction
PostedAmount:
type: number
format: double
description: Amount posted in report currency
BusinessPurpose:
type: string
description: Business purpose for the expense
VendorDescription:
type: string
description: Name of the vendor or merchant
LocationName:
type: string
description: Location where expense was incurred
IsItemized:
type: boolean
description: Whether the entry has been itemized
HasVAT:
type: boolean
description: Whether VAT tax applies to this entry
ReceiptImageID:
type: string
description: ID of the associated receipt image
URI:
type: string
description: URI to retrieve this resource
ExpenseEntryCreate:
type: object
required:
- ReportID
- ExpenseTypeCode
- TransactionDate
- TransactionAmount
- TransactionCurrencyCode
properties:
ReportID:
type: string
description: The parent expense report ID
ExpenseTypeCode:
type: string
description: Expense type code
TransactionDate:
type: string
format: date
description: Date of the expense transaction
TransactionAmount:
type: number
format: doubl
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sap-concur-expense/refs/heads/main/openapi/sap-concur-expense-report-openapi.yml