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.

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

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 "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("filter[external_ids]", "")
		.addQueryParameter("filter[ids]", "")
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("sort", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  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
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/records?filter[external_ids]=&filter[ids]=&page[after]=&page[before]=&page[size]=&sort="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
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, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records based on relevance

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records.json \
  -v -u {email_address}/token:{api_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 \
  -v -u {email_address}/token:{api_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 \
  -v -u {email_address}/token:{api_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.json?page[size]=10sort=-updated_at  \
  -v -u {email_address}/token:{api_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.json"
    },
    {
      "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.json"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records.json?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 "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

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

print(response.text)

Ruby

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

curl - Get custom object record by id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}.json \
  -v -u {email_address}/token:{api_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",
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21.json"
  }
}

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.

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 "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/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\"
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');
var 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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

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

Python

import requests
import json
from requests.auth import HTTPBasicAuth

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 = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Tesla",
      "model": "Y"
    },
    "name": "My car 1"
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

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.json \
  -d @my_object.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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",
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21.json"
  }
}

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

Code Samples

Curl

curl --request PATCH https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6 \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

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

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

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

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

Java

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

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

Nodejs

var axios = require('axios');

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

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

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

print(response.text)

Ruby

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

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}.json \
-d @updated_record.json \
-H "Content-Type: application/json" -X PATCH \
-v -u {email_address}/token:{api_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",
    "updated_at": "2022-09-26T22:25:10Z",
    "updated_by_user_id": "10001",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/01GDXYEY1FQYN066VHF49YHJ21.json"
  }
}

Set Custom Object Record by External Id Or Name

• PATCH /api/v2/custom_objects/{custom_object_key}/records?external_id={external_id}&name={name}

If a record exists for the given external id or name, updates it. Only the specified attributes are updated. Otherwise, creates a new record with the provided external id, name and other attributes. The is_unqiue property on the custom object's name field must be enabled in order to update or create by name. External id and name cannot be used together in the same request.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	true	The external id of a custom object record
name	string	Query	true	The name of a custom object record
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 \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--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"
	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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_record\": {
    \"custom_object_fields\": {
      \"make\": \"Oldsmobile\",
      \"model\": \"Cutlass Supreme\"
    },
    \"name\": \"1997 Cutlass Supreme\"
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
  },
  data : data,
};

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

Python

import requests
import json
from requests.auth import HTTPBasicAuth

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

