Skip to content

ERS-35201-and-ERS-35202: Shift short Get Report FormFields and Get Expense FormFields to public access #1670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

ERS-35201-and-ERS-35202: Shift short Get Report FormFields and Get Expense FormFields to public access #1670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
868031a
ERS-35201-and-ERS-35202
rajatkasliwal Nov 28, 2025
9668eb3
ERS-35201-and-ERS-35202
rajatkasliwal Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions src/api-reference/expense/expense-report/v4.expenses.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,163 @@ layout: reference

# Expenses v4

## Get Expense Form Fields <a name="get-expense-form-fields"></a>

Returns the configured form fields for the specified expense on a report. Use this endpoint to retrieve the metadata for each field defined on the expense form (labels, control types, data types, access and required flags, etc.).

### Scopes

* `expense.report.read` - Refer to [Scope Usage](#scope-usage) for full details.
* `expense.report.readwrite` - Refer to [Scope Usage](#scope-usage) for full details.

### URI

```shell
https://{datacenterURI}/expensereports/v4/reports/{reportId}/expenses/{expenseId}/formFields
```

### Parameters

| Name | Type | Format | Description |
|---------------|----------|--------|--------------------------------------|
| reportId | `string` | path | The unique identifier of the report. |
| expenseId | `string` | path | The unique identifier of the expense.|
| expenseTypeId | `string` | query | The unique identifier of the expense type.|


### Payloads

* Request: None
* Response: [Expense Form Fields Response Schema](#expense-form-fields-response-schema)


### Headers

* [RFC 7231 Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5)
* [RFC 7231 Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5)
* [RFC 7231 Content-Encoding](https://tools.ietf.org/html/rfc7231#section-3.1.2.2)
* [RFC 7235 Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - Bearer Token that identifies the caller.
This is the Company or User access token.

### Response

#### Status Codes

* [200 OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)
* [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)
* [401 Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)
* [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)
* [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)
* [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)

### Examples

#### Request

```shell
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1/formFields' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'
```

#### Response

```shell
200 OK

[
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "String",
"defaultValue": null,
"fieldAccess": "RW",
"fieldId": "ExpName",
"formFieldId": "04845109BC5144D8BEB0CDB6ECB16017",
"fieldName": "Expense Type",
"fieldSequence": 1,
"hasLineSeparator": false,
"isCopyDownSource": false,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": 64,
"isRequired": true,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": "None",
"requiredForAutoSave": true,
"referenceLink": null,
"targetFieldSettings": null
},
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "String",
"defaultValue": null,
"fieldAccess": "RW",
"fieldId": "Custom29",
"formFieldId": "526098551C392F4197FBAD828B9575AE",
"fieldName": "Custom 29",
"fieldSequence": 2,
"hasLineSeparator": false,
"isCopyDownSource": false,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": 48,
"isRequired": false,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": "None",
"requiredForAutoSave": false,
"referenceLink": null,
"targetFieldSettings": [
{
"action": "HIDE",
"operator": "equals",
"value": "TEST",
"searchBy": "value",
"formFieldId": "A9BC29F1C3CAAE4A947D1428AAC170C3"
}
]
},
...
...
...
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "Date",
"defaultValue": null,
"fieldAccess": "RW",
"fieldId": "BudgetAccrualDate",
"formFieldId": "93B32A706D2C514E806C0187533ACEE2",
"fieldName": "Budget Accrual Date",
"fieldSequence": 63,
"hasLineSeparator": false,
"isCopyDownSource": false,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": null,
"isRequired": false,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": "None",
"requiredForAutoSave": false,
"referenceLink": null,
"targetFieldSettings": null
}
]
```

## Retrieve Itemizations on a Specific Expense ID <a name="specific-expense-itemizations"></a>

Retrieves the itemizations that belong to a specific expense ID.
The Expenses API can be used to read the expenses that belong to a specific expense report, modify an expense on an
existing expense report and delete an expense on an unsubmitted report. This API can be used to change attributes like
transaction date, transaction amount, location, etc.
Expand Down Expand Up @@ -914,6 +1071,41 @@ curl --location --request 'DELETE' \

## Schema <a name="schema"></a>

### <a name="expense-form-fields-response-schema"></a>Expense Form Fields Response

| Name | Type | Format | Description |
|------|------|--------|-------------------------------------------------|
| `formFields` | array | [FormField](#form-field-schema) | List of configured form fields for the expense. |

### <a name="form-field-schema"></a>FormField

| Name | Type | Format | Description |
|------|------|--------|-------------|
| `parentFieldId` | `string` | - | For connected list, the form field of the previous segment. Blank for simple list or non-list items. |
| `controlType` | `string` | - | The control type for the form field. (Required) |
| `dataType` | `string` | - | The data type for the form field. (Required) |
| `defaultValue` | `CustomField` | - | The source or content of the default value for the form field. |
| `fieldAccess` | `string` | - | The supplied user’s access to the form field. Allowable values: `HD` = hidden, `RO` = read-only, `RW` = read-write. (Required)
| `fieldId` | `string` | - | The field id. (Required)
| `formFieldId` | `string` | - | The unique identifier of the form field. |
| `fieldName` | `string` | - | The label (name) of the form field. |
| `fieldSequence` | `integer` | - | The field location in the numerical order of the form fields on the form. |
| `hasLineSeparator` | `boolean` | `true`/`false` | Indicates whether the form field has a line separator. |
| `isCopyDownSource` | `boolean` | `true`/`false` | Indicates whether the form field is a copy down source for other fields. |
| `listId` | `string` | - | The unique identifier of the source list to be used for this form field. |
| `listLevel` | `integer` | - | For connected list, the hierarchical position of this field in the list. Blank for simple list or non-list items. |
| `isExternalList` | `boolean` | `true`/`false` | Indicates whether the form field is configured as an external list (uses fetch list connector). (Required)
| `maximumLength` | `integer` | - | The maximum length allowed for the form field. |
| `isRequired` | `boolean` | `true`/`false` | Whether a value is required for the form field. |
| `tooltip` | `string` | - | The tool tip value of the form field. |
| `validationExpression` | `string` | - | The validation expression (regular expression) associated with the form field. |
| `validationMessage` | `string` | - | The failure message for the form field validation. |
| `itemizationCopyDownAction` | `string` | - | Itemization copy down action (e.g. `ConfiguredCopyDown`, `None`, `ParentExpense`). |
| `requiredForAutoSave` | `boolean` | `true`/`false` | Indicates if this field is required to be populated to perform a save even if other required fields are missing. (Required)
| `referenceLink` | `string` | - | The URL of the related HATEOAS link that you can use for subsequent calls. |
| `targetFieldSettings` | array | `List<TargetFieldSetting>` | Target field settings applicable for dependent or target fields. |


### <a name="report-expense-summary-schema"></a>ReportExpenseSummary

| Name | Type | Format | Description |
Expand Down
179 changes: 179 additions & 0 deletions src/api-reference/expense/expense-report/v4.reports.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,151 @@ curl --location --request PATCH 'https://us.api.concursolutions.com/expenserepor
204 No Content
```

## Get Report Form Fields <a name="get-report-form-fields"></a>

Returns the configured form fields for the specified report. Use this endpoint to retrieve the metadata for each field defined on the report form (labels, control types, data types, access and required flags, etc.).

### Scopes

* `expense.report.read` - Refer to [Scope Usage](#scope-usage) for full details.
* `expense.report.readwrite` - Refer to [Scope Usage](#scope-usage) for full details.

### URI

```shell
https://{datacenterURI}/expensereports/v4/reports/{reportId}/formFields
```

### Parameters

| Name | Type | Format | Description |
|----------|----------|--------|----------------------------------------------------|
| reportId | `string` | path | **Required** The unique identifier of the report. |
| policyId | `string` | query | The unique identifier of the applicable policy. |

### Payloads

* Request: None
* Response: [Report Form Fields Response Schema](#report-form-fields-response-schema)

### Headers

* [RFC 7231 Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5)
* [RFC 7231 Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5)
* [RFC 7231 Content-Encoding](https://tools.ietf.org/html/rfc7231#section-3.1.2.2)
* [RFC 7235 Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - Bearer Token that identifies the caller.
This is the Company or User access token.

### Response

#### Status Codes

* [200 OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)
* [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)
* [401 Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1)
* [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)
* [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)
* [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)

### Examples

#### Request

```shell
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/formFields' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json'
```

#### Response

```shell
200 OK

[
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "String",
"defaultValue": null,
"fieldAccess": "RW",
"fieldId": "Name",
"formFieldId": "073AAC230F95415E916057E7CE4255F6",
"fieldName": "Report Name",
"fieldSequence": 1,
"hasLineSeparator": false,
"isCopyDownSource": true,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": 40,
"isRequired": true,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": "None",
"requiredForAutoSave": true,
"referenceLink": null,
"targetFieldSettings": null
},
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "String",
"defaultValue": null,
"fieldAccess": "RO",
"fieldId": "ReportId",
"formFieldId": "FE4E49DD5CF143528EAD66AF0628AB43",
"fieldName": "Report ID",
"fieldSequence": 2,
"hasLineSeparator": false,
"isCopyDownSource": false,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": 32,
"isRequired": true,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": null,
"requiredForAutoSave": false,
"referenceLink": null,
"targetFieldSettings": null
},
...
...
...
{
"parentFieldId": null,
"controlType": "Edit",
"dataType": "Date",
"defaultValue": null,
"fieldAccess": "RO",
"fieldId": "CardProgramEndDate",
"formFieldId": "0BB7311E3E017049AEB604BD9653C672",
"fieldName": "Statement Period - End Date",
"fieldSequence": 92,
"hasLineSeparator": false,
"isCopyDownSource": false,
"listId": null,
"listLevel": null,
"isExternalList": false,
"maximumLength": null,
"isRequired": false,
"tooltip": null,
"validationExpression": null,
"validationMessage": null,
"itemizationCopyDownAction": null,
"requiredForAutoSave": false,
"referenceLink": null,
"targetFieldSettings": null
}
]
```

## Get Reports To Approve

## Update Submitted Report <a name="update-submitted-report"></a>

Updates the report header in a submitted expense report. When calling this endpoint only Company JWT authentication is
Expand Down Expand Up @@ -759,6 +904,40 @@ curl --location --request GET https://integration.api.concursolutions.com/expens
| `totalAmountPaidEmployee` | `string` | - | The amount reimbursed to the employee. |
| `userId` | `string` | - | **Required** The unique identifier of the Concur user who is the report owner. |

### <a name="report-form-fields-response-schema"></a>Report Form Fields Response

| Name | Type | Format | Description |
|------|------|--------|-------------|
| `formFields` | array | [FormField](#form-field-schema) | List of configured form fields for the report. |

### <a name="form-field-schema"></a>FormField

| Name | Type | Format | Description |
|------|------|--------|-------------|
| `parentFieldId` | `string` | - | For connected list, the form field of the previous segment. Blank for simple list or non-list items. |
| `controlType` | `string` | - | The control type for the form field. (Required) |
| `dataType` | `string` | - | The data type for the form field. (Required) |
| `defaultValue` | `CustomField` | - | The source or content of the default value for the form field. |
| `fieldAccess` | `string` | - | The supplied user’s access to the form field. Allowable values: `HD` = hidden, `RO` = read-only, `RW` = read-write. (Required)
| `fieldId` | `string` | - | The field id. (Required)
| `formFieldId` | `string` | - | The unique identifier of the form field. |
| `fieldName` | `string` | - | The label (name) of the form field. |
| `fieldSequence` | `integer` | - | The field location in the numerical order of the form fields on the form. |
| `hasLineSeparator` | `boolean` | `true`/`false` | Indicates whether the form field has a line separator. |
| `isCopyDownSource` | `boolean` | `true`/`false` | Indicates whether the form field is a copy down source for other fields. |
| `listId` | `string` | - | The unique identifier of the source list to be used for this form field. |
| `listLevel` | `integer` | - | For connected list, the hierarchical position of this field in the list. Blank for simple list or non-list items. |
| `isExternalList` | `boolean` | `true`/`false` | Indicates whether the form field is configured as an external list (uses fetch list connector). (Required)
| `maximumLength` | `integer` | - | The maximum length allowed for the form field. |
| `isRequired` | `boolean` | `true`/`false` | Whether a value is required for the form field. |
| `tooltip` | `string` | - | The tool tip value of the form field. |
| `validationExpression` | `string` | - | The validation expression (regular expression) associated with the form field. |
| `validationMessage` | `string` | - | The failure message for the form field validation. |
| `itemizationCopyDownAction` | `string` | - | Itemization copy down action (e.g. `ConfiguredCopyDown`, `None`, `ParentExpense`). |
| `requiredForAutoSave` | `boolean` | `true`/`false` | Indicates if this field is required to be populated to perform a save even if other required fields are missing. (Required)
| `referenceLink` | `string` | - | The URL of the related HATEOAS link that you can use for subsequent calls. |
| `targetFieldSettings` | array | `List<TargetFieldSetting>` | Target field settings applicable for dependent or target fields. |

### <a name="create-report-schema"></a>NewReport

| Name | Type | Format | Description |
Expand Down