redocly logoAPI docs by Redocly

Data Prep Recipe API (68.0)

Download OpenAPI specification:Download

Use the Data Prep Recipe API to programmatically access and manage Data Prep recipes and recipe configurations. Get recipe files, manage notifications, and configure recipe settings.

For detailed usage examples, see Manage, Schedule, and Run Recipes with REST APIs.

Recipes List Resources

Returns a collection of Data Prep recipes.

Available in: v38.0

Note: Recipes require the recipe editor UI for creation and aren’t supported using POST via this API endpoint.

Available in Postman

To view and test a working example of this resource, see getRecipeCollection in Postman. For information about how to authenticate your org with Postman, see the CRM Analytics Rest API Quickstart.

Available Components

getRecipeCollection

Returns a collection of Data Prep recipes.

Available in: v38.0

Note: Create recipes in the recipe editor UI. POST requests to this endpoint aren’t supported.

The following GET request uses the q parameter to search for recipes:

GET /wave/recipes?q=MyRecipe
query Parameters
folderId
string <Id>

Returns a collection filtered by recipes belonging to the specified folder ID.

Available in: v61.0

format
string (ConnectRecipeFormatTypeEnum)
Enum: "R2" "R3"

Returns a collection filtered by the format of the current recipe definition. Valid values are:

  • R2 (Data Prep Classic)
  • R3 (Data Prep)

Available in: v48.0

lastModifiedAfter
string

Returns a collection filtered by recipes with a last modified date after the given value.

Available in: v55.0

lastModifiedBefore
string

Returns a collection filtered by recipes with a last modified date before the given value.

Available in: v55.0

licenseType
string (ConnectAnalyticsLicenseTypeEnum)
Enum: "Cdp" "DataPipelineQuery" "EinsteinAnalytics" "IntelligentApps" "MulesoftDataPath" "Sonic"

Filters the collection by the Analytics license type. Valid values are

  • Cdp (Data 360)
  • DataPipelineQuery (Data Pipeline Query)
  • EinsteinAnalytics (CRM Analytics)
  • IntelligentApps (Intelligent Apps)
  • MulesoftDataPath (Mulesoft Data Works)
  • Sonic (Salesforce Data Pipeline)

Available in: v52.0

nextScheduledAfter
string

Returns a collection filtered by recipes with a scheduled run after the given value.

Available in: v55.0

nextScheduledBefore
string

Returns a collection filtered by recipes with a scheduled run before the given value.

Available in: v55.0

page
string

A generated token that indicates the view of the objects to be returned.

Available in: v38.0

pageSize
integer <int32>

Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.

Available in: v38.0

q
string

Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string. If the user’s search query contains quotation marks or wildcards, those symbols are automatically removed from the query string in the URI along with any other special characters.

Available in: v38.0

sort
string (ConnectWaveSortOrderTypeEnum)
Enum: "App" "CreatedBy" "CreatedById" "CreatedDate" "FolderName" "LastArchivedBy" "LastArchivedDate" "LastModified" "LastModifiedBy" "LastModifiedById" "LastModifiedDate" "Location" "Mru" "Name" "Outcome" "Owner" "RefreshDate" "RunDate" "Status" "Title" "Type"

The type of sort order to be applied to the returned collection. Valid values are:

  • App
  • CreatedBy
  • CreatedById
  • CreatedDate
  • FolderName
  • LastModified
  • LastModifiedBy
  • LastModifiedById
  • LastModifiedDate
  • Location
  • Mru (Most Recently Used, last viewed date)
  • Name
  • Outcome
  • RefreshDate (for assets like datasets)
  • RunDate (for assets like reports)
  • Status
  • Title
  • Type

Available in: v38.0

status
Array of strings (ConnectRecipeStatusEnum)
Items Enum: "Cancelled" "Failure" "New" "Queued" "Running" "Success" "Warning"

Returns a collection filtered by the statuses of the recipe. Valid values are:

  • Cancelled
  • Failure
  • New (Never run or has no recent run)
  • Queued
  • Running
  • Success
  • Warning

Available in: v55.0

Responses

Response samples

Content type
application/json
{
  • "nextPageUrl": "string",
  • "recipes": [
    ],
  • "totalSize": 0,
  • "url": "string"
}

Recipe Resources

Returns, updates, or deletes a Data Prep recipe.

With API version 49.0 and higher, the format request parameter is required for recipes created in the Data Prep format. For recipes created in the Data Prep Classic format, the format request parameter isn’t needed. If you want to up-convert the Data Prep Classic recipe format to the Data Prep recipe format, use the format request parameter set to R3.

Available in: v38.0

Available in Postman

To view and test a working example of this resource, see getRecipe in Postman. For information about how to authenticate your org with Postman, see the CRM Analytics Rest API Quickstart.

