title: Budget v4 - Budget Item layout: reference

Budget Item

This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.

GET All Budget Items

Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.

Use responseSchema=compact if you need to call this API frequently. In compact version, below attributes (the less frequently changed ones) would not be returned. To fetch these details for specific budget you can use GET a Budget Item
- managers
- approvers
- viewers
- team members
- fiscal periods

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/budgetItemHeader

Parameters

Name	Type	Format	Description
`adminView`	`boolean`	`query`	If `true`, returns all budgets for this entity, if `false`, returns only the budgets owned by the current user. Default: `false`
`offset`	`integer`	`query`	The start of the page offset. Default: `0`
`responseSchema`	`string`	`query`	If 'COMPACT', response excludes less frequently changed ones i.e managers, approvers, viewers, team members and fiscal periods. Defaults to 'non-compact' schema

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 Item Header List

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
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: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2

{
  "totalRows":122,"offset":0,"limit":50,
  "budgetItemHeaders":[
    {
        "name":"Marketing-US-Jean Normandy",
        "isTest":false,
        "budgetItemStatusType":"OPEN",
        "description":"Marketing-US",
        "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "costObjects":[
         {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
        ],
        "periodType":"YEARLY",
        "active":true,
        "owned":false,
        "budgetAmounts":{
          "pendingAmount":1178.37697091,
          "unExpensedAmount":2310.73578092,
          "spendAmount":35.78378912,
          "adjustedBudgetAmount": 0,
          "availableAmount":8785.83923997,
          "unExpensedSettings":null,
          "threshold":"UNDER",
          "consumedPercent":12
        },
        "createdDate": "2019-06-26T17:49:53.102Z",
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "annualBudget":10000.00000000,
        "budgetCategory":{
          "name":"airfare",
          "description":null,
          "statusType":"OPEN",
          "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
        },
        "owner":{
          "externalUserCUUID":"8002250890004822936",
          "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
          "id":"f779261d-77ce-4123-b739-d842ef6f104d",
          "name":"Jean Normandy",
          "email":"[email protected]",
          "employeeId":"jean.normandy"
         },
        "budgetApprovers":[
	      {
            "externalUserCUUID":"8002250890004822936",
            "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
            "id":"f779261d-77ce-4123-b739-d842ef6f104d",
            "name":"Jean Normandy",
            "email":"[email protected]",
            "employeeId":"jean.normandy"
          }
        ],
        "budgetManagers":[
	      {
            "externalUserCUUID":"1563846384638464842",
            "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
            "id":"e2bae688-e000-464a-8728-e1362c94f172",
            "name":"Walter Gupta",
            "email":"[email protected]",
            "employeeId":"walter.gupta"
          }
        ],
        "budgetType": "PERSONAL_USE",
        "budgetViewers":[
          {
            "externalUserCUUID":"5005380230004873464",
            "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
            "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
            "name":"Dan Lee",
            "email":"[email protected]",
            "employeeId":"dan.lee"
          }
        ],
        "dateRange": null,
        "fiscalYear":{
          "name":"2017",
          "displayName":"2017",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "status":"OPEN",
          "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
          "lastModified":"2017-03-26 20:53:19",
          "currentYear":false
        }
      },
    {"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
  ],
  "href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
  "next":{
    "href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
  },
  "previous":null
}

GET a Budget Item

Retrieve the details of a single budget item.

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/budgetItemHeader/{id}

Parameters

Name	Type	Format	Description
`id`	`string`	`uuid`	The budget item header'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 Item Header

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

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: 918cfb55-06a1-47da-8ef1-774a45427af9

 {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
    ],
    "periodType":"QUARTERLY",
    "active":true,
    "owned":false,
    "budgetAmounts":{
      "pendingAmount":6870.48165307,
      "unExpensedAmount":102126.89000000,
      "spendAmount":764.86966050,
      "adjustedBudgetAmount": 0,
      "availableAmount":2364.64868643,
      "unExpensedSettings":null,
      "threshold":"UNDER",
      "consumedPercent":76
    },
    "createdDate": "2019-06-26T17:49:53.102Z",
    "currencyCode":"EUR",
    "annualBudget":10000.00000000,
    "budgetCategory":null,
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "id":"f779261d-77ce-4123-b739-d842ef6f104d",
      "name":"Jean Normandy",
      "email":"[email protected]",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
       {
        "externalUserCUUID":"8002250890004822936",
        "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
        "id":"f779261d-77ce-4123-b739-d842ef6f104d",
        "name":"Jean Normandy",
        "email":"[email protected]",
        "employeeId":"jean.normandy"
       }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "id":"e2bae688-e000-464a-8728-e1362c94f172",
        "name":"Walter Gupta",
        "email":"[email protected]",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
        "name":"Dan Lee",
        "email":"[email protected]",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"USD",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":6870.48165307,
          "unExpensedAmount":102126.89000000,
          "spendAmount":764.86966050,
          "adjustedBudgetAmount": 0,
          "availableAmount":-5135.35131357,
          "unExpensedSettings":null,
          "consumedPercent":305,
          "threshold":"OVER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "currentPeriod":false
        },
        "budgetItemBalances":[
          {
            "featureTypeCode":"PURCHASE_REQUEST",
            "featureTypeSubCode":"NONE",
            "workflowState":"SUBMITTED",
            "amount":6870.48165307,
            "id":"11cb732e-cbc4-41cb-82be-162d632d5499"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"NONE",
            "workflowState":"PAID",
            "amount":764.86966050,
            "id":"0f09cc65-b879-4969-a8a1-9dd52c96486d"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"ERECEIPTS",
            "workflowState":"UNSUBMITTED",
            "amount":102126.89000000,
            "id":"27c49c8a-c24d-42eb-b089-84268350ae03"
          }
        ]
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":0,
          "unExpensedAmount":0,
          "spendAmount":0,
          "adjustedBudgetAmount": 0,
          "availableAmount":2500.00000000,
          "unExpensedSettings":null,
          "consumedPercent":0,
          "threshold":"UNDER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q2",
          "fiscalPeriodStatus":"OPEN",
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19",
          "periodType":"QUARTERLY",
          "startDate":"2017-04-01",
          "endDate":"2017-06-30",
          "spendDate":null,
          "currentPeriod":true
        },
        "budgetItemBalances":[]
      },
      {
        "Additional budget item details removed for brevity": "Additional budget item details removed for brevity"
      }
    ],
    "dateRange": null,
    "fiscalYear":{
      "name":"2017",
      "displayName":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "currentPeriod":false
        },
        {
        "name":"2017-Special - Q2",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-04-01",
        "endDate":"2017-06-30",
        "spendDate":null,
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q3",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-07-01",
        "endDate":"2017-09-30",
        "spendDate":null,
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q4",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-10-01",
        "endDate":"2017-12-31",
        "spendDate":null,
        "currentPeriod":false
      }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[]
    }
  }

