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

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

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

Receipt Schema

Error

Name Type Format Description
timestamp string - Date and time.
status string - HTTP status code.
message string - Error message content.

Status Codes

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

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.

On this page