Endpoints

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.

General

Endpoint Response Format Request Summary
GET / JSON Get service index URLs
GET /v4/status/:receiptId JSON Get the status of a receipt
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 Response Format Request Summary
GET /schemas JSON Get currently supported receipt schemas
POST /v4/users/:userId N/A Post a receipt
GET /v4/users/:userId JSON Get a user’s receipts
GET /v4/:receiptId JSON Get a receipt by ID
GET /v4/:receiptId/image image file Get a receipt image.
Endpoint: Schemas
GET /schemas/:schemaId
Parameter Requirement Value
schemaId optional The ID of the schema to be returned.

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
Parameter Requirement Value
receiptId required The id of the receipt associated with the image.

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:

Type Message
INFO Receipt accepted. Queued for processing.
INFO Initiated receipt processing. (event for each attempt)
ERROR Error from User Profile service. Queued for reprocessing.
ERROR Error from Imaging service. Queued for reprocessing.
ERROR Error during image generation or retrieval. Queued for reprocessing.
INFO Receipt image generated.
ERROR Processing failed.
INFO Processing finished.

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
Parameter Requirement Value
userId required The id of the user to whom the receipt belongs.
receipt required The JSON receipt to be posted.
image optional Image of the receipt. If an image isn’t provided, one will be generated automatically from the JSON.

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, 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.

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, 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. Image files are limited to a maximum size of 5MB. Accepted file formats for image files are: image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, and application/pdf.

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
Parameter Requirement Value
receiptId required The id of the receipt to be returned.

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
Parameter Requirement Value
userId required The id of the user whose receipts will be returned.

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
Parameter Requirement Value
receiptId required The id of the receipt associated with the 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

Endpoint Response Format Request Summary
POST /v4/users/:userId/image-only-receipts N/A Post an image-only receipt
GET /v4/users/:userId/image-only-receipts JSON Get a user’s image-only receipts
GET /v4/image-only-receipts/:receiptId JSON Get an image-only receipt by ID
Endpoint: Post an Image-Only Receipt
POST /v4/users/:userId/image-only-receipts
Parameter Requirement Value
userId required The id of the user to whom the receipt image belongs.
image required Image of the receipt.
  • Image constraints
    • Image size must not exceed 5MB
    • Image must be one of the supported file types: image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, and application/pdf

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.

Helfpul 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.

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
Parameter Requirement Value
userId required The id of the user whose receipt images will be returned.

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
Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

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
Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

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