Get Team Budget Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/06bb0160-1eae-41ce-a43e-e616a1ba8213
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Thu, 02 Sep 2021 17:46:31 GMT
Etag: W/"b8a-qZk3TN9hBDgNDyTg0+HMD47/QlE"
Expires: Thu, 02 Sep 2021 17:46:31 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: fa0b0152-157d-4d8b-98a2-228878a2b60d

 {
     "name": "TestTeamBudget1",
     "isTest": false,
     "budgetType": "TEAM",
     "budgetItemStatusType": "OPEN",
     "description": "TestTeamBudget1",
     "syncGuid": "06bb0160-1eae-41ce-a43e-e616a1ba8213",
     "lastModifiedDate": "2021-08-23T17:50:19.000+0000",
     "createdDate": "2021-08-23T17:50:19.000+0000",
     "costObjects": [],
     "periodType": "YEARLY",
     "active": true,
     "owned": null,
     "currencyCode": "USD",
     "budgetAmounts": {
         "pendingAmount": 69.01000000,
         "unExpensedAmount": 12.00000000,
         "spendAmount": 0,
         "availableAmount": 1480.99000000,
         "unExpensedSettings": null,
         "adjustedBudgetAmount": 0,
         "threshold": "UNDER",
         "consumedPercent": 4
     },
     "annualBudget": 1550.00000000,
     "id": "06bb0160-1eae-41ce-a43e-e616a1ba8213",
     "budgetCategory": null,
     "owner": {
         "employeeUuid": "F06D36B8AA9046358B8778D3B2A14FCF",
         "name": "Master, budget ",
         "email": "[email protected]",
         "employeeId": null,
         "externalUserCUUID": "8000011190000003453",
         "id": "f5089008-7f04-441a-979a-77545116fedc"
     },
     "budgetManagers": [],
     "budgetApprovers": [],
     "budgetViewers": [
         {
             "employeeUuid": "F06D36B8AA9046358B8778D3B2A14FCF",
             "name": "Master, budget ",
             "email": "[email protected]",
             "employeeId": null,
             "externalUserCUUID": "8000011190000003453",
             "id": "f5089008-7f04-441a-979a-77545116fedc"
         }
     ],
     "budgetTeamMembers": [
         {
             "budgetPerson": {
                 "employeeUuid": "F06D36B8AA9046358B8778D3B2A14FCF",
                 "name": "Master, budget ",
                 "email": "[email protected]",
                 "employeeId": null,
                 "externalUserCUUID": "8000011190000003453",
                 "id": "f5089008-7f04-441a-979a-77545116fedc"
             },
             "startDate": null,
             "endDate": null,
             "active": "NOT_ENROLLED",
             "status": "EXISTING"
         },
         {
             "budgetPerson": {
                 "employeeUuid": "DEE1652BAF6B4C778FF87FF18DB7E97D",
                 "name": "test1, budget ",
                 "email": "[email protected]",
                 "employeeId": null,
                 "externalUserCUUID": "8000011190000074961",
                 "id": "338deab8-7c51-4f4e-a5d9-be51b5f60df1"
             },
             "startDate": "2020-12-31",
             "endDate": "2021-12-31",
             "active": "FULLY_ENROLLED",
             "status": "EXISTING"
         },
         {
             "budgetPerson": {
                 "employeeUuid": "9D11DEB6D3164A54BD02AFDBFBDB6922",
                 "name": "test2, budget ",
                 "email": "[email protected]",
                 "employeeId": null,
                 "externalUserCUUID": "8000011190000074962",
                 "id": "5b426431-b6b7-4e0f-9a57-a917470ccba2"
             },
             "startDate": "2020-12-31",
             "endDate": "2021-08-31",
             "active": "PARTIALLY_ENROLLED",
             "status": "EXISTING"
         },
         {
             "budgetPerson": {
                 "employeeUuid": "18FEAFCDCA7644688EAF21CFE14916DF",
                 "name": "Manager, Jane ",
                 "email": "",
                 "employeeId": null,
                 "externalUserCUUID": "8000011190000134890",
                 "id": "a1940642-3ffd-4abf-87b4-f133e9e09229"
             },
             "startDate": "2020-12-31",
             "endDate": "2021-12-31",
             "active": "FULLY_ENROLLED",
             "status": "REMOVED"
         },
         {
             "budgetPerson": {
                 "employeeUuid": "657C9DA074C94006B995D2FC488F2C8C",
                 "name": "approver two",
                 "email": "[email protected]",
                 "employeeId": "budgetapprover2",
                 "externalUserCUUID": "8000011190000074765",
                 "id": null
             },
             "startDate": null,
             "endDate": null,
             "active": "NOT_ENROLLED",
             "status": "NEW"
         }
     ],
     "budgetItemDetails": [
         {
             "budgetName": "TestTeamBudget1",
             "currencyCode": "USD",
             "amount": 1550.00000000,
             "syncGuid": "c7bd7322-1783-469e-84b3-8bc8f27505e7",
             "budgetItemDetailStatusType": "OPEN",
             "budgetItemHeaderSyncGuid": "06bb0160-1eae-41ce-a43e-e616a1ba8213",
             "id": "c7bd7322-1783-469e-84b3-8bc8f27505e7",
             "budgetAmounts": {
                 "pendingAmount": 69.01000000,
                 "unExpensedAmount": 12.00000000,
                 "spendAmount": 0,
                 "availableAmount": 1480.99000000,
                 "unExpensedSettings": true,
                 "adjustedBudgetAmount": 0,
                 "threshold": "UNDER",
                 "consumedPercent": 4
             },
             "budgetItemHeaderId": "06bb0160-1eae-41ce-a43e-e616a1ba8213",
             "fiscalPeriod": {
                 "name": "2021",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "f80111fa-e875-4076-90e7-4be694a685fd",
                 "periodType": "YEARLY",
                 "startDate": "2020-12-31",
                 "endDate": "2021-12-31",
                 "spendDate": null,
                 "id": "f80111fa-e875-4076-90e7-4be694a685fd",
                 "currentPeriod": true
             },
             "budgetItemBalances": [
                 {
                     "featureTypeCode": "EXPENSE",
                     "featureTypeSubCode": "NONE",
                     "workflowState": "APPROVED",
                     "amount": 69.01000000,
                     "id": "b3e384b8-3220-4d0a-a272-6524c1d2ebc7"
                 },
                 {
                     "featureTypeCode": "EXPENSE",
                     "featureTypeSubCode": "NONE",
                     "workflowState": "UNSUBMITTED",
                     "amount": 12.00000000,
                     "id": "b602d66c-1036-46cf-88a5-faf2c43369fd"
                 }
             ]
         }
     ],
     "fiscalYear": {
         "name": "2021",
         "startDate": "2020-12-31",
         "endDate": "2021-12-31",
         "status": "OPEN",
         "syncGuid": "dc4cc780-d9f4-4a99-a13d-67e6ff439aba",
         "lastModified": "2021-02-24 20:02:33",
         "displayName": "2021",
         "id": "dc4cc780-d9f4-4a99-a13d-67e6ff439aba",
         "currentYear": true,
         "monthlyFiscalPeriods": [
             {
                 "name": "2021 - Nov",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "399ee81f-9ffd-487f-bc15-a75c2cc31a9a",
                 "periodType": "MONTHLY",
                 "startDate": "2021-11-28",
                 "endDate": "2021-12-27",
                 "spendDate": null,
                 "id": "399ee81f-9ffd-487f-bc15-a75c2cc31a9a",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Jul",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "2989f5f6-d777-4277-92b3-1375a94f8102",
                 "periodType": "MONTHLY",
                 "startDate": "2021-07-28",
                 "endDate": "2021-08-27",
                 "spendDate": null,
                 "id": "2989f5f6-d777-4277-92b3-1375a94f8102",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Dec2",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "9dc219f6-558c-4fc8-855e-bdabf95c4e13",
                 "periodType": "MONTHLY",
                 "startDate": "2021-12-28",
                 "endDate": "2021-12-31",
                 "spendDate": null,
                 "id": "9dc219f6-558c-4fc8-855e-bdabf95c4e13",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Mar",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "e25f142d-9a1e-450d-a4bf-fe53b1c43e0b",
                 "periodType": "MONTHLY",
                 "startDate": "2021-03-28",
                 "endDate": "2021-04-27",
                 "spendDate": null,
                 "id": "e25f142d-9a1e-450d-a4bf-fe53b1c43e0b",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Apr",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "ce64f5f8-5b9c-475e-8606-3e8d8141bdbf",
                 "periodType": "MONTHLY",
                 "startDate": "2021-04-28",
                 "endDate": "2021-05-27",
                 "spendDate": null,
                 "id": "ce64f5f8-5b9c-475e-8606-3e8d8141bdbf",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Feb",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "ebc13849-2c33-4160-a7b5-ad655d944eed",
                 "periodType": "MONTHLY",
                 "startDate": "2021-02-28",
                 "endDate": "2021-03-27",
                 "spendDate": null,
                 "id": "ebc13849-2c33-4160-a7b5-ad655d944eed",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Dec",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "504917d8-d7c9-4176-9762-af56c5b84022",
                 "periodType": "MONTHLY",
                 "startDate": "2020-12-31",
                 "endDate": "2021-01-30",
                 "spendDate": null,
                 "id": "504917d8-d7c9-4176-9762-af56c5b84022",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Oct",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "77d87019-5ae2-49cb-8759-8791802ecf77",
                 "periodType": "MONTHLY",
                 "startDate": "2021-10-28",
                 "endDate": "2021-11-27",
                 "spendDate": null,
                 "id": "77d87019-5ae2-49cb-8759-8791802ecf77",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - May",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "8f5997a4-107f-4079-be79-547f2e1360f5",
                 "periodType": "MONTHLY",
                 "startDate": "2021-05-28",
                 "endDate": "2021-06-27",
                 "spendDate": null,
                 "id": "8f5997a4-107f-4079-be79-547f2e1360f5",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Sep",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "dddf6c18-e1f1-4b78-b680-26ed296a3ded",
                 "periodType": "MONTHLY",
                 "startDate": "2021-09-28",
                 "endDate": "2021-10-27",
                 "spendDate": null,
                 "id": "dddf6c18-e1f1-4b78-b680-26ed296a3ded",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Jun",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "c0cfd89e-299d-4e4e-b51b-27cb8e2b38fa",
                 "periodType": "MONTHLY",
                 "startDate": "2021-06-28",
                 "endDate": "2021-07-27",
                 "spendDate": null,
                 "id": "c0cfd89e-299d-4e4e-b51b-27cb8e2b38fa",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Aug",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "4c40bf61-023b-4a09-b6a7-762f9939809e",
                 "periodType": "MONTHLY",
                 "startDate": "2021-08-28",
                 "endDate": "2021-09-27",
                 "spendDate": null,
                 "id": "4c40bf61-023b-4a09-b6a7-762f9939809e",
                 "currentPeriod": true
             },
             {
                 "name": "2021 - Jan",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "093b4db1-f3aa-484c-8005-39556c03ded0",
                 "periodType": "MONTHLY",
                 "startDate": "2021-01-31",
                 "endDate": "2021-02-27",
                 "spendDate": null,
                 "id": "093b4db1-f3aa-484c-8005-39556c03ded0",
                 "currentPeriod": false
             }
         ],
         "quarterlyFiscalPeriods": [
             {
                 "name": "2021 - Q1",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "3bd07af5-4db2-4bc9-ad06-1cc987ae5404",
                 "periodType": "QUARTERLY",
                 "startDate": "2020-12-31",
                 "endDate": "2021-03-27",
                 "spendDate": null,
                 "id": "3bd07af5-4db2-4bc9-ad06-1cc987ae5404",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Q4",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "8b287184-e7db-4b74-8c40-bb939d831022",
                 "periodType": "QUARTERLY",
                 "startDate": "2021-09-28",
                 "endDate": "2021-12-27",
                 "spendDate": null,
                 "id": "8b287184-e7db-4b74-8c40-bb939d831022",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Q2",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "fbb13ae4-ba14-4ebb-a87e-dde80e13322a",
                 "periodType": "QUARTERLY",
                 "startDate": "2021-03-28",
                 "endDate": "2021-06-27",
                 "spendDate": null,
                 "id": "fbb13ae4-ba14-4ebb-a87e-dde80e13322a",
                 "currentPeriod": false
             },
             {
                 "name": "2021 - Q3",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "73adc840-8990-4906-9696-c79f64a04b15",
                 "periodType": "QUARTERLY",
                 "startDate": "2021-06-28",
                 "endDate": "2021-09-27",
                 "spendDate": null,
                 "id": "73adc840-8990-4906-9696-c79f64a04b15",
                 "currentPeriod": true
             },
             {
                 "name": "2021 - Q5",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "444618e0-5cc1-4b5c-aef2-1b4c17f3390a",
                 "periodType": "QUARTERLY",
                 "startDate": "2021-12-28",
                 "endDate": "2021-12-31",
                 "spendDate": null,
                 "id": "444618e0-5cc1-4b5c-aef2-1b4c17f3390a",
                 "currentPeriod": false
             }
         ],
         "yearlyFiscalPeriods": [
             {
                 "name": "2021",
                 "fiscalPeriodStatus": "OPEN",
                 "syncGuid": "f80111fa-e875-4076-90e7-4be694a685fd",
                 "periodType": "YEARLY",
                 "startDate": "2020-12-31",
                 "endDate": "2021-12-31",
                 "spendDate": null,
                 "id": "f80111fa-e875-4076-90e7-4be694a685fd",
                 "currentPeriod": true
             }
         ],
         "customFiscalPeriods": []
     }
 }

