Virtual changes – Configly Help Centre

Overview

Virtual changes are a staging area for proposed configuration modifications. You can create, update, and delete virtual changes through the API before pushing them to your Zendesk instance. Virtual changes are also used as input to impact analysis and AI analysis endpoints, letting you evaluate the consequences of a change before applying it.

List virtual changes

Retrieve all virtual changes for a connection, ordered by most recently updated first. The response is paginated.

curl "https://api.configly.app/v1/virtual-changes?connectionId={connectionId}&page=1&limit=20" \
  -H "Authorization: Bearer cly_your_key"

Requires a READ_ONLY key at minimum.

Create a virtual change

Stage a new virtual change for a configuration object. Requires a READ_WRITE key.

curl -X POST https://api.configly.app/v1/virtual-changes \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "{connectionId}",
    "objectType": "trigger",
    "objectId": 12345,
    "changeType": "modify",
    "virtualData": {
      "title": "Updated trigger name",
      "active": true
    }
  }'

Returns 201 on success. The objectType field accepts both singular (trigger) and plural (triggers) forms; the API normalises to singular internally.

Upsert behaviour

POST upserts on the combination of connectionId, objectType, and objectId. If a virtual change already exists for the same object, it is replaced silently. If you need create-only semantics, check for an existing change on that object before posting.

Request body fields

Field	Type	Required	Description
`connectionId`	string	Yes	Connection to stage the change against
`objectType`	string	Yes	Configuration object type (singular or plural)
`objectId`	number	Yes	Zendesk ID of the object
`changeType`	string	Yes	One of `modify`, `create`, or `delete`
`originalData`	object or null	No	Original object data before the change
`virtualData`	object	Yes	Proposed object data after the change

Update a virtual change

Modify an existing virtual change by its ID. Requires a READ_WRITE key. Only the fields you include in the request body are updated.

curl -X PUT https://api.configly.app/v1/virtual-changes/{virtualChangeId} \
  -H "Authorization: Bearer cly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "changeType": "delete",
    "virtualData": { "active": false }
  }'

Updatable fields: changeType, originalData, virtualData.

Delete a single virtual change

Remove a specific virtual change by its ID. Requires a READ_WRITE key.

curl -X DELETE https://api.configly.app/v1/virtual-changes/{virtualChangeId} \
  -H "Authorization: Bearer cly_your_key"

Returns { "data": { "deleted": true } } on success.

Delete all for a connection

Remove every virtual change for a connection in a single request. Requires a READ_WRITE key.

curl -X DELETE "https://api.configly.app/v1/virtual-changes?connectionId={connectionId}" \
  -H "Authorization: Bearer cly_your_key"

Returns { "data": { "deletedCount": 5 } } with the number of changes removed.

Response shape

Field	Type	Description
`virtualChangeId`	string	Unique identifier for this virtual change
`connectionId`	string	Connection the change belongs to
`objectType`	string	Configuration object type (singular form)
`objectId`	string	Zendesk ID of the object
`changeType`	string	One of `modify`, `create`, or `delete`
`originalData`	object or null	Original object data, if provided
`virtualData`	object	Proposed object data (round-trips losslessly, not sanitised)
`createdAt`	string (ISO 8601)	When the virtual change was created
`updatedAt`	string (ISO 8601)	When the virtual change was last modified

Error codes

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid or missing request fields
401	`INVALID_API_KEY`	Missing or invalid API key
403	`FORBIDDEN`	Key does not have access to this connection
403	`WRITE_SCOPE_REQUIRED`	A `READ_WRITE` key is required for this operation
404	`NOT_FOUND`	Virtual change not found

To analyse the impact of virtual changes, see Impact analysis. To push changes to Zendesk, see Apply changes.

Related to