Custom Object Records

Custom object records are individual instances of your custom objects. You can use this API to manage custom object Records.

Custom Object Record Limitations

• Each record has a maximum size of 32 KB
• Each account can have a maximum of 50,000,000 custom object records

Additional limitations

• Legacy plans might have other limitations.

Parent-child relationships

If a custom object has a parent relationship field, the field is required and must reference a valid parent record when creating a child record. Set the parent field value in custom_object_fields using the parent record's id, or by external id ("external_id:value") or name ("name:value"), same as lookup field values.

Cascade deletion - Deleting a parent record cascades deletion to all child records asynchronously. Child records are tombstoned immediately and permanently deleted after 30 days. The delete request returns immediately with a 204 response; the cascade happens in the background.

Cascade permissions - If cascade_permissions_enabled is set on a parent field, non-admin agents must provide the parent context when listing or searching child records. Use the Filtered Search API with a filter on the parent field. Requests to the List, Search, and Count endpoints without a parent filter return 403 Forbidden. See Custom Object Permissions for details.

Identifying records by a unique field

If a custom object has unique fields, you can identify a record by the value of a unique field instead of its id. Send the field's key as a query parameter, for example ?vin=1HGCM82633A004352, to these endpoints:

• Show Custom Object Record by Unique Identifier
• Update Custom Object Record by Unique Identifier
• Create or Update Custom Object Record
• Delete Custom Object Record by External Id Or Name

These endpoints also accept external_id or name as the identifier. Send only one identifier per request. In bulk jobs, use the create_or_update_by_unique_field and delete_by_unique_field actions with unique_field_key. To set a lookup field by a target record's unique field value, see Setting lookup field values.

Creating or updating a record with a value that another record already has in a unique field returns a 422 Unprocessable Entity error.

Roll-up summary fields

The values for roll-up summary fields on custom objects are included in record responses under custom_object_fields like any other field. However, roll-up summary field values are read-only and calculated automatically based on the child records. Any attempt to set or update a roll-up summary field value in an API request is ignored. See About roll-up summary fields.

JSON format

Custom Object Records are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
created_at	string	true	false	The time the object was created
created_by_user_id	string	true	false	Id of a user who created the object
custom_object_fields	object	false	false
custom_object_key	string	true	false	A user-defined unique identifier
external_id	string	false	false	An id you can use to link custom object records to external data
id	string	true	false	Automatically assigned upon creation
name	string	true	true	User-defined display name for the object. If autonumbering is selected for the custom object's name field, the name isn't allowed because it's automatically generated. If uniqueness is enabled, the name must be unique.
photo	object	false	false	The record photo represented as an Attachment. The allows_photos property must be set to true for the object. Record photos are publicly accessible via the photo content_url.
updated_at	string	true	false	The time of the last update of the object
updated_by_user_id	string	true	false	Id of the last user who updated the object
url	string	true	false	Direct link to the specific custom object

List Custom Object Records

• GET /api/v2/custom_objects/{custom_object_key}/records

Lists all undeleted custom object records for the specified object.

If the object has a parent field with cascade_permissions_enabled, non-admin agents receive a 403 Forbidden response. Use the Filtered Search endpoint with a filter on the parent field instead.

Pagination

• Cursor pagination only.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
filter[external_ids]	string	Query	false	Optional comma-separated list of external ids to filter records by. If one or more ids are specified, only matching records are returned. The ids must be unique and are case sensitive.
filter[ids]	string	Query	false	Optional comma-separated list of ids to filter records by. If one or more ids are specified, only matching records are returned. The ids must be unique and are case sensitive.
page[after]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.after_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[before]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.before_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[size]	integer	Query	false	Specifies how many records should be returned in the response. You can specify up to 100 records per page.
sort	string	Query	false	One of id, updated_at, -id, or -updated_at. The - denotes the sort will be descending.
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/records?filter[external_ids]=&filter[ids]=&page[after]=&page[before]=&page[size]=&sort= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records?filter[external_ids]=&filter[ids]=&page[after]=&page[before]=&page[size]=&sort="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("filter[external_ids]", "")
		.addQueryParameter("filter[ids]", "")
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("sort", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'filter[external_ids]': '',
    'filter[ids]': '',
    'page[after]': '',
    'page[before]': '',
    'page[size]': '',
    'sort': '',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records?filter[external_ids]=&filter[ids]=&page[after]=&page[before]=&page[size]=&sort="
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
uri.query = URI.encode_www_form("filter[external_ids]": "", "filter[ids]": "", "page[after]": "", "page[before]": "", "page[size]": "", "sort": "")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records based on relevance

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with specified ids

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?filter[ids]=123,456 \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with specified external ids

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?filter[external_ids]=123,456 \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records, 10 records per page, most recently updated record first

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?page[size]=10sort=-updated_at  \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_records": [
    {
      "created_at": "2022-09-12T19:29:59Z",
      "created_by_user_id": "10001",
      "custom_object_fields": {
        "make": "Tesla",
        "model": "S"
      },
      "custom_object_key": "car",
      "external_id": "Internal System Record 54848",
      "id": "01GCSJW391QVSC80GYDH7E93Q6",
      "name": "My Tesla CO record",
      "updated_at": "2022-09-15T21:07:03Z",
      "updated_by_user_id": "10001",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
    },
    {
      "created_at": "2022-09-26T22:24:15Z",
      "created_by_user_id": "123123",
      "custom_object_fields": {
        "make": "Honda",
        "model": "Civic"
      },
      "custom_object_key": "car",
      "external_id": null,
      "id": "01GDXYD7ZTWYP542BA8MDDTE36",
      "name": "My Tesla CO record2",
      "updated_at": "2022-09-26T22:24:15Z",
      "updated_by_user_id": "245159",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYD7ZTWYP542BA8MDDTE36"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records?page%5Bafter%5D=eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0%3D&page%5Bsize%5D=1&query=",
    "prev": null
  },
  "meta": {
    "after_cursor": "eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0=",
    "before_cursor": null,
    "has_more": true
  }
}

Show Custom Object Record

• GET /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

Returns a custom record for a specific object using a provided id.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object
custom_object_record_id	string	Path	true	The id of a custom object record

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6 \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object record by id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id} \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Create Custom Object Record

• POST /api/v2/custom_objects/{custom_object_key}/records

Creates a custom object record according to all the properties described by a custom object definition. If autoincrement_enabled is true, record names aren't allowed in the request body because they are generated automatically. If is_unique is true, record names must be unique.

