Use this API to ingest external content records for search. The help center search engine indexes and ranks the content. When an end user clicks an external content search result, they're taken to the URL of the external content record.

For more information, see Introduction and Setting up Zendesk Federated Search in your help center in Zendesk help.

JSON Format

Records are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
body string false true The body of the record
created_at string false false ISO-8601 compliant date-time reflecting the time the event was created. If not set, the API sets the value when it receives the event
external_id string false true A string that uniquely identifies the record in your system
id string true false Universally Unique Lexicographically Sortable Identifier. See https://github.com/ulid/spec
locale string false true Record locale. Must match a locale already enabled in your help center in order to be returned in search. See Zendesk language support by product in Zendesk help
source_id string false true Universally Unique Lexicographically Sortable Identifier. See https://github.com/ulid/spec
title string false true The title of the record
type_id string false true Universally Unique Lexicographically Sortable Identifier. See https://github.com/ulid/spec
updated_at string false false ISO-8601 compliant date-time reflecting the time the event was last updated
url string false true An accessible URL for the record in your system
user_segment_id string false false The Guide user segment which this record should be visible to. If not set, the record will be visible to all users

List External Content Records

  • GET /api/v2/guide/external_content/records

Lists external content records.

Allowed For

  • Help Center managers

Parameters

Name Type In Required Description
page object Query false Paginate query

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/external_content/records \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "meta": {    "after_cursor": "MW",    "before_cursor": "MQ",    "has_more": true  },  "records": [    {      "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",      "created_at": "2020-07-08T12:27:26Z",      "external_id": "360046759835",      "id": "01EC05A5T1J4ZSDJX4Q8JGFRHP",      "locale": "en-us",      "source": {        "id": "01E77R4513SKX3AE8H20Q0KJ1K",        "name": "My Library"      },      "title": "How to leave feedback for Federated Help Center search",      "type": {        "id": "01EBDWWC98ZF7DK9YQF3DK9Y77",        "name": "Blog"      },      "updated_at": "2020-07-08T12:27:26Z",      "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",      "user_segment_id": "-1"    }  ]}

Show External Content Record

  • GET /api/v2/guide/external_content/records/{id}

Gets the specified external content record.

Allowed For

  • Help Center managers

Parameters

Name Type In Required Description
id string Path true ULID for the object

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/external_content/records/{id} \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "record": {    "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",    "created_at": "2020-07-08T12:27:26Z",    "external_id": "360046759835",    "id": "01EC05A5T1J4ZSDJX4Q8JGFRHP",    "locale": "en-us",    "source": {      "id": "01E77R4513SKX3AE8H20Q0KJ1K",      "name": "My Library"    },    "title": "How to leave feedback for Federated Help Center search",    "type": {      "id": "01EBDWWC98ZF7DK9YQF3DK9Y77",      "name": "Blog"    },    "updated_at": "2020-07-08T12:27:26Z",    "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",    "user_segment_id": "-1"  }}

Create External Content Record

  • POST /api/v2/guide/external_content/records

Creates an external content record. Specify a type_id and source_id for this request. You can retrieve the ids using List External Content Types and List External Content Sources.

Allowed For

  • Help Center managers

Example Body

{  "record": {    "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",    "external_id": "360046759835",    "locale": "en-us",    "source_id": "01E77R4513SKX3AE8H20Q0KJ1K",    "title": "How to leave feedback for Federated Help Center search",    "type_id": "01EBDWWC98ZF7DK9YQF3DK9Y77",    "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",    "user_segment_id": "-1"  }}

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/external_content/records \  -d '{ "record": { "title": "Mansfield Park", "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8", "locale": "en-uk", "body": "Before his return Mrs. Grant and Miss Crawford came in.", "external_id": "mansfieldpark8", "user_segment_id": null, "type_id": "01E77R7P0S8QKHPV07VKXH65S3", "source_id": "01E7GZVZHBWYD50V00XDMYCMYP" }}' \  -H "Content-Type: application/json" \  -v -u {email_address}:{password} -X POST

Example Response

Status 201 Created
{  "record": {    "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",    "created_at": "2020-07-08T12:27:26Z",    "external_id": "360046759835",    "id": "01EC05A5T1J4ZSDJX4Q8JGFRHP",    "locale": "en-us",    "source": {      "id": "01E77R4513SKX3AE8H20Q0KJ1K",      "name": "My Library"    },    "title": "How to leave feedback for Federated Help Center search",    "type": {      "id": "01EBDWWC98ZF7DK9YQF3DK9Y77",      "name": "Blog"    },    "updated_at": "2020-07-08T12:27:26Z",    "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",    "user_segment_id": "-1"  }}

Update External Content Record

  • PUT /api/v2/guide/external_content/records/{id}

Updates the specified record with the request body.

Allowed For

  • Help Center managers

Parameters

Name Type In Required Description
id string Path true ULID for the object

Example Body

{  "record": {    "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",    "external_id": "360046759835",    "locale": "en-us",    "source_id": "01E77R4513SKX3AE8H20Q0KJ1K",    "title": "How to leave feedback for Federated Help Center search",    "type_id": "01EBDWWC98ZF7DK9YQF3DK9Y77",    "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",    "user_segment_id": "-1"  }}

Using curl

curl "https://{subdomain}.zendesk.com/api/v2/guide/external_content/records/{id}"  \  -d '{ "record": { "title": "Mansfield Park", "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8", "locale": "en-uk", "body": "Before his return Mrs. Grant and Miss Crawford came in.", "external_id": "mansfieldpark8", "user_segment_id": null, "type_id": "01E77R7P0S8QKHPV07VKXH65S3", "source_id": "01E7GZVZHBWYD50V00XDMYCMYP" }}' \  -H "Content-Type: application/json" \  -v -u {email_address}:{password} -X PUT

Example Response

Status 200 OK
{  "record": {    "body": "We want to hear what you have to say about external content search, because ultimately we're building it for you. Below, you can find some guidelines on the best ways to let us know what you think. Right here -- this forum is the best place. With this format, we can respond to questions or comments so that everyone can see and benefit. We also encourage you to make it as social and collaborative as possible, so jump in if you have an idea that might help someone else.",    "created_at": "2020-07-08T12:27:26Z",    "external_id": "360046759835",    "id": "01EC05A5T1J4ZSDJX4Q8JGFRHP",    "locale": "en-us",    "source": {      "id": "01E77R4513SKX3AE8H20Q0KJ1K",      "name": "My Library"    },    "title": "How to leave feedback for Federated Help Center search",    "type": {      "id": "01EBDWWC98ZF7DK9YQF3DK9Y77",      "name": "Blog"    },    "updated_at": "2020-07-08T12:27:26Z",    "url": "https://support.zendesk.com/hc/en-us/community/posts/360046759834-How-to-leave-feedback-for-Federated-Help-Center-search",    "user_segment_id": "-1"  }}

Delete External Content Record

  • DELETE /api/v2/guide/external_content/records/{id}

Deletes the specified record.

Allowed For

  • Help Center managers

Parameters

Name Type In Required Description
id string Path true ULID for the object

Using curl

curl https://{subdomain}.zendesk.com/api/v2/guide/external_content/records/{id} \  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content