POST a Budget Item

Save a new budget or update an existing budget. Due to performance considerations, we support header payload with maximum of 200 budget item details.

Scopes

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

Request

URI

Template

POST  /budget/v4/budgetItemHeader

Parameters

N/A

Headers

Payload

Budget Item Header

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 Item Save Response or Error Response

Example

Request

POST https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}

Quarterly Budget Example

  {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
      {
      "fieldDefinitionId":"86eee673-3d81-49c2-966a-b63c7a9302e2",
      "code": "6",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName":"Country Code"
    }
    ],
    "periodType":"QUARTERLY",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"[email protected]",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"[email protected]",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"[email protected]",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"[email protected]",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"35d7dc8a-5ec8-4d5f-ba7c-d9304f7afee3",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"09cd5be1-a21d-47f2-b6b5-8d9019709327"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4ec30f7c-e7fa-4832-9134-85bed9a85b9c",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"c3beec03-a096-4a33-b7af-b49127742702"
        }
      }
    ],
    "fiscalYear":{
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790"
    }
  }

Date Range Budget Example

  {
    "name":"Marketing-US-Jean Normandy Date Range",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
      "code": "6",
      "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName": "Country Code"
    }
    ],
    "periodType":"DATE_RANGE",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"[email protected]",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"[email protected]",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"[email protected]",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"[email protected]",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f7"
        }
      }
    ],
    "fiscalYear":{
      "id":null
    }
  }