If the custom object has a parent relationship field, the parent field is required and must reference a valid parent record. Set the value in custom_object_fields using the parent record's id, external id ("external_id:value"), or name ("name:value").

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/custom_objects/car/records \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records"
	method := "POST"
	payload := strings.NewReader(`{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"make\": \"Tesla\",
      \"model\": \"Y\"
    },
    \"name\": \"My car 1\"
  }
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records"

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
request = Net::HTTP::Post.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Create custom object record

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_object.json

{
  "custom_object_record": {
    "name": "Personal Car",
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
  }
}

curl - Create custom object record snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records \
  -d @my_object.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

# Creating a record with a photo
curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records \
  -F "custom_object_record[name]=Personal Car" \
  -F "custom_object_record[custom_object_fields][make]=Tesla" \
  -F "custom_object_record[photo][uploaded_data]=@/path/to/image.jpg" \
  -H "Content-Type: multipart/form-data" -H "Authorization: Bearer {access_token}" -X POST

Example response(s)

201 Created

// Status 201 Created

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Show Custom Object Record by Unique Identifier

• GET /api/v2/custom_objects/{custom_object_key}/records/show_by_unique_identifier

Returns a custom object record identified by its external id, its name, or the value of one of the custom object's unique fields. Send exactly one identifier per request.

• To identify the record by name, the is_unique property on the custom object's name field must be enabled.
• To identify the record by a unique field, send the field's key as the query parameter, for example ?vin=1HGCM82633A004352. The field's is_unique property must be enabled. For a unique lookup field, the value is the id of the record the field references.

Returns a 400 Bad Request if more than one identifier is sent, if name is sent and the name field isn't unique, or if no identifier is sent. A parameter that isn't the key of a unique field doesn't count as an identifier. Returns a 404 Not Found if no record matches.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	false	The external id of a custom object record
name	string	Query	false	The name of a custom object record
unique_field_value	object	Query	false	A value of one of the custom object's unique fields, sent as {unique_field_key}={value}. For example, vin=1HGCM82633A004352 identifies the record whose unique field with the key "vin" holds that value. The field's is_unique property must be enabled.
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/records/show_by_unique_identifier?external_id=X90001&name=boat&unique_field_value= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/show_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/show_by_unique_identifier")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat")
		.addQueryParameter("unique_field_value", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/show_by_unique_identifier',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
    'unique_field_value': '',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/show_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/show_by_unique_identifier")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat", "unique_field_value": "")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object record by external id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/show_by_unique_identifier?external_id={external_id} \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object record by a unique field value

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/show_by_unique_identifier?{unique_field_key}={value} \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Update Custom Object Record

• PATCH /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

Updates an individual custom object record. The updating rules are as follows:

• Takes a custom_object_record object that specifies the properties to update
• The custom object fields should be nested inside a custom_object_fields object

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object
custom_object_record_id	string	Path	true	The id of a custom object record

Example body

{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}

Code Samples

Curl

curl --request PATCH https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6 \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
	method := "PATCH"
	payload := strings.NewReader(`{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"model\": \"Civic\",
      \"year\": 2002
    }
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", body)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
});

var config = {
  method: 'PATCH',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"PATCH",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
request = Net::HTTP::Patch.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Update custom object record by id

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

updated_record.json

{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}

curl - Update custom object record by id snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id} \
-d @updated_record.json \
-H "Content-Type: application/json" -X PATCH \
-H "Authorization: Bearer {access_token}"

# Adding a photo to a record
curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id} \
-F "custom_object_record[photo][uploaded_data]=@/path/to/image.jpg" \
-H "Content-Type: multipart/form-data" -X PATCH \
-H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Create or Update Custom Object Record

• PATCH /api/v2/custom_objects/{custom_object_key}/records

Creates or updates a custom object record based on the provided external id, name, or unique field value. If a record exists for the given identifier, the endpoint updates it. Only the specified attributes are updated. Otherwise, the endpoint creates a new record with the provided identifier and other attributes. Specify only one identifier per request.

• The is_unique property on the custom object's name field must be enabled in order to update or create by name.
• To update or create by a unique field, send the field's key as the query parameter, for example ?vin=1HGCM82633A004352. The field's is_unique property must be enabled. A new record is created with that value in the field.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	false	The external id of a custom object record
name	string	Query	false	The name of a custom object record
unique_field_value	object	Query	false	A value of one of the custom object's unique fields, sent as {unique_field_key}={value}. For example, vin=1HGCM82633A004352 identifies the record whose unique field with the key "vin" holds that value. The field's is_unique property must be enabled.
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}

Code Samples

Curl

curl --request PATCH https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value="
	method := "PATCH"
	payload := strings.NewReader(`{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat")
		.addQueryParameter("unique_field_value", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"make\": \"Oldsmobile\",
      \"model\": \"Cutlass Supreme\"
    },
    \"name\": \"1997 Cutlass Supreme\"
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", body)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
});

var config = {
  method: 'PATCH',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
    'unique_field_value': '',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value="

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"PATCH",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat", "unique_field_value": "")
request = Net::HTTP::Patch.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Set custom object record by external id

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_object.json

{
  "custom_object_record": {
    "name": "1997 Cutlass Supreme",
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    }
  }
}

curl - Set custom object record by external id snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?external_id={external_id} \
  -d @my_object.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X PATCH

curl - Set custom object record by name

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_object.json

{
  "custom_object_record": {
    "name": "1997 Cutlass Supreme",
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    }
  }
}

curl - Set custom object record by name snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?name={name} \
  -d @my_object.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X PATCH

curl - Set custom object record by a unique field value

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_object.json

{
  "custom_object_record": {
    "name": "1997 Cutlass Supreme",
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    }
  }
}

curl - Set custom object record by a unique field value snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?{unique_field_key}={value} \
  -d @my_object.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X PATCH

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2023-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "custom_object_key": "car",
    "external_id": "X90001",
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "1997 Cutlass Supreme",
    "updated_at": "2023-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Update Custom Object Record by Unique Identifier

• PATCH /api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier

Updates a custom object record identified by its external id, its name, or the value of one of the custom object's unique fields. Unlike Create or Update Custom Object Record, it never creates a record. Send exactly one identifier per request.

• To identify the record by name, the is_unique property on the custom object's name field must be enabled.
• To identify the record by a unique field, send the field's key as the query parameter, for example ?vin=1HGCM82633A004352. The field's is_unique property must be enabled. For a unique lookup field, the value is the id of the record the field references.

The update rules are the same as for Update Custom Object Record:

• Send a custom_object_record object that specifies the properties to update
• Nest the custom object fields inside a custom_object_fields object

Returns a 400 Bad Request if more than one identifier is sent, if name is sent and the name field isn't unique, or if no identifier is sent. A parameter that isn't the key of a unique field doesn't count as an identifier. Returns a 404 Not Found if no record matches.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	false	The external id of a custom object record
name	string	Query	false	The name of a custom object record
unique_field_value	object	Query	false	A value of one of the custom object's unique fields, sent as {unique_field_key}={value}. For example, vin=1HGCM82633A004352 identifies the record whose unique field with the key "vin" holds that value. The field's is_unique property must be enabled.
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}

Code Samples

Curl

curl --request PATCH https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="
	method := "PATCH"
	payload := strings.NewReader(`{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/update_by_unique_identifier")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat")
		.addQueryParameter("unique_field_value", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"make\": \"Oldsmobile\",
      \"model\": \"Cutlass Supreme\"
    },
    \"name\": \"1997 Cutlass Supreme\"
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", body)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
});

