# Create a new custom report with table or chart components

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

## Endpoints

`POST` `/dcapi/reports/customReports/v2`

## Request URL

`https://{serverurl}/dcapi/reports/customReports/v2`

[`{serverurl}`](https://www.manageengine.com/products/desktop-central/help/api/cloud/oauth-authentication-endpoint-domain.html)

## Scope

`DesktopCentralCloud.CustomReport.CREATE`

### Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

## Request Parameters

### Request Headers

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

### Query Parameters

- **saveReport** `boolean` Optional
  - When true, the report is saved permanently. When false (default), a preview is generated and will be deleted within 1 day.

### Request Body

`application/json`

- `JSON Object`
  - **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/cloud/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://appdomains/dcapi/reports/customReports/v2 \
  --header 'Accept: application/savedCustomReport.v2+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/customReport.v2+json' \
  --data '{"componentType":"Table","reportName":"Active Computers Report","subModule":"Computer","selectComponents":[{"columnID":"101"},{"columnID":"102"},{"columnID":"105"}]}'
```

## 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`

- `JSON Object`
  - **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`

- `JSON Object`
  - **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`

- `JSON Object`
  - **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`

- `JSON Object`
  - **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`

- `JSON Object`
  - **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 Responses

### HTTP 200

Custom report successfully created

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

### HTTP 400

Report name already exists

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

### HTTP 401

Missing or invalid authentication token

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

### HTTP 403

User does not have the required role

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

### 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.