Spend Documents v4
Spend Documents v4 provides APIs for ingesting & retrieving receipts and compliance documents. Certified vendors, who have achieved compliance, are able to utilize these APIs to submit compliant receipts to the SAP Concur platform. The workflow involves vendors posting a display version of the receipt, accompanied by the necessary data to generate a receipt. Following this, they can use the PUT API to upload the compliance document. After a successful posting and processing of the receipts, available expenses or receipts are created in Concur Expense.
Prior Versions
The Spend Documents v4 API coexists with another set of Receipts V4 APIs. The latter is currently used for facilitating the submission of electronic receipts (eReceipts) to the SAP Concur platform.
Limitations
Access to this documentation does not provide access to the API. To submit electronic receipts (eReceipts) please use the Receipts v4 APIs.
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Name | Description | Endpoint |
---|---|---|
spenddocs.receipts.write spenddocs.receipts.writeonly |
Post receipt for the user | POST |
spenddocs.receipts.read |
Retrieve Receipt and its representations either by Receipt Id or Image Id and company Id | GET |
spenddocs.receipts.compliance.read |
Retrieve compliance representation of the receipt | GET |
spenddocs.receipts.compliance.write spenddocs.receipts.compliance.writeonly |
Put compliance representation of the receipt | PUT |
Post a New Receipt
This endpoint facilitates the creation of a new receipt. The data for the receipt should be supplied within the request body. Additionally, the display document for the receipt should be uploaded within the same request body, and the feature should be configured to ‘cfdi’.
Scopes
spenddocs.receipts.write
spenddocs.receipts.writeOnly
- Refer to Scope Usage for full details.
URI Template: /spend-documents/v4/receipts
Method: POST
Request
Name | Type | Format | Description |
---|---|---|---|
receipt |
object |
- | Required. The receipt data in JSON format. |
document |
string |
- | The receipt document to be uploaded. Compatible formats are: PDF, JPEG, PNG, GIF, JPG. |
Refer to the Receipt Schema for the structure of the receipt object.
Response
Success
Name | Type | Format | Description |
---|---|---|---|
id |
string |
- | UUID of the receipt. |
imageId |
string |
- | Identifier for the image. |
href |
string |
- | URI to retrieve the receipt. |
Error
Name | Type | Format | Description |
---|---|---|---|
timestamp |
string |
- | Date and time. |
status |
string |
- | HTTP status code. |
message |
string |
- | Error message content. |
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Internal Service Unavailable
Example
Request
curl -L -X POST 'https://us.api.concursolutions.com/spend-documents/v4/receipts' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json' \
-F 'image=@"1.jpg"' \
--F 'receipt="{
"metadata": {
"userId": "a9abaa60-38a0-46be-9736-bc9c1e317e41",
"companyId": "fb7c8157-16d6-4dfd-b970-8c2a39d81790",
"origin": "vendor",
"feature": "cfdi",
"category": "general"
},
"receiptData": {
"transactionDateTime": "08/08/2022 3:30 PM",
"amount": {
"total": "18.47",
"currency": "GBP",
"subTotal": "15.05"
},
"vendor": {
"name": "Amazon",
"addressLine": "1234, Test street",
"city": "seattle",
"state": "washington",
"country": "US",
"postalCode": "98050",
"taxId": "12ADAqweq",
"phone": "4252322323"
},
"paymentType": {
"method": "Credit Card",
"creditCard": {
"type": "MasterCard",
"lastFour": "6170"
}
},
"referenceNumber": "203-6291668-6997137",
"lineItems": [
{
"title": "testTitle",
"description": "KetoPlastics 1 ® 110 Litre Black Bin/Refuse Bin With Lockable Lid (Made In The UK)",
"date": "2022-08-08T15:30:12-0500",
"folioType": "00",
"amount": "18.47",
"quantity": "5",
"unitPrice": "17.07",
"subTotal": "15.05",
"discounts": [
{
"discountAmount": "-2.02",
"discountName": "Discount lineitem level"
}
],
"taxes": [
{
"amount": "3.42",
"name": "Tax",
"rate": 0.9
}
],
"additionalDescription": "Seller: Ketoplastics Limited",
"semanticsCode": "OTHERS"
}
],
"discounts": [
{
"discountAmount": "-2.02",
"discountName": "Discount receipt level"
}
],
"discountsTotal": "-2.33",
"taxesTotal": "3.42",
"tripDetails": {
"itineraryLocator": "12345",
"driverNumber": "ss-343",
"travelDuration": "test",
"mapUrl": "https://test.com",
"startDate": "2014-11-10T15:08:24-0700",
"endDate": "2014-11-10T15:39:46-0700",
"classOfService": "Taxi Cab",
"distance": {
"totalDistance": 15.6,
"unit": "mi"
},
"source": {
"name": "start",
"addressLine": "601 108th Ave NE",
"city": "Bellevue",
"country": "US",
"postalCode": "98004"
},
"destination": {
"name": "end",
"addressLine": "1218 3rd Ave",
"city": "Seattle",
"country": "US",
"postalCode": "98104"
}
}
}
}"
'
Response
202 Accepted
{
"imageId": "341D9EFCDC4E3833B76F75CFC53FF2E9",
"href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/3602e892-f463-497a-8654-8b2e802f4d65",
"id": "3602e892-f463-497a-8654-8b2e802f4d65"
}
Compliance Document for an Existing Receipt
This endpoint facilitates the creation of a compliance document for an existing receipt. The compliance document should be uploaded within the request body.
Scopes
spenddocs.receipts.compliance.write
spenddocs.receipts.compliance.writeonly
Refer to Scope Usage for full details.
Request
URI Template: /spend-documents/v4/receipts/{receiptId}
Method: PUT
Parameters
Name | Type | Format | Description |
---|---|---|---|
receiptId |
string |
- | Required. The unique identifier (UUID) of the receipt. |
Type |
string |
- | Required. cfdi. |
Response
Success
Name | Type | Format | Description |
---|---|---|---|
id |
string |
- | UUID of the receipt. |
Error
Name | Type | Format | Description |
---|---|---|---|
timestamp |
string |
- | Date and time. |
status |
string |
- | HTTP status code. |
message |
string |
- | Error message content. |
Refer to the Receipt Schema for the structure of the receipt object.
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Internal Service Unavailable
Example
Request
curl --location --request PUT 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json' \
-F 'image=@"compliance.xml"
Response
{
"id": "41545f0b-ebce-47b5-8233-1e6ef7f7b3c8"
}
Get Receipt
There are two endpoints to retrieve the details of a specific receipt.
By ReceiptId
This endpoint retrieves the details of a specific receipt using the receipt’s unique identifier (UUID).
By ImageId and CompanyId
This endpoint retrieves the details of a specific receipt using the companyId
and imageId
.
Scopes
spenddocs.receipts.read
- Refer to Scope Usage for full details.
Request
URI Template:
- By Receipt Id:
/spend-documents/v4/receipts/{receiptId}
- By Image Id and Company Id:
/spend-documents/v4/receipts?imageId={imageId}&companyId={companyId}
Method: GET
Parameters
Name | Type | Format | Description |
---|---|---|---|
receiptId or companyId + imageId |
string | - | Required. The unique identifier (UUID) of the receipt OR the unique identifier (UUID) of the company and identifier for the imageId . |
Response
Success
Error
Name | Type | Format | Description |
---|---|---|---|
timestamp |
string |
- | Date and time. |
status |
string |
- | HTTP status code. |
message |
string |
- | Error message content. |
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Internal Service Unavailable
Headers
concur-correlationid
is a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.
Payload
Receipt Response
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'
Or
curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts?imageId=2AB8D2C8078C4E38A5E7F18A6DE5558D&companyId=71f74b81-bb57-4c54-8985-5d7c42f6feb1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'
Response
200 OK
{
"metadata": {
"userId": "3e2c1b7e-0969-41b1-b5a6-590eb6a5f885",
"imageId": "F66F323EAC704DA3B3AA85F66D7E1663",
"id": "4d3a8d80-0f93-4b0b-bed1-2724a354858c",
"companyId": "8f8fd1d8-bbc6-4611-861d-af714a02275f",
"dateTimeReceived": "2024-04-26T18:37:41.930Z",
"origin": "mobile",
"captureMethod": "cameraCapture",
"provider": "user",
"feature": "cfdi",
"status": "processed",
"compliance": {
"status": "processed"
}
},
"receiptData": {
"transactionDateTime": "2023-12-30T11:30:00",
"amount": {
"total": "30.0",
"currency": "USD"
},
"vendor": {
"name": "KIRKLAND PERFORMANCE CENTER",
"city": "KIRKLAND",
"state": "WASHINGTON",
"country": "US"
},
"paymentType": {
"creditCard": {
"type": "$$",
"lastFour": "1006"
}
},
"expenseData": {
"expenseType": "PARKG"
}
},
"documents": [
{
"representation": "display",
"type": "application/pdf",
"name": "fr_expenseit.pdf",
"renderable": true,
"href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/4d3a8d80-0f93-4b0b-bed1-2724a354858c/representations?type=display"
},
{
"representation": "compliance",
"type": "application/pdf",
"name": "4d3a8d80-0f93-4b0b-bed1-2724a354858c.pdf",
"renderable": true,
"href": "https://us.api.concursolutions.com/spend-documents/v4/receipts/4d3a8d80-0f93-4b0b-bed1-2724a354858c/representations?type=compliance"
}
]
}
Get Receipt Representation
There are two endpoints to retrieve the receipt document (display or compliance) of a specific receipt.
By ReceiptId
Retrieves the receipt using the receipt’s unique identifier (UUID).
By ImageId and CompanyId
Retrieves the receipt using the companyId
and imageId
.
Scopes
spenddocs.receipts.read, spenddocs.compliance.read
Refer to Scope Usage for full details.
Request
URI Template:
- By Receipt Id:
/spend-documents/v4/receipts/{receiptId}/representations?type={display or compliance}
- By Image Id and Company Id:
/spend-documents/v4/receipts?imageId={imageId}&companyId={companyId}&type={display or compliance}
Method: GET
Parameters
Name | Type | Format | Description |
---|---|---|---|
receiptId or companyId + imageId |
string |
Required. The unique identifier (UUID) of the receipt OR the unique identifier (UUID) of the company and identifier for the imageId . |
|
Type | string | Required display or compliance |
Response
Success
Returns the image byte stream.
Error
Name | Type | Format | Description |
---|---|---|---|
timestamp |
string |
- | Date and time. |
status |
string |
- | HTTP status code. |
message |
string |
- | Error message content. |
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Internal Service Unavailable
Payload
Receipt Response
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts/8d157fb6-b06b-4ea8-b632-c1f477b93745/representations?type=display' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'
Or
curl --location --request GET 'https://us.api.concursolutions.com/spend-documents/v4/receipts?imageId=2AB8D2C8078C4E38A5E7F18A6DE5558D&companyId=71f74b81-bb57-4c54-8985-5d7c42f6feb1&/representations?type=compliance \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: dc673e9a-1297-499d-beb4-0419d750a034' \
--header 'Content-Type: application/json'
Response
HTTP/1.1 200 ok
Content-Type: image/png
Content-Length: 108842
Returns the image byte stream.
Schema
Receipt
Name | Type | Format | Description |
---|---|---|---|
metadata |
object |
- | Receipt API schema for metadata, receipt-data, enrichmentData and document (& representations). |
receiptData |
object |
- | Receipt API schema for receipt data. |
Metadata
Name | Type | Format | Description |
---|---|---|---|
userId |
string |
- | User’s UUID. |
forwardId |
string |
- | Forward Id that clients provide. |
imageId |
string |
- | Imaging Id in Imaging Service. |
id |
string |
- | Receipt Id. |
companyId |
string |
- | Company UUID. |
dateTimeReceived |
string |
- | Date time of receipt uploaded. |
origin |
string |
- | Origin of the request - supported origins listed below. |
captureMethod |
string |
- | Type of the receipt capture method. |
provider |
string |
- | Provider of the request - supported providers listed below. |
complianceCountryCode |
string |
- | Compliance country code based on user group configuration. |
feature |
string |
- | Feature enrichment for the receipt. |
status |
string |
- | Receipt status. |
compliance |
object |
- | Compliance information for the receipt. |
entityId |
string |
- | Entity Code. |
category |
string |
- | eReceipt category. |
ReceiptData
Name | Type | Format | Description |
---|---|---|---|
receiveDateTime |
string |
- | Date/Time of the document received by customer. |
transactionDateTime |
string |
- | Date/Time of the transaction. |
amount |
object |
- | Transaction Amount - Total, Transaction Currency Code, Total Net Amount, Transaction Amount - Sub Total. |
vendor |
object |
- | Vendor details: Name, Tax Id of the company/vendor, Address Line, City, State, Country, Postal Code, Phone. |
comments |
string |
- | Comments can be added here for any receipt. |
paymentType |
object | - | Supported Payment types based on the data on the Receipt: Payment type method (enum: Cash, Credit Card, Digital Wallet), Credit card type if the payment method is credit card (Name of the card type ex: American Express, MasterCard, Discover, etc., Last 4 digits of credit card number if the payment method is credit card), if the payment method is digitalWallet, type of digital wallet (ex: ApplePay, PayTM, Rupay, GooglePay etc.). |
documentCompliance |
object |
- | Document Compliance information: UUID of the Document, Version of the document format, Additional identified for the document, Document Type (only code), Codes supported by the document, Verification or Certificate Code. |
lineItems |
array |
- | Array of LineItems: Line Identifier, Product Code of goods and services, Item Quantity, Item Unit Price, Item Tax Rate (optional), Item Sub Total (optional), Description, Date, Type, Amount, The taxes applied on this LineItem transaction, The discounts offered on this LineItem transaction, Additional Description, Indicates the charge category for the line item. Example: ‘MOVIE’, ‘PARKING’, ‘OTHER’ etc. |
expenseData |
object |
- | Expense Data: Expense Type for Expense reimbursement, Payment type for Expense reimbursement. |
customData |
object |
- | Custom Data. |
referenceNumber |
string |
- | The unique receipt provider or vendor identifier for this receipt. This value can also be referred to as transaction number, check number, order ID or similar. |
discounts |
array |
- | The discounts offered on this transaction. |
discountsTotal |
string |
- | Total discounts. |
taxesTotal |
string |
- | Total taxes. |
tripDetails |
object |
- | Trip details, This includes all the trip/travel related information specific to an eReceipt category: Unique identifier of an itinerary (also know as a trip) in Concur Itinerary Service. An itinerary can contain one or more bookings from various sources, Unique identifier assigned by the ride company to a driver, Duration of the ride, Google Map url documenting the route taken, Trip starting Date/Time, Trip ending Date/Time, The class of the booking, Trip Distance (Total Distance, Unit of distance: km, mi), Source address which can be pickup location, departure etc., Destination address which can be drop location, arrival etc. |
programName |
string |
- | Name of the program applied to the Receipt. |
networkTransactionId |
string |
- | The network transaction id for the payment. |
taxes |
array |
- | The taxes applied on this transaction. |
Document Data
Name | Type | Format | Description |
---|---|---|---|
representation |
string |
- | For a given receipt document three representations can be stored in the system. Display – a downsized image version to cater for web and mobile UI, compliance - reflects the signed or certified or verified document, original - original document that was submitted. |
type |
string |
- | File type of the receipt document, e.g., PDF, JPEG, PNG, GIF, JPG. |
name |
string |
- | File name of the receipt document. |
renderable |
boolean |
true / false |
Boolean indicating whether the document can be rendered in UI. |
href |
string |
- | Href to download the document. |