openapi: 3.1.0
info:
version: '1.0'
title: Zendesk Account Account Settings Custom Object Records API
description: Needs a description.
tags:
- name: Custom Object Records
paths:
/api/v2/custom_objects/{custom_object_key}/records/autocomplete:
get:
operationId: AutocompleteCustomObjectRecordSearch
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Records Autocomplete
description: 'Retrieves an array of custom object records that have a field value that matches the value specified in the `name` parameter.
#### Pagination
* [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only.
* Returns the first 10,000 records sorted by relevancy with page limits.
#### Allowed For
* Agents'
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- name: name
in: query
description: Part of a name of the record you are searching for
schema:
type: string
- name: page[before]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[after]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[size]
in: query
description: 'The number of records to return in the response. You can specify up to 100 records per page.
'
schema:
type: integer
- name: field_id
in: query
description: '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.
'
schema:
type: string
- name: source
in: query
description: '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.
'
schema:
type: string
- name: filter[dynamic_values]
in: query
description: 'Provided values to be used with [dynamic filters](/api-reference/ticketing/lookup_relationships/lookup_relationships/#using-dynamic-filters).
'
style: deepObject
explode: true
schema:
type: object
additionalProperties:
type: integer
example:
ticket_fields_123: 123
- name: requester_id
in: query
description: 'The id of the requester. For use with dynamic filters.
'
schema:
type: integer
example: 264817272
- name: assignee_id
in: query
description: 'The id of the selected assignee. For use with dynamic filters.
'
schema:
type: integer
example: 7334148660734
- name: organization_id
in: query
description: 'The id of the organization the requester belongs to. For use with dynamic filters.
'
schema:
type: integer
example: 5633330889598
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsAutocompleteResponseExample'
/api/v2/custom_objects/{custom_object_key}/jobs:
post:
operationId: CustomObjectRecordBulkJobs
tags:
- Custom Object Records
summary: Zendesk Post Api V2 Custom_objects Custom_object_key Jobs
description: "Queues a background job to perform bulk actions on up to 100 custom object records per single request.\nTakes a `job` object with two nested fields:\n* `action`, one of:\n * `\"create\"`\n * `\"delete\"`\n * `\"delete_by_external_id\"`\n * `\"create_or_update_by_external_id\"`\n * `\"create_or_update_by_name\"`\n * `\"update\"`\n* `items`\n * For a `\"create\"` action, an array of JSON objects representing the custom object records being created\n * For a `\"delete\"` action, an array of strings representing Zendesk record ids\n * For a `\"delete_by_external_id\"` action, an array of strings representing external ids\n * 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\n * 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.\n * For an `\"update\"` action, an array of JSON objects representing the custom object records being updated\n\nNote: 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.\n\n#### Allowed For\n* Agents\n\n#### Response ###\nThis endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#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](/api-reference/introduction/rate-limits/#job-limit) for more information.\n"
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsBulkCreateRequest'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsBulkCreateRequestExample'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsJobsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsJobsResponseExample'
/api/v2/custom_objects/{custom_object_key}/records:
get:
operationId: ListCustomObjectRecords
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Records
description: "Lists all undeleted custom object records for the specified object\n\n #### Pagination\n\n* [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only.\n#### Allowed For\n* Agents"
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- name: filter[ids]
in: query
description: 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.
schema:
type: string
examples:
multipleIds:
summary: Example of multiple ids
value: id_1,id_2,id_3
oneId:
summary: Example of a single id
value: id_1
- name: filter[external_ids]
in: query
description: 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.
schema:
type: string
examples:
multipleIds:
summary: Example of multiple ids
value: ex_id_1,ex_id_2,ex_id_3
oneId:
summary: Example of a single id
value: ex_id_1
- name: sort
in: query
description: 'One of `id`, `updated_at`, `-id`, or `-updated_at`. The `-` denotes the sort will be descending.
'
schema:
type: string
- name: page[before]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[after]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[size]
in: query
description: 'Specifies how many records should be returned in the response. You can specify up to 100 records per page.
'
schema:
type: integer
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsIndexResponseExample'
post:
operationId: CreateCustomObjectRecord
tags:
- Custom Object Records
summary: Zendesk Post Api V2 Custom_objects Custom_object_key Records
description: '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:
- $ref: '#/components/parameters/CustomObjectKey'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsCreateRequest'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsCreateRequestExample'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsCreateResponseExample'
patch:
operationId: UpsertCustomObjectRecordByExternalIdOrName
tags:
- Custom Object Records
summary: Zendesk Patch Api V2 Custom_objects Custom_object_key Records
description: '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:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/CustomObjectRecordExternalId'
- $ref: '#/components/parameters/CustomObjectRecordName'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsUpsertRequest'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsUpsertRequestExample'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsUpsertResponseExample'
delete:
operationId: DeleteCustomObjectRecordByExternalIdOrName
tags:
- Custom Object Records
summary: Zendesk Delete Api V2 Custom_objects Custom_object_key Records
description: '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:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/CustomObjectRecordExternalId'
- $ref: '#/components/parameters/CustomObjectRecordName'
responses:
'204':
description: No content response
/api/v2/custom_objects/{custom_object_key}/records/{custom_object_record_id}:
get:
operationId: ShowCustomObjectRecord
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Records Custom_object_record_id
description: 'Returns a custom record for a specific object using a provided id.
#### Allowed For
* Agents
'
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/CustomObjectRecordId'
responses:
'200':
description: Custom Object Record
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsCreateResponseExample'
patch:
operationId: UpdateCustomObjectRecord
tags:
- Custom Object Records
summary: Zendesk Patch Api V2 Custom_objects Custom_object_key Records Custom_object_record_id
description: '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:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/CustomObjectRecordId'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsCreateResponseExample'
delete:
operationId: DeleteCustomObjectRecord
tags:
- Custom Object Records
summary: Zendesk Delete Api V2 Custom_objects Custom_object_key Records Custom_object_record_id
description: 'Deletes a record with the specified id
#### Allowed For
* Agents'
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- $ref: '#/components/parameters/CustomObjectRecordId'
responses:
'204':
description: No content response
/api/v2/custom_objects/{custom_object_key}/records/count:
get:
operationId: CountCustomObjectRecords
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Records Count
description: 'Returns a total count of records for a specific custom object as well as the time the count was refreshed.
#### Allowed For
* Agents'
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
responses:
'200':
description: Success response
content:
application/json:
schema:
type: object
properties:
count:
type: object
additionalProperties:
properties:
refreshed_at:
description: The time the last count was performed
format: date-time
readOnly: true
type: string
value:
description: Number of records at the time of the latest count operation
readOnly: true
type: integer
examples:
default:
value:
count:
refreshed_at: '2022-09-02T22:44:35Z'
value: 7
/api/v2/custom_objects/{custom_object_key}/records/search:
get:
operationId: SearchCustomObjectRecords
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Custom_object_key Records Search
description: 'Returns an array of custom object records that meet the search criteria
#### Pagination
* [Cursor pagination](/api-reference/introduction/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:
- $ref: '#/components/parameters/CustomObjectKey'
- name: query
in: query
description: '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.<br/><br/>
Fuzzy search is supported for the following text-based field types: : Text fields, Multi Line Text fields, and RegExp fields.<br/><br/>
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''.<br/><br/>
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''.
'
schema:
type: string
example: jdoe
- name: sort
in: query
description: '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.
'
schema:
type: string
- name: page[before]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[after]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[size]
in: query
description: 'Specifies how many records should be returned in the response. You can specify up to 100 records per page.
'
schema:
type: integer
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsSearchResponseExample'
post:
operationId: FilteredSearchCustomObjectRecords
tags:
- Custom Object Records
summary: Zendesk Post Api V2 Custom_objects Custom_object_key Records Search
description: "Returns an array of custom object records that meet the search and filter criteria.\n\nFilters can contain either an individual [comparison object](#comparison-object) or an array of [comparison objects](#comparison-object) within logical namespaces.\n\nA filter is a JSON object that has the following properties:\n\n| Name | Type | Required | Description\n| --------- | ------ | -------- | -----------\n| ATTRIBUTE | object | no | A [comparison object](#comparison-object) specifying an attribute value condition to be met for records to match.<br/><br/>Examples are marked below.\n| $and | array | no | Array of conjunctive filter objects (logical AND)\n| $or | array | no | Array of conjunctive filter objects (logical OR)\n\n##### Examples\n\n\n```js\n{\n \"filter\": {\n \"custom_object_fields.field_key\": { \"$eq\": \"value\" } // ATTRIBUTE\n }\n}\n```\n\n```js\n// $or\n{\n \"filter\": {\n \"$or\": [\n { \"custom_object_fields.field_key\": { \"$eq\": \"value\" } }, // ATTRIBUTE\n { \"external_id\": { \"$eq\": \"Record123\" } } // ATTRIBUTE\n ]\n }\n}\n```\n\n#### Comparison Object\n\nA 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.\n\nA comparison object is a JSON object that has the following properties:\n\n| Name | Type | Required | Description\n| --------- | ------------- | -------- | -----------\n| FIELD_KEY | string | yes | When filtering on a custom field, they must be namedspaced with `custom_object_fields.`. ex. `custom_object_fields.field_key`<br/><br/>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`\n| OPERATOR | string | yes | [Supported operators](/documentation/custom-data/v2/searching-custom-object-records/) vary by the value's data type\n| VALUE | string, array | yes | The value you're filtering for\n\n#### Pagination\n\n* [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only.\n* 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.\n\n#### Allowed For\n\n* Agents\n* End users (when an admin [configures](https://support.zendesk.com/hc/en-us/articles/6034260247066) the custom object to be accessible to end users)"
parameters:
- $ref: '#/components/parameters/CustomObjectKey'
- name: query
in: query
description: '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.<br/><br/>
Fuzzy search is supported for the following text-based field types: Text fields, Multi Line Text fields, and RegExp fields.<br/><br/>
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''.<br/><br/>
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''.
'
schema:
type: string
example: jdoe
- name: sort
in: query
description: '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.
'
schema:
type: string
- name: page[before]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[after]
in: query
description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) 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.
'
schema:
type: string
- name: page[size]
in: query
description: 'Specifies how many records should be returned in the response. You can specify up to 100 records per page.
'
schema:
type: integer
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/CustomObjectRecordsFilteredSearchRequestBasic'
- $ref: '#/components/schemas/CustomObjectRecordsFilteredSearchRequestComplex'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsFilteredSearchRequestExample'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectRecordsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsSearchResponseExample'
/api/v2/custom_objects/limits/record_limit:
get:
operationId: CustomObjectRecordsLimit
tags:
- Custom Object Records
summary: Zendesk Get Api V2 Custom_objects Limits Record_limit
description: 'List the current count and the limit for custom object records
#### Allowed For
* Agents'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectLimitsResponse'
examples:
default:
$ref: '#/components/examples/CustomObjectRecordsLimitResponseExample'
components:
schemas:
CustomObjectLimitsResponse:
type: object
properties:
count:
type: integer
description: The current numnber of the requested resource
readOnly: true
limit:
type: integer
description: The maximum allowed number for the requested resource
readOnly: true
CustomObjectRecordResponse:
type: object
properties:
custom_object_record:
$ref: '#/components/schemas/CustomObjectRecord'
CustomObjectRecordsResponse:
type: object
properties:
count:
type: integer
description: The number of results returned for the current request
readOnly: true
custom_object_records:
type: array
items:
$ref: '#/components/schemas/CustomObjectRecord'
links:
type: object
properties:
next:
type: string
nullable: true
prev:
type: string
nullable: true
required:
- prev
- next
meta:
type: object
properties:
after_cursor:
type: string
nullable: true
before_cursor:
type: string
nullable: true
has_more:
type: boolean
required:
- has_more
- after_cursor
- before_cursor