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.

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

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`

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.

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