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)