Partial Update Custom Insight

PATCH

https://platform-api.convirza.com/v3/custom-insights/{id}

Custom Insights

Last modified:2026-07-24 13:10:44

Applies a partial update to a custom insight, modifying only the fields present in the request body. All fields not included in the payload retain their existing values.

Common use cases

Update insight name: { "insight_name": "Updated Name" }

Update description: { "insight_description": "New description" }

Change status: { "status": "inactive" }

Replace all rules: { "rules": [...] }

Constraints

At least one field must be present in the request body.

If insight_name is provided, it must be unique within the organization.

If rules array is provided, it replaces ALL existing rules.

Cannot update system default insights (is_system_default = true).

condition_order must be sequential starting from 1 if rules are updated.

updated_at is automatically refreshed on every successful PATCH.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Custom insight updated successfully

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🟠409

🔴500

Request Example

Shell

JavaScript

Java

Swift

curl --location --globoff --request PATCH 'https://platform-api.convirza.com/v3/custom-insights/{id}' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "insight_name": "Updated Missed Opportunity",
    "insight_description": "Updated description for identifying potential missed sales opportunities",
    "status": "active",
    "rules": [
        {
            "indicator_id": 38,
            "condition_type": "=",
            "condition_value": "100",
            "condition_join_type": "AND",
            "condition_order": 1
        }
    ]
}'

Response Example

200 - Example 1

{
    "code": 200,
    "message": "Success",
    "data": {
        "insight_id": 1,
        "org_unit_id": 123,
        "insight_name": "High-Value Missed Opportunities",
        "insight_description": null,
        "status": "active",
        "is_system_default": false,
        "created_at": "2026-04-01T10:30:00.000Z",
        "created_by": 456,
        "updated_at": null,
        "updated_by": null,
        "deleted_at": null,
        "deleted_by": null,
        "rules": [
            {
                "rule_id": 1,
                "custom_insight_id": 101,
                "indicator_id": 38,
                "data_field": null,
                "condition_type": "=",
                "condition_value": "100",
                "condition_join_type": "AND",
                "condition_order": 1
            }
        ]
    },
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-01-20T12:34:56.789Z"
}

Modified at 2026-07-24 13:10:44

Update Custom Insight

Delete Custom Insight