Available Components

Run a Recipe

To run a Data Prep recipe, use the Dataflow Jobs Resource API. For examples of how to start and stop recipes, see Start and Stop a Dataflow Job or Recipe.

Schedule a Recipe

To schedule a recipe, use the Schedule Resource API. For examples of how to schedule recipes, see Schedule Dataflows, Recipes, and Data Syncs.

getRecipe

Returns a Data Prep recipe.

Available in: v38.0

Note: In API version 49.0 and later, format is required for recipes created in the Data Prep format. It isn’t required for recipes created in the Data Prep Classic format. To retrieve a Classic recipe in the Data Prep format, set format to R3.

The following GET request returns a recipe in the Data Prep format:

GET /wave/recipes/{id}?format=R3

To run a recipe, use Start a Dataflow Job. To schedule a recipe, use Create a Schedule. For examples, see Run, Schedule, and Sync CRM Analytics Data.

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

query Parameters
format
string (ConnectRecipeFormatTypeEnum)
Enum: "R2" "R3"

Specifies the format of the returned recipe. Valid values are:

  • R2 (Data Prep Classic)
  • R3 (Data Prep)

Required for Data Prep recipes, Optional for Data Prep Classic recipes.

Available in: v49.0

historyId
string <Id>

Use the history ID to request a specific recipe version.

Available in: v51.0

Responses

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "conversionDetails": [
    ],
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "dataflowLastUpdate": "2019-08-24",
  • "dataset": {
    },
  • "description": "string",
  • "fileUrl": "string",
  • "format": "R2",
  • "historiesUrl": "string",
  • "id": "string",
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "licenseAttributes": {
    },
  • "licenseType": "Cdp",
  • "name": "string",
  • "namespace": "string",
  • "nextScheduledDate": "2019-08-24",
  • "permissions": {
    },
  • "publishingTarget": "DataPool",
  • "recipeDefinition": {
    },
  • "rowLevelSecurityPredicate": "string",
  • "schedule": "string",
  • "scheduleAttributes": {
    },
  • "scheduleType": "EventDriven",
  • "sourceDataflow": "string",
  • "sourceRecipe": "string",
  • "status": "Cancelled",
  • "targetDataflowId": "string",
  • "type": "recipe",
  • "url": "string",
  • "validationDetails": [
    ]
}

putRecipe

Reverts a Data Prep recipe to a previous historical version. Specify that version’s historyId in the request body.

Available in: v38.0

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

Request Body schema: application/json

Use the PUT API request to revert to a previous historical version.

historyId
required
string

The required source history id for this asset to revert to.

Available in: v42.0

historyLabel
string

The history label to tag the revert change with.

Available in: v42.0

Responses

Request samples

Content type
application/json

Reverts the recipe to the historical version identified by historyId. The optional historyLabel labels the reverted version.

{
  • "historyId": "0RmRM000000xxxxxxx",
  • "historyLabel": "Rollback to known-good version"
}

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "conversionDetails": [
    ],
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "dataflowLastUpdate": "2019-08-24",
  • "dataset": {
    },
  • "description": "string",
  • "fileUrl": "string",
  • "format": "R2",
  • "historiesUrl": "string",
  • "id": "string",
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "licenseAttributes": {
    },
  • "licenseType": "Cdp",
  • "name": "string",
  • "namespace": "string",
  • "nextScheduledDate": "2019-08-24",
  • "permissions": {
    },
  • "publishingTarget": "DataPool",
  • "recipeDefinition": {
    },
  • "rowLevelSecurityPredicate": "string",
  • "schedule": "string",
  • "scheduleAttributes": {
    },
  • "scheduleType": "EventDriven",
  • "sourceDataflow": "string",
  • "sourceRecipe": "string",
  • "status": "Cancelled",
  • "targetDataflowId": "string",
  • "type": "recipe",
  • "url": "string",
  • "validationDetails": [
    ]
}

patchRecipe

Updates a Data Prep recipe.

Available in: v38.0

To change the recipe’s license type, set recipeObject.licenseAttributes.type in the request body.

Note: If a Data Prep Classic recipe is retrieved in the Data Prep format, a PATCH request using that representation permanently converts the recipe to the Data Prep format.

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

query Parameters
enableEditorValidation
boolean

Indicates whether editor validation for the recipe is enabled (true) or not (false).

Available in: v53.0

validationContext
string
Enum: "Default" "Editor"

The recipe validation context.

Available in: v53.0

Request Body schema: multipart/form-data
recipeFile
string <binary>

The recipe file.

Available in: v38.0

object (RecipeInput)

A data prep recipe.

enableEditorValidation
boolean

Indicates whether editor validation for the recipe is enabled ( true ) or not ( false ).

