Recipe & Menu Engineering Export API Guide

Introduction

With the Recipe & Menu Engineering Export API, you can access the recipe, ingredient and supplier data in Fourth for use on POS, stock and other systems.

Quick Facts

API type HTTP REST with JSON and XML
Authentication Basic authentication
Availability All customers using our Purchase to Pay and Inventory solution
Testing A test environment is available
More information See the Export API Reference

Get access

Contact your Fourth Implementation Consultant. They will provide:

  • A Recipe & Menu Engineering Export API account to access this API
  • The root URL for requests to both test and live environments

CONTACT US

Unique identifiers 

Each item or data concept available through this API — like ingredients, intolerances, or categories — has a unique identifier (GUID). In responses, the JSON property (or XML element) with the GUID is always appended with “Guid”; for example: 

  • IngredientGuid
  • IntoleranceGuid
  • CategoryGuid

Many of the resources have an option to include the GUID as a path parameter, so that you can get the details of a specific item. 

Category types

The Fourth Purchase to Pay & Inventory system has a hierarchy of user-defined categories. In responses in this API, the hierarchy is:

  1. Category Type
  2. Main Category
  3. SubCategory
  4. SubCategory
  5. SubCategory

In the API responses that include category information, you will see nested SubCategories to represent the above.

For Main Categories, the API will include a flag to indicate whether it is a “smart” or “system” category. Smart categories align with categories in Fourth Inventory. Items can have multiple system categories, but typically have only one smart category. 

Groups

Groups (also called admin groups) are used to silo business units and data in Fourth. Groups enable you to restrict access to data — such as menus or recipes — to user groups. For example, if you run separate brands independently from one another (and require them to have separate data) then these will be groups inside a parent group.

Resources that are relevant to groups are:

  • admingroups and groups — returns the hierarchy and details of your groups
  • ingredients/{}/groups, menus/{}/groups, and recipes/{}/groups — for each ingredient, menu or recipe, this returns the groups that have access to that item. 

Resources

Fourth will provide you with the base path for requests. Each resource exposes a single GET method. Some of the resources do have query parameters for filtering requests. 

Resources Description

category/Ingredient

category/Menu

category/Recipe

Returns the category information and hierarchy for either ingredients, menus or recipes. This includes whether a Main category is a “smart” or “system” category.

Useful for: Stock and warehousing systems; finance reporting.

admingroups

groups

Returns your business’s group hierarchy.

The groups resource returns just the group names and GUIDs with implied hierarchy.

The admingroups resource returns more explicitly described hierarchy as well as details such as the UOM standard, language and currency for the group.

ingredients

ingredients/{guid}

Returns details about all ingredients or a specified ingredient (if you include a GUID). The data returned includes wastage, portions, whether it is sellable, unit sizes, and supplied pack sizes (with supplier details, category and costs).

It does not include the nutrition or intolerance data for the ingredient, nor any images.

Useful for: Stock and warehousing systems; finance reporting.

ingredients/{guid}/groups

Returns the groups that have access to an ingredient. For example, you could check that a luxury ingredient item was available only in your luxury venues.

Useful for: Stock and warehousing systems; finance systems.

ingredients/{guid}/intolerances

Gets all the intolerances listed for an ingredient. This is structured to show the intolerance groups (e.g. nuts) and then the specific intolerance (e.g. hazelnuts).

ingredients/{guid}/nutrition

Gets all the nutrient data listed for an ingredient. The nutrient amount is calculated per 100 grams.

ingredients/{guid}/pictures

Returns all images for a specified ingredient.

Images are stored as base64 strings. The properties for each image will indicate whether it is the default image or not.  

This is useful for ingredients that are hard to identify from written descriptions, including non-food items (like spoons or lightbulbs).

intolerances

Returns the intolerances of all your ingredients and recipes across your business. The returned list does not identify which ingredients or recipes include the intolerance.

menus

menus/{guid}

Returns details about all menus or a specific menu (if you include a GUID). The data returned includes courses, recipes and categories; as well as finer details around wastage, tax, revenue and profitability.

It does not include the nutrition or intolerance data for recipes in the menu, nor any images.

Useful for: Printed and on-screen menus.

menus/{guid}/groups

Returns the groups that have access to a menu. For example, you could check that your ACME menus are only available to ACME-branded restaurants.

nutrients

Returns a generic list of nutrients from Fourth. It includes just the name and description for a nutrient. The data is not linked to any ingredients or recipes.

Recipes

Recipes/{guid}

Returns details about all recipes or a specific recipe (if you include a GUID). The data returned includes PLU, ingredients, menu description, preparation time, storage and shelf-life, price details, servings, weight, portions, and categories.  

It does not include the nutrition or intolerance data, nor any images.

To get recipe steps, use the Recipes/{guid}/preparation resource.

Recipes/{guid}/groups

Returns the groups that have access to a recipe. For example, you could check that your lobster recipes are only available to restaurants serving fish.

Recipes/{guid}/intolerances

Gets all the intolerances listed for a recipe. This is structured to show the intolerance groups (e.g. nuts) and then the specific intolerance (e.g. hazelnuts).

Recipes/{guid}/nutrition

Gets the nutrient values for an recipe. Both serving size and per 100 grams values are provided for each nutrient.