Team Budget Example

Provide syncGuid when doing an update call. Also as of now we are not supporting approvers, managers and tracking field options for Team Budgets. So you do not have to pass values for those fields.

  {
      "name": "TestTeamBudget",
      "isTest": false,
      "budgetType": "TEAM",
      "budgetItemStatusType": "OPEN",
      "description": "TestTeamBudget",
      "syncGuid": null,
      "costObjects": [],
      "periodType": "YEARLY",
      "active": true,
      "currencyCode": "USD",
      "annualBudget": 1550.00000000,
      "budgetCategory": null,
      "owner": {
          "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
          "name": "Processor Budget_2025",
          "email": "[email protected]",
          "employeeId": "Processor",
          "externalUserCUUID": "8000346700001286382",
          "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
      },
      "budgetViewers": [
          {
            "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
            "name": "Processor Budget_2025",
            "email": "[email protected]",
            "employeeId": "Processor",
            "externalUserCUUID": "8000346700001286382",
            "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
          }
      ],
      "budgetTeamMembers": [
          {
              "syncGuid": null,
              "budgetPerson": {
                  "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
                  "name": "Processor Budget_2025",
                  "email": "[email protected]",
                  "employeeId": "Processor",
                  "externalUserCUUID": "8000346700001286382",
                  "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
              },
              "startDate": null,
              "endDate": null,
              "active": "NOT_ENROLLED"
          },
          {
              "syncGuid": null,
              "budgetPerson": {
                  "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
                  "name": "Processor Budget_2025",
                  "email": "[email protected]",
                  "employeeId": "Processor",
                  "externalUserCUUID": "8000346700001286382",
                  "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
              },
              "startDate": "2020-12-31",
              "endDate": "2021-12-31",
              "active": "FULLY_ENROLLED"
          },
          {
              "syncGuid": null,
              "budgetPerson": {
                  "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
                  "name": "Processor Budget_2025",
                  "email": "[email protected]",
                  "employeeId": "Processor",
                  "externalUserCUUID": "8000346700001286382",
                  "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
              },
              "startDate": "2020-12-31",
              "endDate": "2021-08-31",
              "active": "PARTIALLY_ENROLLED"
          },
          {
              "syncGuid": null,
              "budgetPerson": {
                  "employeeUuid": "2AEBAEAC9DC44A62A1D17503FF2B986F",
                  "name": "Processor Budget_2025",
                  "email": "[email protected]",
                  "employeeId": "Processor",
                  "externalUserCUUID": "8000346700001286382",
                  "id": "8d591cff-f745-4c93-9b3c-92d39229f61a"
              },
              "startDate": "2020-12-31",
              "endDate": "2021-12-31",
              "active": "FULLY_ENROLLED"
          }
      ],
      "budgetItemDetails": [
          {
              "budgetName": "TestTeamBudget",
              "currencyCode": "USD",
              "amount": 1550.00000000,
              "syncGuid": null,
              "budgetItemDetailStatusType": "OPEN",
              "budgetItemHeaderSyncGuid": null,
              "id": null,
              "budgetItemHeaderId": null,
              "fiscalPeriod": {
                  "id": "f80111fa-e875-4076-90e7-4be694a685fd"
              }
          }
      ],
      "fiscalYear": {
          "id": "dc4cc780-d9f4-4a99-a13d-67e6ff439aba"
      }
  }

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: 97
concur-correlationid: 809a0898-e523-4114-950d-bd22705a3b25

