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 which have the following keys:

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
Available 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>
Example Response
Status 200

{
  "meta": {
    "after_cursor": "MTA",
    "before_cursor": "MQ",
    "has_more": true
  },
  "records": [{
      "body": "Before his return Mrs. Grant and Miss Crawford came in.",
      "created_at": "2020-05-05T00:08:21Z",
      "external_id": "mansfieldpark8",
      "id": "01E7GZVZHBWYD50V00XDMYCMYP",
      "locale": "en-uk",
      "source": {
          "id": "01E7GZVZHB39350V00XDMYCMYP",
          "name": "My Library"
      },
      "title": "Mansfield Park",
      "type": {
          "id": "01E7GZVZHB39350V00XDMYCMYP",
          "name": "Book"
      },
      "updated_at": "2020-05-05T00:08:21Z",
      "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
      "user_segment_id": "-1"
  }]
}

Creates an external content record

  • POST /api/v2/guide/external_content/records
Example Body
{
  "body": "Before his return Mrs. Grant and Miss Crawford came in.",
  "created_at": "2020-05-05T00:08:21Z",
  "external_id": "mansfieldpark8",
  "id": "01E7GZVZHBWYD50V00XDMYCMYP",
  "locale": "en-uk",
  "source_id": "01E7GZVZHB39350V00XDMYCMYP",
  "title": "Mansfield Park",
  "type_id": "01E7GZVZHB39350V00XDMYCMYP",
  "updated_at": "2020-05-05T00:08:21Z",
  "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
  "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

{
  "record": {
    "body": "Before his return Mrs. Grant and Miss Crawford came in.",
    "created_at": "2020-05-05T00:08:21Z",
    "external_id": "mansfieldpark8",
    "id": "01E7GZVZHBWYD50V00XDMYCMYP",
    "locale": "en-uk",
    "source_id": "01E7GZVZHB39350V00XDMYCMYP",
    "title": "Mansfield Park",
    "type_id": "01E7GZVZHB39350V00XDMYCMYP",
    "updated_at": "2020-05-05T00:08:21Z",
    "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
    "user_segment_id": "-1"
  }
}

Get an external record

  • GET /api/v2/guide/external_content/records/{id}
Available 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

{
  "record": {
    "body": "Before his return Mrs. Grant and Miss Crawford came in.",
    "created_at": "2020-05-05T00:08:21Z",
    "external_id": "mansfieldpark8",
    "id": "01E7GZVZHBWYD50V00XDMYCMYP",
    "locale": "en-uk",
    "source_id": "01E7GZVZHB39350V00XDMYCMYP",
    "title": "Mansfield Park",
    "type_id": "01E7GZVZHB39350V00XDMYCMYP",
    "updated_at": "2020-05-05T00:08:21Z",
    "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
    "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.

Available Parameters
Name Type In Required Description
id string Path true ULID for the object
Example Body
{
  "record": {
    "body": "Before his return Mrs. Grant and Miss Crawford came in.",
    "created_at": "2020-05-05T00:08:21Z",
    "external_id": "mansfieldpark8",
    "id": "01E7GZVZHBWYD50V00XDMYCMYP",
    "locale": "en-uk",
    "source_id": "01E7GZVZHB39350V00XDMYCMYP",
    "title": "Mansfield Park",
    "type_id": "01E7GZVZHB39350V00XDMYCMYP",
    "updated_at": "2020-05-05T00:08:21Z",
    "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
    "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

{
  "record": {
    "body": "Before his return Mrs. Grant and Miss Crawford came in.",
    "created_at": "2020-05-05T00:08:21Z",
    "external_id": "mansfieldpark8",
    "id": "01E7GZVZHBWYD50V00XDMYCMYP",
    "locale": "en-uk",
    "source_id": "01E7GZVZHB39350V00XDMYCMYP",
    "title": "Mansfield Park",
    "type_id": "01E7GZVZHB39350V00XDMYCMYP",
    "updated_at": "2020-05-05T00:08:21Z",
    "url": "http://www.publicbookshelf.com/regency/mansfield-park/mansfieldpark8",
    "user_segment_id": "-1"
  }
}

Deletes a record

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

Given an id, delete the corresponding record.

Available 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}