Budget Category

This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.

GET All Budget Categories

Retrieve a list of all budget categories.

Scopes

This API call requires one of the following scopes:

budgetitem.read - Refer to Scope Usage for full details.
budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET /budget/v4/budgetCategory

Parameters

N/A

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c

[
    {
      "name":"Marketing and Outreach",
      "description":null,
      "statusType":"OPEN",
      "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
      "expenseTypes":[
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"MKTG",
          "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
          "name":null
        },
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"SEMNR",
          "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
          "name":null
        },
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"ADVT",
          "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
          "name":null
        }
      ]
    },
    {
      "name":"Airfare",
      "description":null,
      "statusType":"OPEN",
      "id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
      "expenseTypes":[
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"AIRFR",
          "id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
          "name":null
        },
        {
          "featureTypeCode":"REQUEST",
          "expenseTypeCode":"AIRFR",
          "id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
          "name":null
        }
      ]
    }     
]

GET a Budget Category

Retreive the details of a single budget category.

Scopes

This API call requires one of the following scopes:

budgetitem.read - Refer to Scope Usage for full details.
budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/{id}

Parameters

Name	Type	Format	Description
id	`string`	`uuid`	The budget category’s key field.

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1

{
  "name":"Marketing and Outreach",
  "description":null,
  "statusType":"OPEN",
  "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
  "expenseTypes":[
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"MKTG",
      "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
      "name":null
    },
    {
      "featureTypeCode":"EXPENSE",
      "expenseTypeCode":"SEMNR",
      "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
      "name":null
    },
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"ADVT",
      "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
      "name":null
    }
  ]
}

POST a Budget Category

Save a new budget category or update an existing budget category.

When adding expense types to a budget category, only the feature type code and expense type code are needed.
Since Expense Report expense types are shared with Request and Payment Request (Invoice) expense types are shared with Purchase Request, only EXPENSE and PAYMENT_REQUEST expense types must be supplied. The types will be copied to REQUEST and PURCHASE REQUEST automatically.
If an expense type is supplied but the feature is not enabled, it will have no effect. For example, an Invoice-Maintenance expense type can be added to a Budget Category if Invoice is not enabled for Budget–it will not change how spending is assigned to budgets.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Budget Category

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Budget Category or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Advertising Category",
  "description": "Advertising",
  "expenseTypes": [
    {
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT"
    },
    {
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT"
    }
  ],
  "statusType": "OPEN"
}

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4

{
  "name": "Advertising Category",
  "description": "Advertising",
  "id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
  "statusType": "OPEN",
  "expenseTypes": [
    {
      "id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT",
      "name": null
    },
    {
      "id": "67253ac1-77e0-4d61-a478-0d194611b320",
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT",
      "name": null
    }
  ]
}

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
      "errorMessage" : "Budget category name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
      "errorMessage" : "Budget category must have a unique name"
    }
  ]
}

DELETE a Budget Category

Delete a budget category. Budget categories that are in use by budget items may not be deleted.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

DELETE  /budget/v4/budgetCategory/{id}

Parameters

Name	Type	Format	Description
id	`string`	`uuid`	The budget category’s key field.

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
404 Not Found The resource could not be found or does not exist.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

GET All Valid Expense Types

Retrieve a list of all possible expense types that may be used in a budget category.

The list for REQUEST expense types is identical to the list for EXPENSE expense types and similarly PURCHASE_REQUEST is identical to PAYMENT_REQUEST. Due to response size and performance concerns, only EXPENSE and PAYMENT_REQUEST are returned and the caller should assume that identical expense types exist for REQUEST and PURCHASE_REQUEST.

Scopes

This API call requires one of the following scopes:

budgetitem.read - Refer to Scope Usage for full details.
budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

GET  /budget/v4/budgetCategory/expenseTypes

Parameters

N/A

Headers

Response

Status Codes

200 OK Successful call, response is in body.
400 Bad Request The request was determined to be invalid by the server.
403 Forbidden The user does not have the necessary permissions to perform the request.
500 Internal Server Error Error message in response body.
504 Gateway Timeout Error message in response body.

Headers

Response Headers

Payload

Expense Type

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023

[
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRFR",
    "id":null,
    "name":"Airfare"
  },
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRTX",
    "id":null,
    "name":"Airfare Ticket Tax"
  },
  {
    "featureTypeCode":"PAYMENT_REQUEST",
    "expenseTypeCode":"CATER",
    "id":null,
    "name":"Catering"
  }
]

Schema

BudgetCategory

Name	Type	Format	Description
`description`	`string`	-	The friendly name for this category.
`expenseTypes`	`array`	`expenseType`	Required The list of expense types that this budget category matches.
`name`	`string`	-	Required The admin-facing name for this category.
`statusType`	`string`	-	The status of this budget category. Supported values: `OPEN`, `REMOVED`
`id`	`string`	-	The unique identifier for the budget category.

ExpenseType

Name	Type	Format	Description
`featureTypeCode`	`string`	-	Required The type of feature that this expense type applies to: Purchase Request, Payment Request (Invoice), Expense, or Travel Authorization. Supported values: `PURCHASE_REQUEST`, `PAYMENT_REQUEST`, `EXPENSE`, `REQUEST`
`expenseTypeCode`	`string`	-	Required The alphanumeric code that describes an expense type (Example: `MEALS`, `AC_CATER`). Any string may be used, but only expense type codes returned by GET /budgetCategory/expenseType will behave properly in the SAP Concur UI.
`name`	`string`	-	READ ONLY The name for this expense type if it maps to an expense type set up in SAP Concur.
`id`	`string`	-	The budget service’s key for this object. If this field is not supplied, the service will use an existing expense type entry if one exists.

Error Response

Name	Type	Format	Description
`status`	`boolean`	-	`False` if there was an error.
`errorMessageList`	`array`	`errorMessage`	List of all errors detected.

Error Message

Name	Type	Format	Description
`errorType`	`String`	-	WARNING or ERROR.
`errorCode`	`String`	-	Text code for this error.
`errorMessage`	`String`	-	Plain language error message.

Response 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
RFC 7231 Allow
RFC 7234 Cache-Control
RFC 7230 Content-Length
RFC 7231 Content-Type
RFC 7231 Date
RFC 7234 Expires
RFC 7232 ETag
RFC 7234 Pragma
RFC 7231 Server
RFC 7231 Vary

Budget Category

GET All Budget Categories

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

GET a Budget Category

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

POST a Budget Category

Scopes

Request

URI

Template

Parameters

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

Response

Success Response

Failure Response

DELETE a Budget Category

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Example

Request

Response

GET All Valid Expense Types

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

Schema

BudgetCategory

ExpenseType

Error Response

Error Message

Response Headers

On this page