var config = {
  method: 'PATCH',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
    'unique_field_value': '',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"PATCH",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat", "unique_field_value": "")
request = Net::HTTP::Patch.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Update custom object record by a unique field value

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

updated_record.json

{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}

curl - Update custom object record by a unique field value snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier?{unique_field_key}={value} \
  -d @updated_record.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X PATCH

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Update Custom Object Record by Unique Identifier (PUT)

• PUT /api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier

Same as Update Custom Object Record by Unique Identifier, using PUT.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	false	The external id of a custom object record
name	string	Query	false	The name of a custom object record
unique_field_value	object	Query	false	A value of one of the custom object's unique fields, sent as {unique_field_key}={value}. For example, vin=1HGCM82633A004352 identifies the record whose unique field with the key "vin" holds that value. The field's is_unique property must be enabled.
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}

Code Samples

Curl

curl --request PUT https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="
	method := "PUT"
	payload := strings.NewReader(`{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/update_by_unique_identifier")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat")
		.addQueryParameter("unique_field_value", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"make\": \"Oldsmobile\",
      \"model\": \"Cutlass Supreme\"
    },
    \"name\": \"1997 Cutlass Supreme\"
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
});

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
    'unique_field_value': '',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier?external_id=X90001&name=boat&unique_field_value="

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/update_by_unique_identifier")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat", "unique_field_value": "")
request = Net::HTTP::Put.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Update custom object record by external id (PUT)

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

updated_record.json

{
  "custom_object_record": {
    "custom_object_fields": {
      "model": "Civic",
      "year": 2002
    }
  }
}

curl - Update custom object record by external id (PUT) snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/update_by_unique_identifier?external_id={external_id} \
  -d @updated_record.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X PUT

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_record": {
    "created_at": "2022-09-26T22:25:10Z",
    "created_by_user_id": "10001",
    "custom_object_fields": {
      "color": "white",
      "make": "Tesla",
      "model": "Y"
    },
    "custom_object_key": "car",
    "external_id": null,
    "id": "01GDXYEY1FQYN066VHF49YHJ21",
    "name": "My Tesla",
    "photo": {
      "content_type": "image/png",
      "content_url": "https://company.zendesk.com/record_photos/my_funny_pic.png",
      "id": 928374,
      "name": "my_funny_pic.png",
      "size": 166144
    },
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21"
  }
}

Incremental Custom Object Record Export, Cursor Based

• GET /api/v2/incremental/custom_objects/{custom_object_key}/cursor

Returns the custom object records that changed since the start time. This endpoint supports cursor-based incremental exports for custom object records.

This endpoint only supports cursor-based pagination and does not support offset-based pagination. Cursor-based exports provide more consistent performance and response body sizes. For more information, see Cursor-based incremental exports in Using the Incremental Exports API.

Allowed For

• Admins
• Agents with custom object read permissions

Rate Limiting

You can make up to 10 requests per minute to this endpoint.

Notes

• start_time is only required for the initial request for the pages in the record set, then cursor is required for all subsequent requests
• The start_time must be more than 60 seconds ago
• Deleted records will have their field values replaced with "[DELETED]" unless excluded via filter
• Photo fields are excluded from incremental export responses

Parameters

Name	Type	In	Required	Description
cursor	string	Query	false	The cursor pointer to work with for all subsequent exports after the initial request
filter[exclude_deleted]	boolean	Query	false	If true, exclude deleted records from the export
per_page	integer	Query	false	Number of records to return per page (default 1000, maximum 1000)
start_time	integer	Query	false	The time to start the incremental export from. Must be at least one minute in the past. Data isn't provided for the most recent minute. Required on the initial export request; not required on subsequent cursor-based pagination requests
custom_object_key	string	Path	true	The key identifier for the custom object

Code Samples

curl

Cursor-based export

# Initial request with start_time
curl https://{subdomain}.zendesk.com/api/v2/incremental/custom_objects/{custom_object_key}/cursor?start_time=1332034771 \
  -H "Authorization: Bearer {access_token}"

# Subsequent requests with cursor
curl https://{subdomain}.zendesk.com/api/v2/incremental/custom_objects/{custom_object_key}/cursor?cursor=MTU3NjYxMzUzOS4wfHw0NTF8 \
  -H "Authorization: Bearer {access_token}"

# With filters
curl https://{subdomain}.zendesk.com/api/v2/incremental/custom_objects/{custom_object_key}/cursor?start_time=1332034771&filter[exclude_deleted]=true \
  -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/incremental/custom_objects/apartment/cursor?cursor=&filter[exclude_deleted]=&per_page=&start_time=1332034771"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/incremental/custom_objects/apartment/cursor")
		.newBuilder()
		.addQueryParameter("cursor", "")
		.addQueryParameter("filter[exclude_deleted]", "")
		.addQueryParameter("per_page", "")
		.addQueryParameter("start_time", "1332034771");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/incremental/custom_objects/apartment/cursor',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'cursor': '',
    'filter[exclude_deleted]': '',
    'per_page': '',
    'start_time': '1332034771',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/incremental/custom_objects/apartment/cursor?cursor=&filter[exclude_deleted]=&per_page=&start_time=1332034771"
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/incremental/custom_objects/apartment/cursor")
uri.query = URI.encode_www_form("cursor": "", "filter[exclude_deleted]": "", "per_page": "", "start_time": "1332034771")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "after_cursor": "MTU3NjYxMzUzOS4wfHw0Njd8",
  "after_url": "https://company.zendesk.com/api/v2/incremental/custom_objects/apartment/cursor?cursor=MTU3NjYxMzUzOS4wfHw0Njd8",
  "before_cursor": null,
  "before_url": null,
  "custom_object_records": [
    {
      "created_at": "2023-01-15T10:30:00Z",
      "created_by_user_id": "360000000001",
      "custom_object_fields": {
        "address": "123 Main Street",
        "bathrooms": "1",
        "bedrooms": "2",
        "rent": "2500",
        "status": "occupied",
        "tenant_email": "[email protected]",
        "unit_number": "12A"
      },
      "custom_object_key": "apartment",
      "external_id": "apt-12a-main-st",
      "id": "01HXAMPLE123456789",
      "name": "Apartment 12A",
      "updated_at": "2023-01-15T14:45:00Z",
      "updated_by_user_id": "360000000001",
      "url": "https://company.zendesk.com/api/v2/custom_objects/apartment/records/01HXAMPLE123456789"
    },
    {
      "created_at": "2023-01-10T08:15:00Z",
      "created_by_user_id": "360000000002",
      "custom_object_fields": {
        "address": "456 Oak Avenue",
        "bathrooms": "1",
        "bedrooms": "1",
        "rent": "1800",
        "status": "vacant",
        "tenant_email": null,
        "unit_number": "5B"
      },
      "custom_object_key": "apartment",
      "external_id": "apt-5b-oak-ave",
      "id": "01HXAMPLE987654321",
      "name": "Apartment 5B",
      "updated_at": "2023-01-16T09:20:00Z",
      "updated_by_user_id": "360000000003",
      "url": "https://company.zendesk.com/api/v2/custom_objects/apartment/records/01HXAMPLE987654321"
    },
    {
      "created_at": "2023-01-05T12:00:00Z",
      "created_by_user_id": "360000000001",
      "custom_object_fields": {
        "address": "[DELETED]",
        "bathrooms": "[DELETED]",
        "bedrooms": "[DELETED]",
        "rent": "[DELETED]",
        "status": "[DELETED]",
        "tenant_email": "[DELETED]",
        "unit_number": "[DELETED]"
      },
      "custom_object_key": "apartment",
      "external_id": "[DELETED]",
      "id": "01HXAMPLE555666777",
      "name": "[DELETED]",
      "updated_at": "2023-01-16T16:30:00Z",
      "updated_by_user_id": "360000000001",
      "url": "https://company.zendesk.com/api/v2/custom_objects/apartment/records/01HXAMPLE555666777"
    }
  ],
  "filter": {
    "exclude_deleted": false
  },
  "meta": {
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "StartTimeTooRecent",
      "status": "400",
      "title": "start_time must be more than 60 seconds ago"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "Unauthorized",
      "status": "401",
      "title": "Authentication required"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "Forbidden",
      "status": "403",
      "title": "Insufficient permissions to access custom objects"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "CustomObjectNotFound",
      "status": "404",
      "title": "Custom object not found"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "RateLimitExceeded",
      "status": "429",
      "title": "Rate limit exceeded. Maximum 10 requests per minute."
    }
  ]
}

Autocomplete Custom Object Record Search

• GET /api/v2/custom_objects/{custom_object_key}/records/autocomplete

Retrieves an array of custom object records that have a field value that matches the value specified in the name parameter.

If the object has a parent field with cascade_permissions_enabled, the request must be made in the context of a cascade parent field using the field_id and source parameters.

Pagination

• Cursor pagination only.
• Returns the first 10,000 records sorted by relevancy with page limits.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
assignee_id	integer	Query	false	The id of the selected assignee. For use with dynamic filters.
field_id	string	Query	false	The id of the lookup field. If the field has a relationship filter, the filter is applied to the results. Must be used with source param.
filter[dynamic_values]	object	Query	false	Provided values to be used with dynamic filters.
name	string	Query	false	Part of a name of the record you are searching for
organization_id	integer	Query	false	The id of the organization the requester belongs to. For use with dynamic filters.
page[after]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.after_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[before]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.before_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[size]	integer	Query	false	The number of records to return in the response. You can specify up to 100 records per page.
requester_id	integer	Query	false	The id of the requester. For use with dynamic filters.
source	string	Query	false	One of "zen:user", "zen:ticket", "zen:organization", or "zen:custom_object:CUSTOM_OBJECT_KEY". Represents the object field_id belongs to. Must be used with field_id param.
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete?assignee_id=7334148660734&field_id=&filter[dynamic_values]=&name=&organization_id=5633330889598&page[after]=&page[before]=&page[size]=&requester_id=264817272&source= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete?assignee_id=7334148660734&field_id=&filter[dynamic_values]=&name=&organization_id=5633330889598&page[after]=&page[before]=&page[size]=&requester_id=264817272&source="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/autocomplete")
		.newBuilder()
		.addQueryParameter("assignee_id", "7334148660734")
		.addQueryParameter("field_id", "")
		.addQueryParameter("filter[dynamic_values]", "")
		.addQueryParameter("name", "")
		.addQueryParameter("organization_id", "5633330889598")
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("requester_id", "264817272")
		.addQueryParameter("source", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'assignee_id': '7334148660734',
    'field_id': '',
    'filter[dynamic_values]': '',
    'name': '',
    'organization_id': '5633330889598',
    'page[after]': '',
    'page[before]': '',
    'page[size]': '',
    'requester_id': '264817272',
    'source': '',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete?assignee_id=7334148660734&field_id=&filter[dynamic_values]=&name=&organization_id=5633330889598&page[after]=&page[before]=&page[size]=&requester_id=264817272&source="
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete")
uri.query = URI.encode_www_form("assignee_id": "7334148660734", "field_id": "", "filter[dynamic_values]": "", "name": "", "organization_id": "5633330889598", "page[after]": "", "page[before]": "", "page[size]": "", "requester_id": "264817272", "source": "")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get records with name matching Tesla

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=Tesla \
  -H "Authorization: Bearer {access_token}"

curl - get records with name matching Tesla, 10 records per page, previous page

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=Tesla&page[before]=cursor_value&page[size]=10 \
  -H "Authorization: Bearer {access_token}"

curl - Get records with name matching Tesla, with field_id and source

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=Tesla&field_id=field_value&source=zen:custom_object:car \
  -H "Authorization: Bearer {access_token}"

curl - Get records while applying values in dynamic relationship filters

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=*&filter[dynamic_values][ticket_fields_123]=456&filter[dynamic_values][custom_object.object_key.custom_fields.field_key]=789 \
  -H "Authorization: Bearer {access_token}"

curl - Get records filtered by ticket brand

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=*&field_id={field_id}&source=zen:ticket&filter[dynamic_values][ticket_brand_id]={brand_id} \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "count": 100,
  "custom_object_records": [
    {
      "created_at": "2022-09-12T19:29:59Z",
      "created_by_user_id": "10001",
      "custom_object_fields": {
        "make": "Tesla",
        "model": "S"
      },
      "custom_object_key": "car",
      "external_id": "Internal System Record 54848",
      "id": "01GCSJW391QVSC80GYDH7E93Q6",
      "name": "My Tesla CO record",
      "updated_at": "2022-09-15T21:07:03Z",
      "updated_by_user_id": "10001",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
    },
    {
      "created_at": "2022-09-26T22:24:15Z",
      "created_by_user_id": "123123",
      "custom_object_fields": {
        "make": "Honda",
        "model": "Civic"
      },
      "custom_object_key": "car",
      "external_id": null,
      "id": "01GDXYD7ZTWYP542BA8MDDTE36",
      "name": "My Tesla CO record2",
      "updated_at": "2022-09-26T22:24:15Z",
      "updated_by_user_id": "245159",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYD7ZTWYP542BA8MDDTE36"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/autocomplete?page%5Bafter%5D=eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0%3D&page%5Bsize%5D=1&query=",
    "prev": null
  },
  "meta": {
    "after_cursor": "eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0=",
    "before_cursor": null,
    "has_more": true
  }
}

Search Custom Object Records

• GET /api/v2/custom_objects/{custom_object_key}/records/search

Returns an array of custom object records where the search query matches the values in Text Fields, Multi Line Text fields, and RegExp fields. To find records in other fields, use the Filtered Search API endpoint.

If the object has a parent field with cascade_permissions_enabled, non-admin agents receive a 403 Forbidden response. Use the Filtered Search endpoint with a filter on the parent field instead.

Pagination

• Cursor pagination only.
• Returns the records sorted by relevancy with page limits. Without a sort parameter, only the first 10,000 records are returned. With a sort parameter, all records are returned.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.after_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[before]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.before_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[size]	integer	Query	false	Specifies how many records should be returned in the response. You can specify up to 100 records per page.
query	string	Query	false	The query parameter is used to search text-based fields for records that match specific query terms. The query can be multiple words or numbers. Every record that matches the beginning of any word or number in the query string is returned. Fuzzy search is supported for the following text-based field types: Text fields, Multi Line Text fields, and RegExp fields. For example, you might want to search for records related to Tesla vehicles: query=Tesla. In this example the API would return every record for the given custom object where any of the supported text fields contain the word 'Tesla'. You can include multiple words or numbers in your search. For example: query=Tesla Honda 2020. This search phrase would be URL encoded as query=Tesla%20Honda%202020 and return every record for the custom object for which any of the supported text fields contained 'Tesla', 'Honda', or '2020'.
sort	string	Query	false	One of name, created_at, updated_at, -name, -created_at, or -updated_at. The - denotes the sort will be descending. Defaults to sorting by relevance.
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=jdoe" \
  -H "Authorization: Bearer {access_token}"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/search")
		.newBuilder()
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("query", "jdoe")
		.addQueryParameter("sort", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/search',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'page[after]': '',
    'page[before]': '',
    'page[size]': '',
    'query': 'jdoe',
    'sort': '',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort="
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/search")
uri.query = URI.encode_www_form("page[after]": "", "page[before]": "", "page[size]": "", "query": "jdoe", "sort": "")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records with fields matching Tesla

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=Tesla" \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with fields matching 1998 or 2003

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=1998%202003" \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with fields matching Tesla, newest records first

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=Tesla" \
  --data-urlencode "sort=created_at" \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with fields matching Tesla, sort by car name, descending

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=Tesla" \
  --data-urlencode "sort=-name" \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with fields matching Tesla, 10 records per page, previous page

curl -G "https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search" \
  --data-urlencode "query=Tesla" \
  --data-urlencode "page[before]=cursor_value" \
  --data-urlencode "page[size]=10" \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "count": 100,
  "custom_object_records": [
    {
      "created_at": "2022-09-12T19:29:59Z",
      "created_by_user_id": "10001",
      "custom_object_fields": {
        "make": "Tesla",
        "model": "S"
      },
      "custom_object_key": "car",
      "external_id": "Internal System Record 54848",
      "id": "01GCSJW391QVSC80GYDH7E93Q6",
      "name": "My Tesla CO record",
      "updated_at": "2022-09-15T21:07:03Z",
      "updated_by_user_id": "10001",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
    },
    {
      "created_at": "2022-09-26T22:24:15Z",
      "created_by_user_id": "123123",
      "custom_object_fields": {
        "make": "Honda",
        "model": "Civic"
      },
      "custom_object_key": "car",
      "external_id": null,
      "id": "01GDXYD7ZTWYP542BA8MDDTE36",
      "name": "My Tesla CO record2",
      "updated_at": "2022-09-26T22:24:15Z",
      "updated_by_user_id": "245159",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYD7ZTWYP542BA8MDDTE36"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/search?page%5Bafter%5D=eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0%3D&page%5Bsize%5D=1&query=",
    "prev": null
  },
  "meta": {
    "after_cursor": "eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0=",
    "before_cursor": null,
    "has_more": true
  }
}

Filtered Search of Custom Object Records

• POST /api/v2/custom_objects/{custom_object_key}/records/search

Returns an array of custom object records that meet the search and filter criteria. For simple searches limited to only text fields and no complex logic, use the Search Custom Object Records API endpoint.

If the object has a parent field with cascade_permissions_enabled, non-admin agents must include a filter on the parent field (for example, "custom_object_fields.parent_field_key": { "$eq": "parent_record_id" }). Requests without a parent filter return 403 Forbidden.

Filters can contain either an individual comparison object or an array of filter expressions within logical namespaces. Filter expressions can themselves be either comparison objects or $and / $or groups, so logical operators can be nested to build complex Boolean queries.

A filter is a JSON object that has the following properties:

Name	Type	Required	Description
ATTRIBUTE	object	no	A comparison object specifying an attribute value condition to be met for records to match. Examples are marked below.
$and	array	no	Array of filter expressions combined with logical AND. Each element may be a comparison object or a nested $and / $or group.
$or	array	no	Array of filter expressions combined with logical OR. Each element may be a comparison object or a nested $and / $or group.

Limits for nested $and / $or groups:

• Maximum nesting depth: 5 (outermost $and / $or counts as level 1). Exceeding it returns 422 Invalid Condition.
• Attribute keys cannot share a level with $and / $or once the payload contains any $and / $or nested inside another $and / $or. The request returns 422 Invalid Condition; wrap the attribute inside the group instead.

Examples

{
  "filter": {
    "custom_object_fields.field_key": { "$eq": "value" } // ATTRIBUTE
  }
}

{
  "filter": {
    "$or": [
      { "custom_object_fields.field_key": { "$eq": "value" } }, // ATTRIBUTE
      { "external_id": { "$eq": "Record123" } } // ATTRIBUTE
    ]
  }
}

// Nested $and / $or
{
  "filter": {
    "$and": [
      { "custom_object_fields.contract_term_months": { "$gt": 5 } },
      {
        "$or": [
          { "custom_object_fields.status": { "$eq": "active" } },
          { "custom_object_fields.status": { "$eq": "pending" } }
        ]
      }
    ]
  }
}

Comparison Object

A comparison object defines a condition a record must meet to be considered a match. The condition is based on an attribute value or object type.

A comparison object is a JSON object that has the following properties:

Name	Type	Required	Description
FIELD_KEY	string	yes	When filtering on a custom field, they must be namedspaced with custom_object_fields.. ex. custom_object_fields.field_key When filtering on a standard field, no namespace is required. The following fields are considered standard: created_at, updated_at, created_by_user, updated_by_user, name, external_id
OPERATOR	string	yes	Supported operators vary by the value's data type
VALUE	string, array	yes	The value you're filtering for

• Date values should be in ISO 8601 format.

Pagination

• Cursor pagination only.
• Returns the records sorted by relevancy with page limits. Without a sort parameter, only the first 10,000 records are returned. With a sort parameter, all records are returned.

Allowed For

• Agents
• End users (when an admin configures the custom object to be accessible to end users)

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.after_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[before]	string	Query	false	A pagination cursor that tells the endpoint which page to start on. It should be a meta.before_cursor value from a previous request. Note: page[before] and page[after] can't be used together in the same request.
page[size]	integer	Query	false	Specifies how many records should be returned in the response. You can specify up to 100 records per page.
query	string	Query	false	The query parameter is used to search text-based fields for records that match specific query terms. The query can be multiple words or numbers. Every record that matches the beginning of any word or number in the query string is returned. Fuzzy search is supported for the following text-based field types: Text fields, Multi Line Text fields, and RegExp fields. For example, you might want to search for records related to Tesla vehicles: query=Tesla. In this example the API would return every record for the given custom object where any of the supported text fields contain the word 'Tesla'. You can include multiple words or numbers in your search. For example: query=Tesla Honda 2020. This search phrase would be URL encoded as query=Tesla%20Honda%202020 and return every record for the custom object for which any of the supported text fields contained 'Tesla', 'Honda', or '2020'.
sort	string	Query	false	One of "name", "created_at", "updated_at", "-name", "-created_at", or "-updated_at". The "-" denotes the sort will be descending. Defaults to sorting by relevance.
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort="
	method := "POST"
	payload := strings.NewReader(`{
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/search")
		.newBuilder()
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("query", "jdoe")
		.addQueryParameter("sort", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"filter\": {
    \"$and\": [
      {
        \"custom_object_fields.key_one\": {
          \"$eq\": \"foo\"
        }
      },
      {
        \"custom_object_fields.key_two\": {
          \"$eq\": \"bar\"
        }
      }
    ],
    \"$or\": [
      {
        \"custom_object_fields.key_three\": {
          \"$eq\": \"foo\"
        }
      },
      {
        \"custom_object_fields.key_four\": {
          \"$eq\": \"bar\"
        }
      }
    ]
  }
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/search',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'page[after]': '',
    'page[before]': '',
    'page[size]': '',
    'query': 'jdoe',
    'sort': '',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort="

