The Allocations API can be used to read the allocations that belong to a specific expense on an expense report and modify an allocation on an existing expense in an expense report. This API can be used to change custom field attributes, etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Prior Versions

  • Allocations v3 documentation is available here

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition

Scope Usage

Required Scopes:

Name Description Endpoint
expense.report.read Get information about expense reports. GET
expense.report.readwrite Read and write expense report headers. PATCH
user.read Get User Information, necessary for userID. GET

Optional Scope:

Name Description Endpoint
spend.listitem.read Read only access to spend list items listItemId. GET
spend.list.read Read only access to spend list and category details. GET

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

Access Token Usage

This API supports both company level and user level access tokens.

Retrieve Allocations of an Expense ID on a Specific Report ID

Retrieves the allocations that belong to a specific expense ID on a specific report ID.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/allocations

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER
reportId string - Required The unique identifier of the report to which the expense entry belongs whose allocations are being retrieved.
expenseId string - Required The unique identifier of the expense entry whose allocations are being retrieved.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/29EE3C62F5D844458828A5C1086072D1/allocations' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'

Response

200 OK

[
    {
        "customData": [
            {
                "id": "custom9",
                "value": "D3954B47BCEC9446A4FFC49E0000B46E",
                "isValid": true
            }
        ],
        "allocationId": "3BBB494511E1C74DA04469C45B039871",
        "accountCode": "Pending Client",
        "overLimitAccountCode": null,
        "allocationAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "approvedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "claimedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "expenseId": "29EE3C62F5D844458828A5C1086072D1",
        "isSystemAllocation": false,
        "isPercentEdited": false,
        "percentage": 50.00000000
    },
    {
        "customData": [
            {
                "id": "custom9",
                "value": "88EACA3116581248BCE27956DE67647D",
                "isValid": true
            }
        ],
        "allocationId": "4DB06B4360E31443AD43ED52B2AE007E",
        "accountCode": "Pending Client",
        "overLimitAccountCode": null,
        "allocationAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "approvedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "claimedAmount": {
            "value": 250.00,
            "currencyCode": "USD"
        },
        "expenseId": "29EE3C62F5D844458828A5C1086072D1",
        "isSystemAllocation": false,
        "isPercentEdited": false,
        "percentage": 50.00000000
    }
]

Retrieve an Allocation by ID

Retrieves the details of the specific allocation of an expense entry on a report.

Scopes

expense.report.read - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this allocation belongs.
allocationId string - Required The unique identifier of the allocation that is being retrieved.

Headers

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'

Response

200 OK

{
    "customData": [
        {
            "id": "custom9",
            "value": "D3954B47BCEC9446A4FFC49E0000B46E",
            "isValid": true
        }
    ],
    "allocationId": "3BBB494511E1C74DA04469C45B039871",
    "accountCode": "Pending Client",
    "overLimitAccountCode": null,
    "allocationAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "approvedAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "claimedAmount": {
        "value": 250.00,
        "currencyCode": "USD"
    },
    "expenseId": "29EE3C62F5D844458828A5C1086072D1",
    "isSystemAllocation": false,
    "isPercentEdited": false,
    "percentage": 50.00000000
}

Update a Specific Allocation

Updates the attributes of a specific allocation.

Scopes

expense.report.readwrite - Refer to Scope Usage for full details.

Request

URI Template

https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY
reportId string - Required The unique identifier of the report to which this allocation belongs.
allocationId string - Required The unique identifier of the allocation that is being retrieved.

Headers

REST Design Specification

PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "allocation":{
    "customData": [
        {
            "id": "custom9",
            "value": "058713001E2CD943824280D9275FDC3F",
            "isValid": true
        }
    ]
    },

    "expenseIds": ["29EE3C62F5D844458828A5C1086072D1"]

}'

Response

204 No Content

Schema

ReportAllocationResponse

Name Type Format Description
accountCode string - The ledger account code associated with the allocation.
allocationAmount Amount - The amount of the allocation.
allocationId string - Required The unique identifier of the allocation.
approvedAmount Amount - The pro-rated amount of the allocation approved for reimbursement based on the approved expense amount.
claimedAmount Amount - The amount of the allocation requested for reimbursement.
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
expenseId string - Required The unique identifier of the expense associated with the allocation.
isPercentEdited boolean true/false Required Whether the allocation percent has been edited.
isSystemAllocation boolean true/false Required Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only.
overLimitAccountCode string - The ledger account code associated with the allocation if it exceeds a pre-defined threshold, for example, the user’s travel allowance limit.
percentage number double Required The percentage of the total expense that this allocation represents.

CustomData

Name Type Format Description
id string - Required The unique identifier of the custom field. Examples: custom1, orgUnit1
isValid boolean true/false Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true
value string - The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user’s assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona
value number double Required The amount in the defined currency.

UpdateReportAllocation

Name Type Format Description
allocation UpdateAllocation - Required This is an allocation custom data object to be updated.
expenseIds string - Required This is an array of unique identifiers of expenses within this report that are being updated.

UpdateAllocation

Name Type Format Description
customData CustomData - The details from the customData fields. These fields may not have data, depending on the configuration.
Name Type Format Description
deprecation string - -
href string - Required The URL of the related HATEOAS link that you can use for subsequent calls.
hreflang string - -
isTemplated boolean true/false Required Whether the href is parameterized.
media string - -
method string - Required The HTTP method required for the related call.
rel string - Required The link relationship that describes how the href relates to the API call.
title string - -
type string - -

ErrorMessage

Name Type Format Description
errorId string - The unique identifier of the error associated with the response.
errorMessage string - Required The detailed error message.
httpStatus string - Required The http response code and phrase for the response.
path string - Required The URI of the attempted request.
timestamp string date-time Required The time when the error was captured.
validationErrors ValidationError - The validation error messages.

ValidationError

Name Type Format Description
id string - The ID of the validation error.
message string - The detailed message of the validation error.
source string - The type of validation which failed.