{
  "success": true,
  "budgetItemHeaderSyncGuid": "6f5c0189-f680-407b-b474-df917151a947",
  "budgetItemDetailSyncGuids": [
    "29e46a1e-ea18-43ef-80b1-4c311cdf0fe7"
  ]
}

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 459
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: cea62849-02e5-4a7f-a576-68280c84bd02

{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_REQUIRED",
      "errorMessage" : "Budget item name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_ERROR",
      "errorMessage" : "Budget item name should be more than 1 characters"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_OWNER_REQUIRED",
      "errorMessage" : "Budget item owner is required"
    }
  ]
}

DELETE a Budget Item Header

Delete a budget item.

Scopes

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

Request

URI

Template

DELETE  /budget/v4/budgetItemHeader/{id}

Parameters

Name	Type	Format	Description
`id`	`string`	`path`	The budget item header'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 Item Response or Error Response

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 97
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb

  {
    "success": true,
    "budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
  }

Schema

PagedBudgetItemHeaderList

Name	Type	Format	Description
`totalRows`	`integer`	-	The total number of rows available.
`offset`	`integer`	-	The starting row for this page of results (zero-based).
`limit`	`integer`	-	The number of results returned per page. Maximum: `50`
`budgetItemHeaders`	`array`	`budgetItemHeader`	List of budget item headers. Each budget item header represents a single budget for a fiscal year.
`href`	`string`	-	The link to this page of results.
`previous`	`string`	`href`	The `href` for the previous page of results (`null` if this is the first page of results).
`next`	`string`	`href`	The `href` for the next page of results (`null` if no results remaining).

BudgetItemHeader