payload = json.loads("""{
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/search")
uri.query = URI.encode_www_form("page[after]": "", "page[before]": "", "page[size]": "", "query": "jdoe", "sort": "")
request = Net::HTTP::Post.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "filter": {
    "$and": [
      {
        "custom_object_fields.key_one": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_two": {
          "$eq": "bar"
        }
      }
    ],
    "$or": [
      {
        "custom_object_fields.key_three": {
          "$eq": "foo"
        }
      },
      {
        "custom_object_fields.key_four": {
          "$eq": "bar"
        }
      }
    ]
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records with name field matching Tesla

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=* \
  -d '{
        "filter": {
          "name": { "$eq": "Tesla" }
        }
      }'\
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with year fields matching 1998 or 2003

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=* \
  -d '{
        "filter": {
          "$or": [
            { "custom_object_fields.year": { "$eq": "1998" } },
            { "custom_object_fields.year": { "$eq": "1998" } }
          ]
        }
      }' \
  -H "Authorization: Bearer {access_token}"

curl - Get custom object records with year field matching 1998 and color field matching red

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=* \
  -d '{
        "filter": {
          "$and": [
            { "custom_object_fields.year": { "$eq": "1998" } },
            { "custom_object_fields.color": { "$eq": "red" } }
          ]
        }
      }' \
  -H "Authorization: Bearer {access_token}"

curl - Get records matching (contract_term > 5) AND (status = active OR status = pending)

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=* \
  -d '{
        "filter": {
          "$and": [
            { "custom_object_fields.contract_term_months": { "$gt": 5 } },
            {
              "$or": [
                { "custom_object_fields.status": { "$eq": "active" } },
                { "custom_object_fields.status": { "$eq": "pending" } }
              ]
            }
          ]
        }
      }' \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "count": 100,
  "custom_object_records": [
    {
      "created_at": "2022-09-12T19:29:59Z",
      "created_by_user_id": "10001",
      "custom_object_fields": {
        "make": "Tesla",
        "model": "S"
      },
      "custom_object_key": "car",
      "external_id": "Internal System Record 54848",
      "id": "01GCSJW391QVSC80GYDH7E93Q6",
      "name": "My Tesla CO record",
      "updated_at": "2022-09-15T21:07:03Z",
      "updated_by_user_id": "10001",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
    },
    {
      "created_at": "2022-09-26T22:24:15Z",
      "created_by_user_id": "123123",
      "custom_object_fields": {
        "make": "Honda",
        "model": "Civic"
      },
      "custom_object_key": "car",
      "external_id": null,
      "id": "01GDXYD7ZTWYP542BA8MDDTE36",
      "name": "My Tesla CO record2",
      "updated_at": "2022-09-26T22:24:15Z",
      "updated_by_user_id": "245159",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYD7ZTWYP542BA8MDDTE36"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/search?page%5Bafter%5D=eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0%3D&page%5Bsize%5D=1&query=",
    "prev": null
  },
  "meta": {
    "after_cursor": "eyJmcm9tIjoxLCJzaXplIjoxLCJzZWFyY2hBZnRlciI6bnVsbCwic29ydCI6bnVsbH0=",
    "before_cursor": null,
    "has_more": true
  }
}

Custom Object Records Limit

• GET /api/v2/custom_objects/limits/record_limit

List the current count and the limit for custom object records

Allowed For

• Agents

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/limits/record_limit \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

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

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/limits/record_limit")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/limits/record_limit',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/limits/record_limit"
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/limits/record_limit")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records count and limit

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/limits/record_limit \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "count": 10294,
  "limit": 1000000
}

Custom Object Record Bulk Jobs

• POST /api/v2/custom_objects/{custom_object_key}/jobs

Queues a background job to perform bulk actions on up to 100 custom object records per single request. Takes a job object with the following nested fields:

• action, one of:
  • "create"
  • "delete"
  • "delete_by_external_id"
  • "delete_by_unique_field"
  • "create_or_update_by_external_id"
  • "create_or_update_by_name"
  • "create_or_update_by_unique_field"
  • "update"
• items
  • For a "create" action, an array of JSON objects representing the custom object records being created
  • For a "delete" action, an array of strings representing Zendesk record ids
  • For a "delete_by_external_id" action, an array of strings representing external ids
  • For a "delete_by_unique_field" action, an array of strings representing values of the unique field named in unique_field_key
  • For a "create_or_update_by_external_id" action, an array of JSON objects representing the custom object records being created or updated by external id
  • For a "create_or_update_by_name" action, an array of JSON objects representing the custom object records being created or updated by name. The is_unique property on the custom object's name field must be enabled.
  • For a "create_or_update_by_unique_field" action, an array of JSON objects representing the custom object records being created or updated by the unique field named in unique_field_key. Each object must include that field's value in custom_object_fields.
  • For an "update" action, an array of JSON objects representing the custom object records being updated
• unique_field_key, required for the "create_or_update_by_unique_field" and "delete_by_unique_field" actions: the key of the custom object field that identifies the records. The field's is_unique property must be enabled. Use the *_by_name actions to identify records by name.

Note: If autonumbering is selected for the custom object's name field, record names aren't allowed in the request body because they are generated automatically. If uniqueness is enabled, the record names must be unique.

Identifying records by a unique field

Returns a 400 Bad Request with the error InvalidUniqueFieldKey if unique_field_key is missing or isn't the key of a unique field on the custom object.

In the job status results, each item of a "delete_by_unique_field" job reports the unique_field_key and value from the request, along with its index and status (for example, "Deleted"). An item that matches no record fails with "Record not found". Each item in a "create_or_update_by_unique_field" job reports the record's id, its index and status. An item without a value for the unique field fails with "Unique field value cannot be blank". If the field's uniqueness is turned off before the job runs, its items fail with "Uniqueness must be enabled on the field to identify records by it".

Allowed For

• Agents

Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See Job limit for more information.

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/custom_objects/car/jobs \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json" \
--data-raw '{
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/jobs"
	method := "POST"
	payload := strings.NewReader(`{
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/jobs")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"job\": {
    \"action\": \"create\",
    \"items\": [
      {
        \"custom_object_fields\": {
          \"color\": \"Red\",
          \"year\": 2020
        },
        \"name\": \"2020 Tesla\"
      },
      {
        \"custom_object_fields\": {
          \"color\": \"Blue\",
          \"external_id\": \"ddd444\",
          \"year\": 2012
        },
        \"name\": \"2012 Toyota\"
      },
      {
        \"custom_object_fields\": {
          \"color\": \"Silver\",
          \"external_id\": \"ddd445\",
          \"year\": 2017
        },
        \"name\": \"2017 Ford\"
      }
    ]
  }
}""");

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/jobs',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  data : data,
};

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