Available in: v53.0

validationContext
string

The recipe validation context. Valid values are:

  • Default
  • Editor

Available in: v53.0

Responses

Request samples

Content type
multipart/form-data

The following JSON shows how to update a recipe, specifically the license type for the recipe.

{
  "recipeObject": {
    "licenseAttributes": {
      "type": "Sonic"
    }
  }
}

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "conversionDetails": [
    ],
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "dataflowLastUpdate": "2019-08-24",
  • "dataset": {
    },
  • "description": "string",
  • "fileUrl": "string",
  • "format": "R2",
  • "historiesUrl": "string",
  • "id": "string",
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "licenseAttributes": {
    },
  • "licenseType": "Cdp",
  • "name": "string",
  • "namespace": "string",
  • "nextScheduledDate": "2019-08-24",
  • "permissions": {
    },
  • "publishingTarget": "DataPool",
  • "recipeDefinition": {
    },
  • "rowLevelSecurityPredicate": "string",
  • "schedule": "string",
  • "scheduleAttributes": {
    },
  • "scheduleType": "EventDriven",
  • "sourceDataflow": "string",
  • "sourceRecipe": "string",
  • "status": "Cancelled",
  • "targetDataflowId": "string",
  • "type": "recipe",
  • "url": "string",
  • "validationDetails": [
    ]
}

deleteRecipe

Deletes a Data Prep recipe.

Available in: v38.0

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

Responses

Recipe File Resources

Returns a Data Prep recipe's file content as JSON.

Available in: v38.0

getRecipeFile

Returns a Data Prep recipe’s JSON file contents as a binary stream.

Available in: v38.0

This endpoint is internal to the recipe UI and is available only for debugging and reference. Modifying this content isn’t supported. The JSON representation differs between recipe 2.0 and recipe 3.0.

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

Responses

Recipe Notification Resources

Returns a Data Prep recipe job notification, creates, or updates a Data Prep recipe job notification.

Available in: v49.0

Available in Postman

To view and test a working example of this resource, see getRecipeNotification in Postman. For information about how to authenticate your org with Postman, CRM Analytics Rest API Quickstart.

Available Components

getRecipeNotification

Returns a Data Prep recipe job notification.

Available in: v49.0

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

Responses

Response samples

Content type
application/json
{
  • "longRunningAlertInMins": 0,
  • "notificationLevel": "Always",
  • "recipe": {
    }
}

putRecipeNotification

Creates or updates a Data Prep recipe job notification.

Available in: v49.0

path Parameters
id
required
string <Id> ^(05v)\w*

The ID of the recipe.

Request Body schema: application/json

Recipe Notification Input

longRunningAlertInMins
integer

The number of minutes that a recipe can run before sending an alert.

Available in: v49.0

notificationLevel
required
string (ConnectEmailNotificationLevelEnum)
Enum: "Always" "Failures" "Never" "Warnings"

Valid types of email notification levels.

Available in: v49.0

Filter group: Small

Responses

Request samples

Content type
application/json

The following JSON shows how to update an existing recipe notification.

{
  • "longRunningAlertInMins": 60,
  • "notificationLevel": "Warnings"
}

Response samples

Content type
application/json
{
  • "longRunningAlertInMins": 0,
  • "notificationLevel": "Always",
  • "recipe": {
    }
}

Recipe Configurations List Resources

Returns or updates a collection of Data Prep recipe configurations and creates a recipe configuration.

Available in: v54.0

getRecipeConfigurationCollection

Returns a collection of Data Prep recipe configurations.

Available in: v54.0

Responses

Response samples

Content type
application/json
{
  • "configurations": [
    ],
  • "histories": [
    ],
  • "nextPageUrl": "string",
  • "totalSize": 0,
  • "url": "string"
}

postRecipeConfigurationCollection

Creates a Data Prep recipe configuration.

Available in: v54.0

Request Body schema: application/json

Recipe Configuration Input

configurationType
string (RecipeConfigurationTypeEnum)

The recipe configuration fiscal type. Valid values are:

  • Fiscal (Recipe Configuration Fiscal Input)

Available in: v54.0

description
string

Short description of the asset

Required for POST; Optional in PATCH

Available in: v36.0

firstDayOfWeek
integer

First day of week (calendar and fiscal).

fiscalType
required
string
Value: "Offset"
id
string

ID.

isDefault
boolean

If true, this is the default fiscal configuration.

label
string

The asset label.

in POST and PATCH

Available in: v37.0

monthOffset
integer

Month offset.

name
string

The asset developer name.

Required for POST; Not allowed to edit in PATCH

Available in: v36.0

yearBasedOn
string (RecipeConfigurationFiscalOffsetYearBasedOnEnum)
Enum: "End" "Start"