Name	Type	Format	Description
`active`	`boolean`	-	READ ONLY Indicates if this budget should be displayed on user screens.
`annualBudget`	`decimal`	-	READ ONLY The total budget amount and accumulated balances for this budget header.
`budgetAmounts`	`array`	`budgetAmounts`	READ ONLY The accumulated budget amounts for this budget.
`budgetManagers`	`array`	`budgetPerson`	If managers exist, spend items only matches this budget if one of the managers is in the manager hierarchy of the submitter or approver for the given spend item.
`budgetApprovers`	`array`	`budgetPerson`	The workflow approvers for this budget.
`budgetTeamMembers`	`array`	`budgetItemBudgetTeam`	The team members associated with this budget.
`budgetCategory`	`array`	`budgetCategory`	The budget category for this budget item. If a budget category is present, spending items must match one of the expense types in the budget category in order to match this budget.
`budgetItemDetails`	`array`	`budgetItemDetail`	Required Specify the budget information for each fiscal period in the fiscal year.
`budgetItemStatusType`	`string`	-	The status of this budget item. Supported values: `OPEN`, `CLOSED`(no spending can be attached to this budget), `REMOVED`
`budgetType`	`string`	-	The budget type indicates if the budget item is personal or not. Supported values: `PERSONAL_USE`, `BUDGET`, `RESTRICTED`, `TEAM`
`budgetViewers`	`array`	`budgetPerson`	The users who can view this budget.
`costObjects`	`array`	`budgetTrackingValue`	The cost object list for matching spending items.
`createdDate`	`datetime`	-	READ ONLY The time the budget item header was created. Date in UTC.
`currencyCode`	`string`	-	The 3-letter ISO 4217 currency code for the budget currency. This is the currency code of the budget amount. Spending Items are converted using yesterday's closing value. 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.
`description`	`string`	-	Required The user-friendly name for this budget. This description is displayed to end users on desktop and mobile.
`dateRange`	`dateRange`	`dateRange`	READ ONLY Specify custom date range for budget.
`fiscalYear`	`array`	`fiscalYear`	Required The fiscal year for this budget. Only the ID of the fiscal year, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
`id`	`string`	-	The key for this object.
`isTest`	`boolean`	-	The test flag for the budget item. If `true`, this budget will only match spending submitted by test users.
`lastModifiedDate`	`datetime`	-	READ ONLY The last time the budget item header was updated. Date in UTC.
`name`	`string`	-	Required The admin-facing name for this budget.
`owned`	`string`	-	READ ONLY A flag indicating if the current user is the owner of this budget.
`owner`	`array`	`budgetPerson`	Required The user who is ultimately responsible for this budget.
`periodType`	`string`	-	READ ONLY The type of period within the fiscal year that this budget's details use.

BudgetItemDetail

Name	Type	Format	Description
`amount`	`decimal`	-	Required The budget currency amount allocated to this fiscal period. May be zero.
`budgetAmounts`	`array`	`budgetAmounts`	READ ONLY The accumulated budget numbers for this budget.
`budgetItemBalances`	`array`	`budgetItemBalance`	READ ONLY Shows the break-out of budget spending by product and workflow state.
`budgetItemDetailStatusType`	`string`	-	The status of this budget item. Supported values: `OPEN`, `CLOSED`(no spending can be attached to this budget), `REMOVED`
`currencyCode`	`string`	-	The 3-letter ISO 4217 currency code for the budget currency. 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.
`budgetName`	`string`	-	READ ONLY The admin-facing name of this budget.
`budgetItemHeaderId`	`string`	-	READ ONLY The unique ID of the header that contains this budget item detail.
`fiscalPeriod`	`fiscalPeriod`	-	Required The fiscal period for this budget amount. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
`detailDashboardBudgetItemAdjustmentDTOs`	`array`	`detailDashboardBudgetItemAdjustment`	READ ONLY List of budget adjustments.
`fiscalPeriod`	`array`	`fiscalPeriod`	Required The specific fiscal period when this budget amount will be used. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.

BudgetAmounts

Name	Type	Format	Description
`adjustedBudgetAmount`	`decimal`	-	READ ONLY The amount adjusted against this budget.
`availableAmount`	`decimal`	-	READ ONLY The available amount accumulated against this budget. Uses budget setting to determine which amounts are included to calculate available amount.
`consumedPercent`	`decimal`	-	READ ONLY The percentage of the budget that is considered used. Uses budget setting to determine which amounts to include.
`pendingAmount`	`decimal`	-	READ ONLY The pending amount accumulated against this budget.
`spendAmount`	`decimal`	-	READ ONLY The spent amount accumulated against this budget.
`threshold`	`string`	-	READ ONLY The indicator of whether this budget is under the alert limit, equal to or over the alert limit but under the control limit, or equal to or over the control limit. Supported values: `UNDER`, `ALERT`, `OVER`
`unExpensedAmount`	`decimal`	-	READ ONLY The amount of unexpensed items like travel bookings, quick expenses, or e-receipts.
`unExpensedSettings`	`string`	-	READ ONLY The company's budget setting for unexpensed items. Applies to all budgets for the company. Supported values: `SHOW_UNSUBMITTED_EXPENSES_AS_PENDING`, `SHOW_UNSUBMITTED_EXPENSES_BALANCE`, `DO_NOT_SHOW_UNSUBMITTED_EXPENSES`

BudgetPerson

Provide externalUserCUUID or email or employee ID of the user for looking up the person.