Python

import requests
import json

url = "https://example.zendesk.com/api/v2/custom_objects/car/jobs"

payload = json.loads("""{
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
}""")
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/jobs")
request = Net::HTTP::Post.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
request.body = %q({
  "job": {
    "action": "create",
    "items": [
      {
        "custom_object_fields": {
          "color": "Red",
          "year": 2020
        },
        "name": "2020 Tesla"
      },
      {
        "custom_object_fields": {
          "color": "Blue",
          "external_id": "ddd444",
          "year": 2012
        },
        "name": "2012 Toyota"
      },
      {
        "custom_object_fields": {
          "color": "Silver",
          "external_id": "ddd445",
          "year": 2017
        },
        "name": "2017 Ford"
      }
    ]
  }
})
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Create or update multiple custom object records by external id

For clarity, the example places the JSON in a separate file and imports it into the cURL statement. For the create_or_update_by_external_id action, each job item must include an external_id attribute. If a record exists for the external id, the record is updated. If a record does not exist for the external id, a new record is created.

my_job.json

{
  "job": {
      "action": "create_or_update_by_external_id",
      "items": [{ "name": "2020 Tesla", "external_id": "ddd443", "custom_object_fields": {  "color": "Red", "year": 2020 }},
                { "name": "2012 Toyota", "external_id": "ddd444", "custom_object_fields": {  "color": "Blue", "year": 2012 }},
                { "name": "2017 Ford",  "external_id": "ddd445", "custom_object_fields": {  "color": "Silver", "year": 2017 }}]
      }
}

