Definitions of Resources

• E-Receipt - A schema-enforced resource with data and, optionally, an image. If an image is not provided, one will be generated from the data resource.
• Image-Only Receipt - A standalone image without data.

Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Supported Image Formats

• Image size must not exceed 25MB.
• Images with any dimension exceeding 2,200 pixels will be reduced, with the longest dimension reduced to 2,200 pixels and the remaining dimensions scaled down using a fixed aspect ratio.
• Image must be one of the supported file types: image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, and application/pdf. Images provided in image/tiff and image/tif will be converted to a PDF document with the image embedded within.

General

Endpoint: Service Index

GET /

Making a GET request to the root of the service will return a list of current endpoints. If endpoint URLs ever change, the service index will be updated. To ensure that you are using the correct URLs, the safest practice is to check the service index before every request. The response will include current URLs for all endpoints in the receipt service.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/

HTTPie:

http https://us.api.concursolutions.com/receipts/ 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "links": [
    {
      "rel": "self",
      "href": "https://us.api.concursolutions.com/receipts/v4"
    },
    {
      "rel": "receipt-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "rel": "receipt-post",
      "method": "POST",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "receipts-get-user",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "schemas-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas"
    }
  ]
}

Back to Top

E-Receipts

Endpoint: Schemas

GET /schemas/:schemaId

The response to a GET request to /schemas will have a list of JSON validation schemas for available receipt types. An array of supportingSchemas is also returned, but these do not represent actual receipt types.

If a schema ID is provided, then only the schema with that ID will be returned, instead of the entire schema index. The ID’s of schemas are not UUIDs, but are instead just the names of the schema with the extension .schema.json. For example, car-rental-receipt.schema.json or air-receipt.schema.json.

One of the receipt schemas must be included in the link header of receipt POST requests with the relationship of describedBy. This looks like link: <http://schema.concursolutions.com/{RECEIPT TYPE}.schema.json>;rel=describedBy.

Example Requests:

cURL for the schema index:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/

HTTPie for the schema index:

http https://us.api.concursolutions.com/receipts/schemas 'Authorization:Bearer {YOUR ACCESS TOKEN}'

cURL for a single schema:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json

HTTPie for a single schema:

http https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "receiptSchemas": [
    {
      "rel": "http://schema.concursolutions.com/air-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/air-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/general-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/general-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/ground-transport-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/ground-transport-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/hotel-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/hotel-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/jpt-ic-card-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/jpt-ic-card-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/rail-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/rail-receipt.schema.json"
    }
  ],
  "supportingSchemas": [
    {
      "rel": "http://schema.concursolutions.com/address-original.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address-original.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/address.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/common.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/common.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/discount.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/discount.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/line-item.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/line-item.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/location.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/location.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/merchant.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/merchant.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/payments.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/payments.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/receipt-core.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/receipt-core.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/taxes.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/taxes.schema.json"
    }
  ]
}

Back to Top

Endpoint: Get Receipt Status

GET /v4/status/:receiptId

This endpoint may be used to see the current processing status of a receipt.

When a successful POST request is made the Link header of the response contains a ‘processing-status’ URL. This processing-status URL will be available for two weeks after the initial POST and will provide information regarding the processing status of your receipt.

There are four possible top level statuses: ACCEPTED, FAILED, PROCESSING, and PROCESSED.

In additional to a high level status, information will be provided in an array of event logs. Events that may be included in the logs will be typed as INFO, DEBUG, WARNING, or ERROR.

Example event messages:

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "status": "PROCESSED",
  "logs": [
    {
      "logLevel": "INFO",
      "message": "Receipt accepted. Queued for processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Initiated receipt processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Receipt image generated.",
      "timestamp": "Mon, 08 May 2017 23:05:53 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Processing finished.",
      "timestamp": "Mon, 08 May 2017 23:05:54 GMT"
    }
  ]
}

Back to Top

Endpoint: Post a Receipt

POST /v4/users/:userId

Creating a receipt requires JSON data about the transaction and, optionally, an image of the receipt. If an image is not supplied with the request, SAP Concur will automatically generate a receipt image based on the data provided. JSON schemas are used to validate the format of receipt data received in POST requests.

SAP Concur systems and clients rely on e-receipts to be legally valid tax documents in the relevant government jurisdictions. Please see this information regarding important usage restrictions.

Successful POST requests will receive a response of 201 Created. The Location header of the response contains a URL for your receipt. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt. More information can be found here.

