The Knowledge Graph API lets you create, retrieve, and update entities programmatically, so you can build integrations that manage your account's entity data without using the Yext platform UI.

Create an Entity

To create an entity, send a POST request with the entity object as the payload:

POST https://api.yextapis.com/v2/accounts/me/entities?entityType=ENTITY_TYPE&api_key=API_KEY&v=YYYYMMDD

Set entityType to the ID of the entity type, for example, location, healthcareProfessional, or a custom entity type. You can find the ID for a specific entity type under Knowledge Graph > Configuration > Entity Types, on the Settings tab for that entity type.

Every request must include values for the entity type's required fields. Required fields vary by entity type and are listed on the Fields tab for that entity type under Knowledge Graph > Configuration > Entity Types.

Example request body: Create an entity of type location.

{
  "meta": {
    "id": "yourTestLocation"
  },
  "name": "Your Test Location",
  "address": {
    "line1": "205 Main St",
    "line2": "Suite 451",
    "city": "New York",
    "region": "NY",
    "postalCode": "10001",
    "countryCode": "US"
  },
  "mainPhone": "2125555765"
}

The id field is optional. Yext generates an ID automatically if one isn't provided, or you can set your own in the meta sub-field. Entity IDs must be unique within an account; creating an entity with an existing ID returns an error. You can also provide folderId in the meta sub-field.

A successful request returns the created entity's data, including system-generated fields such as accountId, uid, and entityType.

Retrieve an Entity

Confirm an entity was created, or retrieve its current data, with a GET request that includes the entity's ID in the path:

GET https://api.yextapis.com/v2/accounts/me/entities/{id}?api_key=API_KEY&v=YYYYMMDD

Yext validates every request and returns any errors or warnings in the meta sub-field of the response. Review these on each request and adjust the request as needed.

Update an Entity

Yext updates only the fields included in the request body, so send just the fields that are changing.

PUT https://api.yextapis.com/v2/accounts/me/entities/{id}?api_key=API_KEY&v=YYYYMMDD

Example request body: Update an entity's name.

{
  "name": "My Real Location"
}

A successful request returns the updated entity's data, in the same format as the create response.

Phone number fields

For phone number fields such as mainPhone, Yext validates the number against the entity's country if no country code is provided. If the phone number doesn't match the entity's country, include a country code. For example, a US-based entity providing a non-US number needs a full country code, such as +12125555765. The API always returns phone numbers with the country code included.

Coordinate fields

Depending on the entity type, an entity may have the following latitude/longitude coordinate fields:

• displayCoordinate: Where the map pin for the entity displays.
• routableCoordinate: Destination coordinates for driving directions to the entity.
• walkableCoordinate: Destination coordinates for walking directions to the entity.
• pickupCoordinate: Coordinates for the entity's pickup area.
• dropoffCoordinate: Coordinates for the entity's drop-off area.

Each of these fields has a corresponding read-only "yext" field, for example, yextDisplayCoordinate and yextRoutableCoordinate. Yext calculates these based on sources such as the entity's address or user-provided coordinates and sends them to Listings partners where applicable.