curl - Create or update multiple custom object records by external id snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Delete multiple custom object records by a unique field

For clarity, the example places the JSON in a separate file and imports it into the cURL statement. For the delete_by_unique_field action, unique_field_key names the unique field and each job item is a value of that field.

my_job.json

{
  "job": {
      "action": "delete_by_unique_field",
      "unique_field_key": "vin",
      "items": ["5YJ3E1EA7LF000001", "4T1BF1FK5CU000002", "1FA6P8TH1H5000003"]
      }
}

curl - Delete multiple custom object records by a unique field snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Update multiple custom object records

For clarity, the example places the JSON in a separate file and imports it into the cURL statement. For the update action, each job item must include id attribute.

my_job.json

{
  "job": {
      "action": "update",
      "items": [{ "name": "2020 Tesla", "id": "01GCSJW391QVSC80GYDH7E93Q6", "custom_object_fields": {  "color": "Red", "year": 2020 }},
                { "name": "2012 Toyota", "id": "01GCSJW3A0QVSC80GYDH7E93Q7", "custom_object_fields": {  "color": "Blue", "year": 2012 }},
                { "name": "2017 Ford",  "id": "01GCSJW3A0QVSC80GYDH7E93Q8", "custom_object_fields": {  "color": "Silver", "year": 2017 }}]
      }
}

