# Create a new custom report with table or chart components

Creates a new custom report. Supports either table or chart component types.

## Endpoint

`POST /dcapi/reports/customReports/v2`

## Request

### Request URL

`https://{server-hostname}:8383/dcapi/reports/customReports/v2`

### Scope

`CustomReport.CREATE`

### Header

`Authorization: d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

- **Content-Type** (`string`, Mandatory): `application/customReport.v2+json`
- **Accept** (`string`, Mandatory): `application/savedCustomReport.v2+json`

#### Request Body

`application/json`

- **reportName** (`string`, Mandatory): Display name of the custom report. Must be unique when saving.
- **reportDesc** (`string`, Optional): Optional description of the custom report.
- **subModule** (`string`, Mandatory): Sub-module name (e.g., Computer, Hardware, Software). Fetch from [Get Available Columns](https://www.manageengine.com/products/desktop-central/help/api/onpremise/report-get-available-columns.html).
- **criteria** (`JSON array`, Optional): Array of filter criteria objects for filtering report data.
- **selectComponents** (`JSON array`, Mandatory): Array of selected column objects for table reports. Each object specifies a column and optional aggregation.
- **groupby** (`array`, Optional): Array of column IDs to group by. Required when aggregation is applied.
- **criteriaPattern** (`string`, Optional): Custom criteria pattern defining how criteria are combined (e.g., `(1 AND 2) OR 3`).
- **componentType** (`string`, Mandatory): Type of report component: Table or Chart.
- **chartMeta** (`JSON object`, Optional): Chart configuration object. Required when `componentType` is Chart.

### Sample Request

```curl
curl --request POST \
  --url https://appdomain/dcapi/reports/customReports/v2 \
  --header 'Accept: application/savedCustomReport.v2+json' \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/customReport.v2+json' \
  --data '{"componentType":"Table","reportDesc":"List of all active computers with OS details","reportName":"Active Computers Report","subModule":"Computer","selectComponents":[{"columnID":"101"},{"columnID":"102"},{"columnID":"105","aggregation":"COUNT"}],"criteria":[{"comparator":"contains","logicalOperator":"AND","columnID":103,"searchValue":["Windows"]}],"groupby":["101"],"criteriaPattern":"(1)"}'
```

### Sample Request Body

#### Create a table-based custom report with column selection, grouping, and criteria

```json
{
  "componentType": "Table",
  "reportDesc": "List of all active computers with OS details",
  "reportName": "Active Computers Report",
  "subModule": "Computer",
  "selectComponents": [
    {
      "columnID": "101"
    },
    {
      "columnID": "102"
    },
    {
      "columnID": "105",
      "aggregation": "COUNT"
    }
  ],
  "criteria": [
    {
      "comparator": "contains",
      "logicalOperator": "AND",
      "columnID": 103,
      "searchValue": [
        "Windows"
      ]
    }
  ],
  "groupby": [
    "101"
  ],
  "criteriaPattern": "(1)"
}
```

#### Create a chart-based custom report with pie chart configuration

```json
{
  "componentType": "Chart",
  "reportName": "OS Distribution Chart",
  "subModule": "Computer",
  "chartMeta": {
    "yAxis": {
      "columnID": "101",
      "aggregation": "COUNT"
    },
    "xAxis": {
      "columnID": "103"
    },
    "chartType": "pie"
  }
}
```

## Response Parameters

### HTTP Code 200

Response Body: `application/json`

- **reportId** (`long`): Unique ID of the created/previewed custom report.
- **reportName** (`string`): Display name of the report.
- **viewName** (`string`): Internal view name (e.g., `CRVIEW_1711234567890`).
- **owner** (`string`): Username of the report creator.
- **customerId** (`long`): Customer ID (or null for all customers).

### HTTP Code 400

Response Body: `application/json`

- **errorCode** (`long`): Numeric error code: report name exists, column/criteria limits exceeded, invalid column IDs, aggregation mismatch, or invalid chart axis configuration.
- **errorMessage** (`string`): Detailed error description indicating the specific validation failure.

### HTTP Code 401

Response Body: `application/json`

- **errorCode** (`long`): Unauthorized error code returned when authentication credentials are missing, expired, or invalid (`authentication=required`).
- **errorMsg** (`string`): Authentication failure reason.

### HTTP Code 403

Response Body: `application/json`

- **errorCode** (`long`): Forbidden error code returned when the authenticated user does not have the required uem-roles (e.g., `DataEncryption_Admin` or `DataEncryptionRecoveryKey_Admin`).
- **errorMsg** (`string`): Message indicating insufficient privileges to access this resource.

### HTTP Code 429

Response Body: `application/json`

- **errorCode** (`long`): Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes.
- **errorMsg** (`string`): Rate limit exceeded message with retry guidance.

### Possible Response Codes

- `200` HTTP code
- `400` HTTP code
- `401` HTTP code
- `403` HTTP code
- `429` HTTP code

### Sample Response: HTTP 200

Custom report successfully created.

```json
{
  "owner": "admin",
  "reportId": 1005,
  "reportName": "Active Computers Report",
  "viewName": "CRVIEW_1711234567890",
  "customerId": 2
}
```

### Sample Response: HTTP 400

Report name already exists.

```json
{
  "errorMessage": "A custom report with this name already exists",
  "errorCode": 12345
}
```

### Sample Response: HTTP 401

Missing or invalid authentication token.

```json
{
  "errorMessage": "Authentication token is missing or invalid",
  "errorCode": "401"
}
```

### Sample Response: HTTP 403

User does not have the required role.

```json
{
  "errorMessage": "User does not have the required role to access this resource",
  "errorCode": "403"
}
```

### Sample Response: HTTP 429

Rate limit exceeded.

```json
{
  "errorMessage": "Rate limit exceeded. Please retry after some time",
  "errorCode": "429"
}
```

## Rate Limits

![](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

**Duration:** 1 minute | **Threshold:** 15 | **Lock period:** 5 minutes

Duration - Time window for the threshold.  
Threshold - Number of API calls allowed within the specified duration.  
Lock Period - Wait time before consecutive API requests.