Name	Type	Format	Description
`externalUserCUUID`	`string`	-	The unique identifier for this user. This must match the CUUID from the SAP Concur profile service.
`name`	`string`	-	READ ONLY The user's name. Provided for convenience.
`id`	`string`	-	The budget service's unique identifier for this user.
`email`	`string`	-	The email address of the person to lookup.
`employeeId`	`string`	-	READ ONLY The employee ID of the person to lookup.
`employeeUuid`	`string`	-	The unique identifier for this user. This must match the UUID from the SAP Concur profile service.

BudgetItemBudgetTeam

Name	Type	Format	Description
`id`	`string`	-	The budget service's unique identifier for this team member.
`budgetPerson`	`budgetPerson`	-	Refers to the person and has profile details. Always pass externalUserCUUID and email of user.
`syncGuid`	`string`	-	The unique identifier for this user which is used for look ups.
`active`	`string`	-	Indicates enrollment status of team member in the budget. Supported values: `FULLY_ENROLLED`, `PARTIALLY_ENROLLED`, `NOT_ENROLLED`
`startDate`	`date`	`YYYY-MM-DD`	Indicates the start date from which the team member was enrolled in the budget. Required if the team member is `FULLY_ENROLLED` or `PARTIALLY_ENROLLED`. Pass `null` in case of `NOT_ENROLLED`.
`endDate`	`date`	`YYYY-MM-DD`	Indicates the end date until when the team member was enrolled in the budget. Required if the team member is `FULLY_ENROLLED` or `PARTIALLY_ENROLLED`. Pass `null` in case of `NOT_ENROLLED`.
`status`	`string`	-	READ ONLY Indicates if the user is a new, existing or removed team member of the budget. `NEW` means the user was newly added as a reportee of the budget owner. `Existing` means already a reportee and `REMOVED` means the team member is not a direct reportee of the budget owner.

BudgetCategory

Name	Type	Format	Description
`description`	`string`	-	The list of expense types that this budget category matches.
`name`	`string`	-	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 product that this expense type applies to: Purchase Request, Invoice (Payment Request), Expense, or Request. Supported values: `PURCHASE_REQUEST`, `PAYMENT_REQUEST`, `EXPENSE`, `REQUEST`
`expenseTypeCode`	`string`	-	Required The alphanumeric code that describes an expense type. (Example: `MEALS`, `AC_CATER`) Valid expense type codes are returned by the GET /budgetCategory/expenseType method described in the Budget Category service.
`name`	`string`	-	READ ONLY The name for this expense type if it maps to an expense type set up in your SAP Concur product(s).
`id`	`string`	-	The budget service's key for this object.

BudgetTrackingValue

Name	Type	Format	Description
`code`	`string`	-	The code for the cost object field. This can be used instead of fieldDefinitionId and will take priority if populated. This value can be found for your budget tracking fields you have configured by using the GET All Budget Tracking Fields resource.
`value`	`string`	-	The value for the cost object field.For `INLIST` and `NOTINLIST` operator, the value of this field can be one or more comma-separated values. For `EQUAL` and `NOTEQUAL` operator, the value of this field can be one value. For `ISFALSE` operator, the value of this field must be `ISFALSE`. For `ISNOTFALSE` operator, the value of this field must be `ISNOTFALSE`. For `ISBLANK`, `ISTRUE`, `ISFALSE`, `ISNOTTRUE`, `ISNOTFALSE`, the value of this field is not required and ignored if provided.
`listKey`	`string`	-	When setting up the budget, specify the `listKey` that maps to the value of this list in the SAP Concur list service.
`operator`	`string`	-	Required The comparison to use when matching values for this tracking field. Supported values: `EQUAL`, `INLIST`, `ISBLANK`, `NOTEQUAL`, `NOTINLIST`, `ISNOTBLANK`, `ISTRUE`, `ISFALSE`, `ISNOTTRUE`, `ISNOTFALSE`
`fieldDefinitionID`	`string`	-	Required The budget service’s key for this object’s field definition ID. This value can be found for your budget tracking fields you have configured by using the GET All Budget TrackingFields resource.
`displayName`	`string`	-	The budget field tracking name.

BudgetItemBalance

Name	Type	Format	Description
`amount`	`decimal`	-	READ ONLY The balance amount.
`featureTypeCode`	`string`	-	READ ONLY The product type for this balance. Supported values: `REQUEST`, `TRAVEL`, `EXPENSE`, `PAYMENT_REQUEST`
`featureTypeSubCode`	`string`	-	READ ONLY The feature type sub code for this balance. Supported values: `QUICK_EXPENSE`, `ERECEIPT`, `CREDIT_CARD`, `PERSONAL_CARD`, `TRIP`, `RECEIPT_CAPTURE`, `BILLING_STATEMENT`, `MANUAL`, `NONE`, `BUDGET_AMOUNT`, `SPENT_AMOUNT`, `PENDING_AMOUNT`, `PRE_AUTHORIZED`, `PURGE_ADJUSTMENT`
`workflowState`	`string`	-	READ ONLY Supported values: `UNSUBMITTED`, `UNSUBMITTED_HELD`, `SUBMITTED`, `APPROVED`, `PROCESSED`, `PAID`.
`id`	`string`	-	The unique identifier for this particular budget balance bucket..

FiscalYear