payload = json.loads("""{
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records")
uri.query = URI.encode_www_form("external_id": "X90001", "name": "boat")
request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")
request.body = %q({
  "custom_object_record": {
    "custom_object_fields": {
      "make": "Oldsmobile",
      "model": "Cutlass Supreme"
    },
    "name": "1997 Cutlass Supreme"
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

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.json?external_id={external_id} \
  -d @my_object.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json?name={name} \
  -d @my_object.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json"
  }
}

Delete Custom Object Record

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

Deletes a record with the specified 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 DELETE https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6 \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records/01GCSJW391QVSC80GYDH7E93Q6")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

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

print(response.text)

Ruby

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

curl - Delete custom object record by id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}.json \
  -X DELETE \
  -v -u {email_address}/token:{api_token}

Example response(s)

204 No Content

// Status 204 No Content

null

Delete Custom Object Record by External Id Or Name

• DELETE /api/v2/custom_objects/{custom_object_key}/records?external_id={external_id}&name={name}

Deletes a record with the specified external id or name. The is_unique property on the custom object's name field must be enabled in order to delete by name. External id and name cannot be used together in the same request.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
external_id	string	Query	true	The external id of a custom object record
name	string	Query	true	The name of a custom object record
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 \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

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

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

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records")
		.newBuilder()
		.addQueryParameter("external_id", "X90001")
		.addQueryParameter("name", "boat");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'external_id': 'X90001',
    'name': 'boat',
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/records?external_id=X90001&name=boat"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

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

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}.json \
  -X DELETE \
  -v -u {email_address}/token:{api_token}

curl - Delete custom object record by name

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records?name={name}.json \
  -X DELETE \
  -v -u {email_address}/token:{api_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.

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 "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records/count")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

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

print(response.text)

Ruby

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

curl - Get custom object record count

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/count.json \
  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK

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

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.

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.
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=&name=&organization_id=5633330889598&page[after]=&page[before]=&page[size]=&requester_id=264817272&source= \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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=&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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete")
		.newBuilder()
		.addQueryParameter("assignee_id", "7334148660734")
		.addQueryParameter("field_id", "")
		.addQueryParameter("name", "")
		.addQueryParameter("organization_id", "5633330889598")
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("requester_id", "264817272")
		.addQueryParameter("source", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'assignee_id': '7334148660734',
    'field_id': '',
    '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
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete?assignee_id=7334148660734&field_id=&name=&organization_id=5633330889598&page[after]=&page[before]=&page[size]=&requester_id=264817272&source="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/records/autocomplete")
uri.query = URI.encode_www_form("assignee_id": "7334148660734", "field_id": "", "name": "", "organization_id": "5633330889598", "page[after]": "", "page[before]": "", "page[size]": "", "requester_id": "264817272", "source": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get records with name matching Tesla

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/autocomplete?name=Tesla \
  -v -u {email_address}/token:{api_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 \
  -v -u {email_address}/token:{api_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 \
  -v -u {email_address}/token:{api_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.json"
    },
    {
      "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.json"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/autocomplete.json?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 that meet the search criteria

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 --request GET https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort= \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/car/records/search")
		.newBuilder()
		.addQueryParameter("page[after]", "")
		.addQueryParameter("page[before]", "")
		.addQueryParameter("page[size]", "")
		.addQueryParameter("query", "jdoe")
		.addQueryParameter("sort", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  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
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/records/search?page[after]=&page[before]=&page[size]=&query=jdoe&sort="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
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, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object records with fields matching Tesla

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=Tesla \
  -v -u {email_address}/token:{api_token}

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

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=1998%202003 \
  -v -u {email_address}/token:{api_token}

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

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=Tesla&sort=created_at \
  -v -u {email_address}/token:{api_token}

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

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=Tesla&sort=-name \
  -v -u {email_address}/token:{api_token}

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

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/records/search?query=Tesla&page[before]=cursor_value&page[size]=10 \
  -v -u {email_address}/token:{api_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.json"
    },
    {
      "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.json"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/search.json?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.

Filters can contain either an individual comparison object or an array of comparison objects within logical namespaces.

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 conjunctive filter objects (logical AND)
$or	array	no	Array of conjunctive filter objects (logical OR)

Examples

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

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

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

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_four": {
        "$eq": "bar"
      },
      "custom_object_fields.key_three": {
        "$eq": "foo"
      }
    }
  }
}

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 "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
  "filter": {
    "$and": {
      "custom_object_fields.key_one": {
        "$eq": "foo"
      },
      "custom_object_fields.key_two": {
        "$eq": "bar"
      }
    },
    "$or": {
      "custom_object_fields.key_four": {
        "$eq": "bar"
      },
      "custom_object_fields.key_three": {
        "$eq": "foo"
      }
    }
  }
}'

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_four": {
        "$eq": "bar"
      },
      "custom_object_fields.key_three": {
        "$eq": "foo"
      }
    }
  }
}`)
	req, err := http.NewRequest(method, url, payload)

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

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/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_four\": {
        \"$eq\": \"bar\"
      },
      \"custom_object_fields.key_three\": {
        \"$eq\": \"foo\"
      }
    }
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

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

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/records/search',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  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
from requests.auth import HTTPBasicAuth

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_four": {
        "$eq": "bar"
      },
      "custom_object_fields.key_three": {
        "$eq": "foo"
      }
    }
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
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, "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_four": {
        "$eq": "bar"
      },
      "custom_object_fields.key_three": {
        "$eq": "foo"
      }
    }
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

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" }
        }
      }'\
  -v -u {email_address}/token:{api_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" } }
          ]
        }
      }' \
  -v -u {email_address}/token:{api_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" } }
          ]
        }
      }' \
  -v -u {email_address}/token:{api_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.json"
    },
    {
      "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.json"
    }
  ],
  "links": {
    "next": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/records/search.json?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 "Content-Type: application/json" \
-u {email_address}/token:{api_token}

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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/custom_objects/limits/record_limit")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

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

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

print(response.text)

Ruby

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

curl - Get custom object records count and limit

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/limits/record_limit \
  -v -u {email_address}/token:{api_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 two nested fields:

• action, one of:
  • "create"
  • "delete"
  • "delete_by_external_id"
  • "create_or_update_by_external_id"
  • "create_or_update_by_name"
  • "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 "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 an "update" action, an array of JSON objects representing the custom object records being updated

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.

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 "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--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("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

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

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

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/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\"
      }
    ]
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');
var 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: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

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

Python

import requests
import json
from requests.auth import HTTPBasicAuth

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 = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

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

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/jobs")
request = Net::HTTP::Post.new(uri, "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"
      }
    ]
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST

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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json \
  -d @my_job.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_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.json"
  }
}