Federated Search - External Content Record API

This API is for managing external records. Once you have created records with sources and types, they will be made available for searching from the Help Center front end.

Important: The External Content API is in early access. This API is subject to change and should not be used in a production environment. Visit the Federated Search EAP forum for more information and to provide feedback.

Allowed for:
  • Help Center managers

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. More info: 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 this Help Center article for more details on locales in Help Center.
source_id string false true Universally Unique Lexicographically Sortable Identifier. More info: https://github.com/ulid/spec
title string false true The title of the record
type_id string false true Universally Unique Lexicographically Sortable Identifier. More info: 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.

Lists external records

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

Lists external records

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" -u <email_address>:<password>
curl -g "https://{subdomain}.zendesk.com/api/v2/guide/external_content/records?page[after]={after_cursor}" \
  -u {email_address}:{password}
curl -g "https://{subdomain}.zendesk.com/api/v2/guide/external_content/records?page[before]={before_cursor}" \
  -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"
    }
  ]
}

Creates an external content record

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

Creates an external content record

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"    }}' -u <email_address>:<password>
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"
  }
}

Get an external record

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

Get a single record for a given account with a given id

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}" \
  -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"
  }
}

Updates a record

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

Updates the record identified by the given ID with the request body.

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/01EA23X9NHVYW04WAPXZDV5EJF" -X PUT -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"    }}'\
  -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"
  }
}

Deletes a record

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

Given an id, delete the corresponding record.

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/01EA23X9NHVYW04WAPXZDV5EJF" -X DELETE \
-u {email_address}:{password}
Example Response
Status 204 No Content