Content Source | Yext Hitchhikers Platform

With the Content source, the records being passed into Content Endpoints are entities, meaning there will be one entity passed into the Content Endpoint as an input for every entity which matches the filter.

Filter

With the Content source, the accepted filter types are:

• savedFilterIds
• entityTypes

Filters of the same type will be linked together by an “OR” relationship, but different entityType and savedFilterIds will be linked by an “AND” relationship. For example, for a Content Endpoint with

• entityTypes = [“location”, “healthcareProfessional”] and savedFilterIds = [“123”, “456”]

the logic would be:

• [(EntityType in [“location”, “healthcareProfessional”]) AND (savedFilter in [“123”, “456”])

Source vs. Referenced Entities

The filter only applies to the base records processed by the Content Endpoint; this means that entities which do not match the filter can still be accessed when traversing relationships. However, this relationship data will always be produced in the context of the base record(s).

For example, if a Content Endpoint was filtered only to Healthcare Professional entity types, you could still access data across linked condition entity types, and linked facilities where the doctor worked. However, the Content Endpoint would only produce outputs (unique records) for Healthcare Professionals, and the data from the other types would be in the context of each Healthcare Professional.

Fields

The fields property is used to define the list of fields from the source records (see: Entities) which are included in the Content Endpoint. These fields are accessed using their field IDs, which are the external IDs for fields across Yext APIs and Configuration as Code.

Accessing Data Across Entity Relationships

In Yext, relationships are stored in fields. For example, I might have a field on my healthcareProfessional entity type called c_worksAt, which is a relationship (entity reference) field. In that field, I would store a pointer to all of the healthcareFacility entity types which a given doctor works at.

We access data across relationships using dot notation. A user specifies the field that the relationship is stored in, and the field on the entity across the relationship, with a period as the delimiter. For example, if I want to access the names of the Facilities which a doctor works at in the example above, I would use the syntax c_worksAt.name. Again, in this example, the c_worksAt field is part of the schema of the healthcareProfessional entityType, and the fields accessed across the relationship are part of the schema of the healthcareFacility entityType.

Note you can’t include both the top level field and subfields of that field in the same stream. If you want to use the HTML of a field, only include {fieldID}.html and not {fieldID}.

Content Endpoint-Specific Fields

There are a number of fields which can be accessed from the Content source which are not a part of the specific entity schema. These fields can be included for any Content Endpoint from the Content source.

All other Content fields are available from the Content source. These fields should be referenced using the Field ID.

meta object

ref_listings object

ref_reviewsAgg object

Example - Fetching Entities and Projecting Data from Linked Entities

Let’s look at a specific example. Say you want to use the Content API to search entity data from Yext Content.

Specifically, you would like to query for Healthcare Providers based on Insurances Accepted, and Conditions Treated. All of this information is stored across different entity types. Specifically, we have four entity types:

• Healthcare Professionals (entityType = healthcareProfessional)
• Insurance Plans (entityType = ce_insurancePlans)
• Conditions (entityType = ce_conditions)

These entities are related via Entity Relationships. The relationships are stored in fields on the entity types.

For example, c_insurancesAccepted is a field on the Healthcare Professional entity type which stores a list of related entities of type ce_insurancePlan. This relationship allows us to access data from a related Insurance Plan in the context of a specific Healthcare Professional. We access this relationship using dot notation.

As previously mentioned, you would like to be able to query Healthcare Professional entity types using related data from the aforementioned linked entities. It is important to understand that you want this data in the context of the Healthcare Professionals, so when you define the Content Endpoint, you specify this using a combination of source and filters.

{
  "$id": "providerEndpoint",
  "$schema": "https://schema.yext.com/config/streams/streams-endpoint/v1",
  "name": "Provider API",
  "stream": {
        "source": "content",
        "filter": {
              "entityTypes": ["healthcareProfessional"],
              "savedFilterIds": ["1234"]
         },
        "fields": [
          "id",
          "firstName",
          "lastName",
          "address",
          "description",
          "npi",
          "c_insurancesAccepted.name", // referencing the pointer to other entities stored in the c_insurancesAccepted field
          "c_insurancesAccepted.description",
          "c_conditionsTreated.name", // referencing the pointer to other entities stored in the c_conditionsTreated field
          "c_conditionsTreated.c_symptoms",
          "c_conditionsTreated.description",
          "c_conditionsTreated.c_therapies"
        ]
   },
  "fieldIndexes": [
    {"field": "npi"},
    {"field": "c_insurancesAccepted.name"},
    {"field": "c_conditionsTreated.name"}
  ]
}

Source

For the source, we’d choose Content, since the Healthcare Provider entities live in Yext Content.

Filter

For the filter, we filtered down to only the Healthcare Professional Entity Type, since we want each record returned by the API to be in the context of a specific Healthcare Professional Entity. You could also add a Saved Filter to my filter criteria. For example, if you only wanted to filter to some set of Healthcare Professionals who work within a specific network of Hospitals, you could created a Saved Filter based on some field(s) on the Healthcare Professional entity, and supply that Saved Filter in the filter criteria of the endpoint definition.

Fields

For fields, we want to include some fields from the Healthcare Professional entity type, such as the name, id, npi, and description of the entity.

We also want to access some data from the related entities. As previously mentioned, we use dot notation to access related entities. Specifically, the field where the relationship is stored comes before the dot, and the reference to a field on that related entity comes after the dot. For example, you can access the linked entities stored in the c_insurancedAccepted field, then use a dot to specify a field on the linked entities, so c_insurancesAccepted.name returns the name of any linked entities stored in that field for a given Healthcare Professional entity which is included in the Content Endpoint.

Note: Content Endpoints also supports “multi-hops”, allowing users to traverse relationships across multiple entities using the same dot notation on the field where the relationship(s) are stored.

FieldIndexes

We can query the Content Endpoint via API using any of the fields specified within the fieldIndexes property. For example, a query to this API could pass query terms for c_insurancesAccepted.name=Worlds%20Best%20Insurance&c_conditionsTreated.name=Rheumatoid%20Arthritis, and the API would return Healthcare Providers who accept “World’s Best Insurance” and treat “Rheumatoid Arthritis”. The JSON Document returned by the API would include all fields specified in the endpoint configuration; for example, the returned record would also include the description of the insurance plan pulled from the linked entity, and the symptoms, description, and therapies for the linked condition entities.

Example Request:

GET https://cdn.yextapis.com/v2/accounts/me/api/providerEndpoint?api_key={api_key}&v=20200408&c_insurancesAccepted.name=Worlds%20Best%20Insurance&c_conditionsTreated.name=Rheumatoid%20Arthritis

Example Response

{
   "response":{
      "docs":[
         {
            "id":"drjoesmith",
            "firstName":"Joe",
            "lastName":"Smith",
            "address":{
               "city":"New york",
               "countryCode":"US",
               "line1":"1 Madison ave",
               "postalCode":"10010",
               "region":"NY"
            },
            "description":"Voted the best orthopedic surgeon in NY 5 years running! ",
            "npi":"1558444216",
            "c_insurancesAccepted":[
               {
                  "name":"Worlds Best Insurance",
                  "description":"Worlds Best Insurance offers affordable health insurance plans for individuals and families"
               }
            ],
            "c_conditionsTreated":[
               {
                  "name":"Rheumatoid Arthritis",
                  "c_symptoms":[
                    "Joint Stiffness",
                    "Pain in the joints",
                    "Body fatigue"
                  ],
                  "description":"RA is an autoimmune and inflammatory disease causing swelling in the affected parts of the body.",
                  "c_therapies":[
                    "Stretching",
                    "Physical Therapy"
                   ]
               }
            ]
         }
      ]
   }
}