Goals mAPI reference
Complete reference documentation for the Goals resource.
Goals
#Goals are measurable outcomes you define in Knock and attach to workflows, broadcasts, and guides for completion and attribution tracking.
You can retrieve, update, create, validate, clone, and archive goals, as well as list all goals in a given environment. Goals are identified by their unique goal key. Goal upserts publish immediately and do not accept a commit parameter. Clone a goal to copy it into another environment; goals are not promotable.
List goals
#Returns a paginated list of goals for the given environment.
Endpoint
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
Whether to annotate the resource. Only used in the Knock CLI.
Returns
A paginated list of Goal. Contains a list of entries and page information.
A list of entries.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
Archive a goal
#Archives a given goal in this environment. Refuses if a workflow, guide, or broadcast in this environment is attached to the goal.
Endpoint
Path parameters
The key of the goal to archive.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
The response from archiving a goal.
The result of the archive operation.
Get a goal
#Retrieve a goal by its key in a given environment.
Endpoint
Path parameters
The key of the goal to retrieve.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Whether to annotate the resource. Only used in the Knock CLI.
Returns
A goal defines an event condition that is tracked and attributed to messaging resources.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).
Upsert a goal
#Updates a goal of a given key, or creates a new one if it does not yet exist. The goal is published immediately; this endpoint does not accept a commit parameter.
Endpoint
Path parameters
The key of the goal to upsert.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Whether to annotate the resource. Only used in the Knock CLI.
Request body
A goal payload for upsert or validate.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
An optional description for the goal. Maximum of 280 characters allowed.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
Returns
Wraps the Goal response under the goal key.
A goal defines an event condition that is tracked and attributed to messaging resources.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).
Validate a goal
#Validates a goal payload without persisting it.
Endpoint
Path parameters
The key of the goal to validate.
Query parameters
The environment slug. When omitted, the account's default environment is used.
The slug of a branch to use. When environment is omitted, the branch is resolved from Development after the account default is injected. When environment is supplied, it must be "development".
Request body
A goal payload for upsert or validate.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
An optional description for the goal. Maximum of 280 characters allowed.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
Returns
Wraps the Goal response under the goal key.
A goal defines an event condition that is tracked and attributed to messaging resources.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).
Clone a goal
#Clones a goal into a destination environment.
Endpoint
Path parameters
The key of the source goal to clone.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Request body
The destination key, name, and environment for the cloned goal.
The destination environment slug.
The key for the cloned goal.
The name for the cloned goal.
Returns
Wraps the Goal response under the goal key.
A goal defines an event condition that is tracked and attributed to messaging resources.
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).
Detach a goal
#Detaches the goal from a workflow, guide, or broadcast in the given environment. The change goes live without a commit: the resource is published in the background, so the response doesn't wait on it. Returns 404 when the goal isn't attached to the resource.
Endpoint
Path parameters
The key of the goal.
The type of resource: workflow, guide, or broadcast.
The key of the workflow, guide, or broadcast.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
The response from detaching a goal.
The result of the detach operation.
Attach a goal
#Attaches the goal to a workflow, guide, or broadcast in the given environment, or updates its attribution window. The attachment goes live without a commit: the resource is published in the background, so the response doesn't wait on it. Workflows and guides must have been committed in the environment, and broadcasts must not have been sent. A resource holds one goal, so this replaces any other goal attached to it.
Endpoint
Path parameters
The key of the goal.
The type of resource: workflow, guide, or broadcast.
The key of the workflow, guide, or broadcast.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Request body
Settings for the goal attachment.
The number of days after a message is sent in which a goal completion is attributed to it. Must be between 1 and 30. When omitted, re-saving the attached goal keeps its window; otherwise 7.
Returns
Wraps the GoalResourceAttachment response under the attachment key.
A goal attached to a workflow, guide, or broadcast in one environment. An attachment goes live without a commit.
The number of days after a message is sent in which a goal completion is attributed to it.
The key of the attached goal.
The key of the workflow, guide, or broadcast.
The type of resource the goal is attached to.
List a goal's attachments
#Returns the workflows, guides, and broadcasts the goal is attached to in the given environment.
Endpoint
Path parameters
The key of the goal.
Query parameters
The environment slug. When omitted, the account's default environment is used.
Returns
The goal's attachments in the environment.
The goal's attachments in the environment.
The number of days after a message is sent in which a goal completion is attributed to it.
The key of the attached goal.
The key of the workflow, guide, or broadcast.
The type of resource the goal is attached to.
GoalResourceAttachment
#A goal attached to a workflow, guide, or broadcast in one environment. An attachment goes live without a commit.
Attributes
The number of days after a message is sent in which a goal completion is attributed to it.
The key of the attached goal.
The key of the workflow, guide, or broadcast.
The type of resource the goal is attached to.
GoalCondition
#A goal condition consisting of a polymorphic event and optional match conditions.
Attributes
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
GoalRequest
#A goal payload for upsert or validate.
Attributes
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
An optional description for the goal. Maximum of 280 characters allowed.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
Goal
#A goal defines an event condition that is tracked and attributed to messaging resources.
Attributes
A goal condition consisting of a polymorphic event and optional match conditions.
The event to track. Supports integration_source and audience event types.
Optional list of condition groups; each group uses an operator (and/or) with nested conditions.
The timestamp of when the goal was created. (read-only).
An optional description for the goal. Maximum of 280 characters allowed.
The slug of the environment in which the goal exists. (read-only).
The unique key string for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
A name for the goal. Must be at minimum 1 character and at maximum 255 characters in length.
The SHA hash of the goal data. (read-only).
The timestamp of when the goal was last updated. (read-only).