Different fiscal offset year based on configurations

Responses

Request samples

Content type
application/json
{
  • "configurationType": "Fiscal",
  • "description": "string",
  • "firstDayOfWeek": 0,
  • "fiscalType": "Offset",
  • "id": "string",
  • "isDefault": true,
  • "label": "string",
  • "monthOffset": 0,
  • "name": "string",
  • "yearBasedOn": "End"
}

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "configurationType": "Fiscal",
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "description": "string",
  • "firstDayOfWeek": 0,
  • "fiscalType": "Offset",
  • "id": "string",
  • "isDefault": true,
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "monthOffset": "string",
  • "name": "string",
  • "namespace": "string",
  • "permissions": {
    },
  • "type": "RecipeFiscalOffsetConfiguration",
  • "url": "string",
  • "yearBasedOn": "End"
}

patchRecipeConfigurationCollection

Updates a collection of Data Prep recipe configurations.

Available in: v54.0

Request Body schema: application/json

Recipe Configuration Collection Input

Array of objects (RecipeConfigurationInput)

List of recipe configurations.

required
Array of objects (RecipeConfigurationInput)

The list of recipe configurations to update.

Available in: v54.0

Responses

Request samples

Content type
application/json
{
  • "configurations": [
    ],
  • "recipeConfigurations": [
    ]
}

Response samples

Content type
application/json
{
  • "configurations": [
    ],
  • "histories": [
    ],
  • "nextPageUrl": "string",
  • "totalSize": 0,
  • "url": "string"
}

Recipe Configuration Resources

Returns, updates, or deletes a Data Prep recipe configuration.

Available in: v54.0

getRecipeConfiguration

Returns a Data Prep recipe configuration.

Available in: v54.0

path Parameters
id
required
string <Id> ^(7y8)\w*

The ID of the recipe.

Responses

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "configurationType": "Fiscal",
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "description": "string",
  • "firstDayOfWeek": 0,
  • "fiscalType": "Offset",
  • "id": "string",
  • "isDefault": true,
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "monthOffset": "string",
  • "name": "string",
  • "namespace": "string",
  • "permissions": {
    },
  • "type": "RecipeFiscalOffsetConfiguration",
  • "url": "string",
  • "yearBasedOn": "End"
}

patchRecipeConfiguration

Updates the specified Data Prep recipe configuration.

Available in: v54.0

path Parameters
id
required
string <Id> ^(7y8)\w*

The ID of the recipe.

Request Body schema: application/json

Recipe Configuration Input

configurationType
string (RecipeConfigurationTypeEnum)

The recipe configuration fiscal type. Valid values are:

  • Fiscal (Recipe Configuration Fiscal Input)

Available in: v54.0

description
string

Short description of the asset

Required for POST; Optional in PATCH

Available in: v36.0

firstDayOfWeek
integer

First day of week (calendar and fiscal).

fiscalType
required
string
Value: "Offset"
id
string

ID.

isDefault
boolean

If true, this is the default fiscal configuration.

label
string

The asset label.

in POST and PATCH

Available in: v37.0

monthOffset
integer

Month offset.

name
string

The asset developer name.

Required for POST; Not allowed to edit in PATCH

Available in: v36.0

yearBasedOn
string (RecipeConfigurationFiscalOffsetYearBasedOnEnum)
Enum: "End" "Start"

Different fiscal offset year based on configurations

Responses

Request samples

Content type
application/json
{
  • "configurationType": "Fiscal",
  • "description": "string",
  • "firstDayOfWeek": 0,
  • "fiscalType": "Offset",
  • "id": "string",
  • "isDefault": true,
  • "label": "string",
  • "monthOffset": 0,
  • "name": "string",
  • "yearBasedOn": "End"
}

Response samples

Content type
application/json
{
  • "assetSharingUrl": "string",
  • "configurationType": "Fiscal",
  • "createdBy": {
    },
  • "createdDate": "2019-08-24",
  • "description": "string",
  • "firstDayOfWeek": 0,
  • "fiscalType": "Offset",
  • "id": "string",
  • "isDefault": true,
  • "label": "string",
  • "lastAccessedDate": "2019-08-24",
  • "lastModifiedBy": {
    },
  • "lastModifiedDate": "2019-08-24",
  • "monthOffset": "string",
  • "name": "string",
  • "namespace": "string",
  • "permissions": {
    },
  • "type": "RecipeFiscalOffsetConfiguration",
  • "url": "string",
  • "yearBasedOn": "End"
}

deleteRecipeConfiguration

Deletes the specified Data Prep recipe configuration.

Available in: v54.0

path Parameters
id
required
string <Id> ^(7y8)\w*

The ID of the recipe.

Responses

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!