Helpful Notes:

• Include link as a header and make its value: “http://schema.concursolutions.com/{receipt type}.schema.json;rel=describedBy”
• Copy a sample receipt of that receipt type from the documentation (https://developer.concur.com/api-reference/receipts/sample-receipts.html) and post it into the body of this POST call → you can then edit this body to your specification

If you are not providing an image with your receipt data, the body of the request should be your receipt JSON.

Receipt images may be posted along with data. In this case, SAP Concur will use the provided image instead of generating a new one. To post data and an image, use multipart form data. The Content-Type:multipart/form-data header must be set. The image should be included under the key image, and the receipt JSON should be included under the key receipt. For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL data without image:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-d @{PATH TO YOUR RECEIPT JSON}

cURL data and image:

curl -v -k -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-F "receipt=<{PATH TO YOUR RECEIPT JSON};type=application/json" \
-F "image=@{PATH TO YOUR IMAGE};type={FILE MIME TYPE OF YOUR IMAGE}"

HTTPie data without image:

http POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
"Authorization:Bearer {YOUR ACCESS TOKEN}" \
"Content-Type: application/json" \
"link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
< {PATH TO YOUR RECEIPT JSON}

Example Response:

HTTP/1.1 201 Created
Link: <http://schema.concursolutions.com/car-rental-receipt.schema.json>; rel="describedBy", <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get a Receipt by ID

GET /v4/:receiptId

Returns the JSON receipt associated with the ID in the URL.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

{
  "dateTimeReceived": "2016-09-28T21:41:21.087Z",
  "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
  "image": "",
  "receipt": {
    ...Receipt JSON...
  },
  "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
  "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
  "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
  "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
}

Back to Top

Endpoint: Get Receipts By UserId

GET /v4/users/:userId

Returns all receipts for a given user ID.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "receipts": [
    {
      "dateTimeReceived": "2016-09-28T21:41:21.087Z",
      "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "dateTimeReceived": "2016-09-28T19:59:30.488Z",
      "id": "df8c1161d917439c9e6f141fd0d6b588",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/df8c1161d917439c9e6f141fd0d6b588",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    ...
  ]
}

Back to Top

Endpoint: Get Receipt Image

GET /v4/:receiptId/image

If an image or PDF document was generated by or POSTed to Receipts v4, this endpoint can return the image in the same format that it was originally received by the API. Images for receipts created with v3 of the API are not accessible via this endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top

Image-Only Receipts

Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Endpoint: Post an Image-Only Receipt

POST /v4/users/:userId/image-only-receipts

Successful POST requests will receive a response of 202 Accepted. The Location header of the response contains a URL for your receipt image. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt image.

Helpful Notes:

• The header must include content-type with multipart/form-data as its value
• In the body, add “image” as a key and select “file” from the dropdown since you will be linking an image file. Then, choose your saved image file as the value.

For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN}/image-only-receipts \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-F "image=@{PATH TO YOUR IMAGE};type=image/{FILE MIME TYPE OF YOUR IMAGE}"

Example Response:

HTTP/1.1 202 Accepted
Link: <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/images/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get Image-Only Receipts By UserId

GET /v4/users/:userId/image-only-receipts

Returns the JSON metadata of receipt images for the user ID specified in the URL. Results should be paginated in the same manner as the e-receipt endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

HTTP/1.1 200 OK
Content-Length: 800
Connection: keep-alive

{
	"receiptsImages": [
	    {
	        "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
	        "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
	        "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
	        "userId": "abcd123456efg"
	    },
	    { ... },
	],
	"next": "https://us.api.concursolutions.com/receipts/v4/users/abcd123456efg/image-only-receipts/page/1507587575592_d4721b2f3b304a9a9325fabdad5f50ad"
}

Back to Top

Endpoint: Get an Image-Only Receipt by ID

GET /v4/image-only-receipts/:receiptId

Returns the JSON metadata associated with the ID in the URL.

Example Requests:

cURL:

curl -v -X GET https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}"

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

HTTP/1.1 200 OK
Content-Length: 272
Connection: keep-alive

{
    "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
    "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
    "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
    "userId": "abcd123456efg"
}

Back to Top

Endpoint: Get Receipt Image (Image-Only)

GET /v4/image-only-receipts/:receiptId/image

Returns the image in the same format that it was originally received by the API (image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, or application/pdf).

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top