Name	Type	Format	Description
`currentYear`	`boolean`	-	READ ONLY If `true`, this is the current fiscal year based on the current date and time. `false`, if otherwise.
`startDate`	`date`	`YYYY-MM-DD`	Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
`endDate`	`date`	`YYYY-MM-DD`	Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
`name`	`string`	-	Required The name of this fiscal year. Must be unique for this entity.
`status`	`string`	-	Required The status of this fiscal year. Supported values: `OPEN`, `CLOSED`, `REMOVED`
`id`	`string`	-	The budget service's key for this object.
`fiscalYearId`	`string`	-	The unique identifier of the fiscal year for this budget.
`lastModified`	`datetime`	-	READ ONLY The UTC date and time when this object was last changed.
`displayName`	`string`	-	READ ONLY Display name for fiscal year. For date range budget item we use this field to display.
`fiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of all fiscal periods in this fiscal year.
`monthlyFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of monthly Fiscal Periods in this Fiscal Year. Fiscal periods must complete fill the parent Fiscal Year with no overlaps.
`quarterlyFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of quarterly Fiscal Periods in this Fiscal Year. If this parameter is not specified, quarterly Fiscal Periods are automatically generated based on the monthly Fiscal Periods supplied.
`yearlyFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of yearly Fiscal Periods in this Fiscal Year. If this parameter is not specified, one period is created that fills the Fiscal Year.
`customFiscalPeriods`	`array`	`fiscalPeriod`	READ ONLY The list of custom Fiscal Periods in this Fiscal Year. Custom Fiscal Periods are API-only and will not display on user budget dashboards.

FiscalPeriod

Name	Type	Format	Description
`currentPeriod`	`boolean`	-	READ ONLY If `true`, this is the current fiscal period based on the current time. `false`, if otherwise.
`startDate`	`date`	`YYYY-MM-DD`	Required The start date for this fiscal period. Must be within the parent fiscal year.
`endDate`	`date`	`YYYY-MM-DD`	Required The end date for this fiscal year. Must be within the parent fiscal year.
`name`	`string`	-	Required The name of this fiscal period. Must be unique for this entity.
`fiscalPeriodStatus`	`string`	-	Required The status of this fiscal period. Supported values: `OPEN`, `CLOSED`, `REMOVED`
`periodType`	`string`	-	Required The type of fiscal period. Supported values: `MONTHLY`, `QUARTERLY`, `YEARLY`, `CUSTOM`, `DATE_RANGE`
`id`	`string`	-	The budget service's key for this object.
`spendDate`	`date`	-	READ ONLY If the current date is after this fiscal period's start date, this field shows the current date.

DateRange

Name	Type	Format	Description
`startDate`	`date`	`YYYY-MM-DD`	The start date for the budget.
`endDate`	`date`	`YYYY-MM-DD`	The end date for the budget.

DetailDashboardBudgetItemAdjustment

Name	Type	Format	Description
`adjustmentType`	`string`	-	The type of adjustment being made. Only a user reference field. Supported values: `BUDGET_BALANCE`, `FUND_TRANSFER`, `EXPENSE`, `PAYMENT_REQUEST`, `PURCHASE_REQUEST`, `REQUEST`, `PURGE_ADJUSTMENT`
`amount`	`decimal`	-	The value of the amount adjusted (+/-).
`amountType`	`string`	-	The amount type of the field. Supported values: `QUICK_EXPENSE`, `ERECEIPT`, `CREDIT_CARD`, `PERSONAL_CARD`, `TRIP`, `RECEIPT_CAPTURE`, `BILLING_STATEMENT`, `MANUAL`, `NONE`, `BUDGET_AMOUNT`, `SPENT_AMOUNT`, `PENDING_AMOUNT`, `PRE_AUTHORIZED`, `PURGE_ADJUSTMENT`
`description`	`string`	-	The short description of the adjustment.
`transactionDate`	`date`	`YYYY-MM-DD`	The transaction date of adjusted spend. Required when the adjustment is made for amount type. Supported values: `SPENT_AMOUNT`, `PENDING_AMOUNT`

BudgetItemResponse

Name	Type	Format	Description
`success`	`boolean`	-	`True` or `False` for success or failure.
`budgetItemHeaderId`	`guid`	-	The key of the created/updated/removed budget item header.

BudgetItemHeaderSaveResponse

Name	Type	Format	Description
`success`	`boolean`	-	`True` or `False` for success or failure.
`budgetItemHeaderSyncGuid`	`guid`	-	The key of the created/updated budget item header.
`budgetItemDetailSyncGuids`	`array` of `guid`	-	The keys of the created/updated budget item details.

DateRange

Name	Type	Format	Description
`startDate`	`date`	`YYYY-MM-DD`	Required The start date for this fiscal year.
`endDate`	`date`	`YYYY-MM-DD`	Required The end date for this fiscal year.

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

FilesExpand file tree

v4.budget-header.md

Latest commit

History

v4.budget-header.md

File metadata and controls

title: Budget v4 - Budget Item layout: reference

Budget Item

GET All Budget Items

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

GET a Budget Item

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

Get Team Budget Example

Request

Response

POST a Budget Item

Scopes

Request

URI

Template

Parameters

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

Quarterly Budget Example

Date Range Budget Example

Team Budget Example

Response

Success Response

Failure Response

DELETE a Budget Item Header

Scopes

Request

URI

Template

Parameters

Headers

Response

Status Codes

Headers

Payload

Example

Request

Response

Schema

PagedBudgetItemHeaderList

BudgetItemHeader

BudgetItemDetail

BudgetAmounts

BudgetPerson

BudgetItemBudgetTeam