Approval Workflow Instances

Important: The Approval Requests API is currently part of an early access program. For more information, see About approvals and how they work. Breaking changes should be expected between the EAP and GA version of this API.

An Approval Workflow Instance is a type of entity that will let us group approval requests to a single workflow in the future. Currently, there is a one to one mapping between an approval workflow instance and an approval request.

Create Approval Workflow Instance

• POST /api/v2/approval_workflow_instances

Creates an approval workflow instance attached to a ticket. The request must include a name for the workflow and a ticket id to associate with the workflow instance.

Allowed For

• Agents

Code Samples

curl

curl -u {email_address}/token:{api_token} https://{subdomain}.zendesk.com/api/v2/approval_workflow_instances.json \
  -H "Content-Type: application/json" -X POST -d \
 '{"name": "Workflow instance for laptop request", "ticket_id": 1234}'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/approval_workflow_instances"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/approval_workflow_instances")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/approval_workflow_instances',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/approval_workflow_instances"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"POST",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/approval_workflow_instances")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

{
  "custom_object_record": {
    "created_at": "2025-03-10T22:24:15Z",
    "created_by_user_id": "123123",
    "custom_object_fields": {
      "standard::completed_at": null,
      "standard::status": "pending",
      "standard::ticket": "138"
    },
    "custom_object_key": "standard::approval_workflow_instance",
    "external_id": null,
    "id": "01JP0S9TMASZS2X2N3YJ28TS33",
    "name": "My approval workflow instance",
    "updated_at": "2025-03-10T22:24:15Z",
    "updated_by_user_id": "245159",
    "url": "https://example.zendesk.com/api/v2/custom_objects/standard::approval_workflow_instance/records/01JP0S9TMASZS2X2N3YJ28TS33.json"
  }
}