curl - Update multiple custom object records snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Create or update multiple custom object records by a unique field

For clarity, the example places the JSON in a separate file and imports it into the cURL statement. For the create_or_update_by_unique_field action, unique_field_key names the unique field and each job item must include that field's value in custom_object_fields. If a record exists for the value, the record is updated. If a record does not exist for the value, a new record is created.

my_job.json

{
  "job": {
      "action": "create_or_update_by_unique_field",
      "unique_field_key": "vin",
      "items": [{ "name": "2020 Tesla", "custom_object_fields": {  "vin": "5YJ3E1EA7LF000001", "color": "Red", "year": 2020 }},
                { "name": "2012 Toyota", "custom_object_fields": {  "vin": "4T1BF1FK5CU000002", "color": "Blue", "year": 2012 }},
                { "name": "2017 Ford", "custom_object_fields": {  "vin": "1FA6P8TH1H5000003", "color": "Silver", "year": 2017 }}]
      }
}

curl - Create or update multiple custom object records by a unique field snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Create or update multiple custom object records by Name

For clarity, the example places the JSON in a separate file and imports it into the cURL statement. For the create_or_update_by_name action, the is_unique property on the custom object's name field must be enabled. If a record exists for the name, the record is updated. If a record does not exist for the name, a new record is created.