Recipes/{guid}/pictures

Returns all images for a specified recipe. Images are stored as base64 strings. The properties for each image will indicate whether it is the default image or not.  

Useful for: Digital displays; kitchen screens.

Recipes/{guid}/preparation

Returns recipe preparation steps. This includes full steps, mise en place, critical control points (CCP), service/presentation and any associated images.

An example response is below.

Useful for: Kitchen screens.

suppliers

Returns the name, description and website of your suppliers listed in Fourth. 

Useful for: Stock and warehousing systems and reporting. Another use case is adding vendor details to a retail website.

units

Returns a generic list of the units of measure (UOM) from Fourth.

Filtering menu, recipe and ingredient results 

You can filter results from the ingredients, menus and recipes resources using query parameters. 
The parameters are all date filters using the format YYYY-mm-dd. You can include multiple parameters in the request to filter results further.

Query parameter Description
createdAfter

Returns only records created on or after the specified date.

Works with: menus, recipes and ingredients resources. 

lastModifiedAfter

Returns only records modified on or after the specified date.

Works with: menus, recipes and ingredients resources.

scheduledExportAfter

In the Fourth UI, you can set the Scheduled Export After field for menus, recipes and ingredients. This is an editable field that is intended for your own use and is ignored from within Fourth. For example, it allows you to set your own dates for filtering and reviewing records in an external reporting tool.

Specifying this parameter will return only records with a date on or after any set Scheduled Export After date.
The default value for this field is the “created on” date. 

Works with: menus, recipes and ingredients resources.

lastNutritionModifiedAfter

Returns only records where the nutrition data has changed on or after the specified date. 

Works with: recipes and ingredients resources.

lastNutritionModifiedBefore

Returns only records where the nutrition data has changed on or before the specified date. 

Works with: recipes and ingredients resources.

 For example, this request will return only menus created from 2016 onwards: 

<ROOT>/Menus?createdAfter=2016-01-01

You can include multiple parameters in the request to filter results further. For example, imagine you completed a major menu revision in April 2018 to your 2016 onward menus. You could look for menus that needed updating by comparing the previous results with the following: 

<ROOT>/Menus?createdAfter=2016-01-01&lastModifiedAfter=2018-04-01

This would provide a list of all the menus that were created after 2016, and had been revised after the start of April. You would just need to subtract these from your original list to find any menus that had not had updates in April. 

Request header

For all requests, you must provide your authentication details using Basic authentication in the header.

Example header:
GET /Recipes/12345/preparation  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Field Description
Authorization

Your Recipes & Menu Engineering Export ID and password, separated by a colon, and then base64 encoded. Your ID and password are case-sensitive. 

Content-Type The data format you are using for POST request. Options are: application/json, text/json, application/xml, text/xml.

Response 

Successful requests

Successful GET requests receive an HTTP 200 OK response with the data requested in the response body. 

Unsuccessful requests

Unsuccessful requests receive an HTTP 400-599 response, with an error message in the response body. 

Example response 

The following shows the response to a recipe preparation request. Note that, for the <image> elements, the content is truncated to make this example simpler to read.  

<?xml version="1.0" encoding="utf-8"?>
<RecipePreparations>
   <RecipePreparation>
      <RecipeGuid>eb8c2bed-f8ed-4c3b-89b0-2034b3400f9f</RecipeGuid>
      <Name>Toast</Name>
      <Method>
         <ContentType>text/plain</ContentType>
         <MethodList>
            <Step>
               <Text>Toast bread in a toaster until brown but not burnt.</Text>
               <Image />
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Add avocado and drizzle with oil.</Text>
               <Image />
               <Order>2</Order>
            </Step>
            <Step>
               <Text>Top with cherry tomatoes.  Lay the toast on a service plate and arrange a salad garnish to one side.</Text>
               <Image />
               <Order>3</Order>
            </Step>
            <Step>
               <Text>Drizzle the salad garnish with the dressing and serve immediately.</Text>
               <Image />
               <Order>4</Order>
            </Step>
         </MethodList>
      </Method>
      <MiseEnPlace>
         <ContentType>text/plain</ContentType>
         <MiseEnPlaceList>
            <Step>
               <Text>Slice bread and cherry tomatoes and store.</Text>
               <Image />
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Prepare salad garnishes as per recipe.</Text>
               <Image />
               <Order>2</Order>
            </Step>
         </MiseEnPlaceList>
      </MiseEnPlace>
      <Ccp>
         <ContentType>text/plain</ContentType>
         <CcpList>
            <Step>
               <Text>Wash hands first</Text>
               <Image>...</Image>
               <Order>1</Order>
            </Step>
            <Step>
               <Text>Do not freeze</Text>
               <Image>...</Image>
               <Order>2</Order>
            </Step>
            <Step>
               <Text>Salad and Fruit Chopping Board</Text>
               <Image>...</Image>
               <Order>3</Order>
            </Step>
         </CcpList>
      </Ccp>
      <Service>
         <ContentType>text/plain</ContentType>
         <Service />
         <ServiceVehicleText>10 inch white plate for toast plus small white bowl for salad garnish.</ServiceVehicleText>
      </Service>
   </RecipePreparation>
</RecipePreparations>