my_job.json

{
  "job": {
      "action": "create_or_update_by_name",
      "items": [{ "name": "2020 Tesla", "custom_object_fields": {  "color": "Red", "year": 2020 }},
                { "name": "2012 Toyota", "custom_object_fields": {  "color": "Blue", "year": 2012 }},
                { "name": "2017 Ford", "custom_object_fields": {  "color": "Silver", "year": 2017 }}]
      }
}

curl - Create or update multiple custom object records by Name snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Create multiple custom object records

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_job.json

{
  "job": {
      "action": "create",
      "items": [{ "name": "2020 Tesla", "custom_object_fields": {  "color": "Red",    "year": 2020 }},
                { "name": "2012 Toyota","custom_object_fields": {  "color": "Blue",   "year": 2012 }},
                { "name": "2017 Ford",  "custom_object_fields": {  "color": "Silver", "year": 2017 }}]
      }
}

curl - Create multiple custom object records snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Delete multiple custom object records by External ID

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_job.json

{
  "job": {
      "action": "delete_by_external_id",
      "items": ["ddd444", "ddd445", "ddd446"]
      }
}

curl - Delete multiple custom object records by External ID snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

curl - Delete multiple custom object records by ID

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_job.json

{
  "job": {
      "action": "delete",
      "items": ["01GCSJW391QVSC80GYDH7E93Q6", "01GCSJW3A0QVSC80GYDH7E93Q7", "01GCSJW3A0QVSC80GYDH7E93Q8"]
      }
}

curl - Delete multiple custom object records by ID snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/jobs \
  -d @my_job.json \
  -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST

Example response(s)

201 Created

// Status 201 Created

{
  "job_status": {
    "id": "V3-291e720c98aef4d953563ab090486213",
    "message": null,
    "progress": null,
    "results": null,
    "status": "queued",
    "total": 2,
    "url": "https://{subdomain}.zendesk.com/api/v2/job_statuses/V3-291e720c98aef4d953563ab090486213"
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "description": "job.unique_field_key must be the key of a unique field on the car custom object",
  "error": "InvalidUniqueFieldKey"
}

Delete Custom Object Record by External Id Or Name

• DELETE /api/v2/custom_objects/{custom_object_key}/records

Deletes a record with the specified external id, name, or unique field value. Specify only one identifier per request.

• The is_unique property on the custom object's name field must be enabled in order to delete by name.
• To delete by a unique field, send the field's key as the query parameter, for example ?vin=1HGCM82633A004352. The field's is_unique property must be enabled.

If the record is a parent in a parent-child relationship, all associated child records are also deleted asynchronously via a background job.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	false	The external id of a custom object record
name	string	Query	false	The name of a custom object record
unique_field_value	object	Query	false	A value of one of the custom object's unique fields, sent as {unique_field_key}={value}. For example, vin=1HGCM82633A004352 identifies the record whose unique field with the key "vin" holds that value. The field's is_unique property must be enabled.
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request DELETE https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value= \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value="
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat")
		.addQueryParameter("unique_field_value", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
    'unique_field_value': '',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat&unique_field_value="
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat", "unique_field_value": "")
request = Net::HTTP::Delete.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Delete custom object record by external id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?external_id={external_id} \
  -X DELETE \
  -H "Authorization: Bearer {access_token}"

curl - Delete custom object record by name

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?name={name} \
  -X DELETE \
  -H "Authorization: Bearer {access_token}"

curl - Delete custom object record by a unique field value

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?{unique_field_key}={value} \
  -X DELETE \
  -H "Authorization: Bearer {access_token}"

Example response(s)

204 No Content

// Status 204 No Content

null

Count Custom Object Records

• GET /api/v2/custom_objects/{custom_object_key}/records/count

Returns a total count of records for a specific custom object as well as the time the count was refreshed.

If the object has a parent field with cascade_permissions_enabled, non-admin agents receive a 403 Forbidden response. Use the Filtered Search endpoint with a filter on the parent field instead.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/records/count \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/count"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/count")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/count',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/count"
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/count")
request = Net::HTTP::Get.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object record count

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/count \
  -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK

// Status 200 OK

{
  "count": {
    "refreshed_at": "2022-09-02T22:44:35Z",
    "value": 7
  }
}

Delete Custom Object Record

• DELETE /api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}

Deletes a record with the specified id.

If the record is a parent in a parent-child relationship, all associated child records are also deleted asynchronously via a background job. Child records are soft-deleted first and then permanently deleted after a 30-day retention period. The delete request returns immediately; the cascade deletion happens in the background.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object
custom_object_record_id	string	Path	true	The id of a custom object record

Code Samples

Curl

curl --request DELETE https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6 \
--header "Authorization: Bearer ${authToken}" \
--header "Content-Type: application/json"

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Authorization", "Bearer ${authToken}")
	req.Header.Add("Content-Type", "application/json")

	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/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Authorization", "Bearer ${authToken}")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6',
  headers: {
	'Authorization': 'Bearer ${authToken}',
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6"
headers = {
	"Authorization": "Bearer ${authToken}",
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
request = Net::HTTP::Delete.new(uri, "Authorization": "Bearer ${authToken}", "Content-Type": "application/json")
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Delete custom object record by id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id} \
  -X DELETE \
  -H "Authorization: Bearer {access_token}"

Example response(s)

204 No Content

// Status 204 No Content

null