Knock

Send the notifications you designed in Knock from a workflow: trigger a workflow by key for up to a thousand recipients at once, with the data its templates fill themselves in from. Keep the people and records Knock notifies up to date, read and write their channel and category preferences, group them by tenant, and look back over everything that was sent and what the recipients did with it.

Actions

Action	What it does
Cancel a workflow run	Stop a workflow run that is still waiting, whether in a delay step or gathering a batch.
Delete a tenant	Delete a tenant and everything associated with it.
Delete a user	Permanently delete a user and all of their data, including their messages and preferences.
Delete an object	Delete one record and everything associated with it, including the subscriptions to it.
Get a message	Read one notification: which channel carried it, whether it was delivered, and whether the recipient saw, read or clicked it.
Get a tenant	Read one tenant and its settings.
Get a user	Read one Knock user and everything stored on them.
Get an object	Read one record out of a collection.
Identify a user	Create a Knock user, or update one that already exists.
List a user's messages	Every notification sent to one person, newest first, with filters for how it was delivered and what they did with it.
List a user's preferences	Every preference set stored for one user.
List messages	Every notification this Knock environment has sent, newest first, with filters for the workflow, the channel, how it was delivered and what the recipient did with it.
List objects	List the records in one collection, a page at a time.
List tenants	List the tenants in this Knock environment, optionally filtered by name or id.
List users	List the users in this Knock environment, a page at a time.
Mark a message as read	Mark an in-app message read on the recipient's behalf, for when they acted on it somewhere other than the feed.
Set a tenant	Create or update a tenant: the customer or workspace a notification belongs to.
Set a user's preferences	Write what a user does and doesn't want to be notified about, by channel type, by category or by workflow.
Set an object	Create or update a record that isn't a person: a project, a document, a repository.
Trigger a workflow	Run one of your Knock workflows: Knock decides the channels, the template and the batching from what you built in the dashboard.

Cancel a workflow run

Stop a workflow run that is still waiting, whether in a delay step or gathering a batch. Anything already sent stays sent. Give it the same cancellation key the trigger step used.

Inputs

Workflow keyworkflow_keytextRequired: The workflow whose run you want to stop.
Cancellation keycancellation_keytextRequired: The key the 'Trigger a workflow' step was given.
Recipientsrecipientslist: Cancel for these recipients only. Leave blank to cancel for everyone the key covers.

Outputs

cancellation_keytext
cancelledtrue/false
recipient_countnumber
workflow_keytext

Example output

{
  "cancellation_key": "comment-91",
  "cancelled": true,
  "recipient_count": 0,
  "workflow_key": "new-comment"
}

Delete a tenant

Delete a tenant and everything associated with it. This cannot be undone.

Inputs

Tenant IDtenant_idtextRequired: Which tenant to delete.

Outputs

deletedtrue/false
tenant_idtext

Example output

{
  "deleted": true,
  "tenant_id": "acme"
}

Delete a user

Permanently delete a user and all of their data, including their messages and preferences. This cannot be undone.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.

Outputs

deletedtrue/false
user_idtext

Example output

{
  "deleted": true,
  "user_id": "user_1"
}

Delete an object

Delete one record and everything associated with it, including the subscriptions to it. This cannot be undone.

Inputs

CollectioncollectiontextRequired: The kind of record this is: Knock creates the collection the first time you write to it, so any name you use consistently works.
Object IDobject_idtextRequired: Your own id for this record, unique within the collection.

Outputs

collectiontext
deletedtrue/false
object_idtext

Example output

{
  "collection": "projects",
  "deleted": true,
  "object_id": "project-42"
}

Get a message

Read one notification: which channel carried it, whether it was delivered, and whether the recipient saw, read or clicked it.

Inputs

Message IDmessage_idtextRequired: The id of one notification. A 'List messages' step returns these, and the Messages page in Knock shows them.

Outputs

archived_attext
channel_idtext
channel_nametext
channel_typetext
dataobject
engagement_statuseslist
idtext
inserted_attext
link_clicked_attext
read_attext
recipient
scheduled_attext
seen_attext
statustext
tenanttext
updated_attext
workflowtext
workflow_run_idtext

Example output

{
  "archived_at": null,
  "channel_id": "8f2a1c3e-0b4d-4f7a-9c1e-2d3b4a5c6d7e",
  "channel_name": "Transactional email",
  "channel_type": "email",
  "data": {
    "plan": "pro"
  },
  "engagement_statuses": [
    "seen"
  ],
  "id": "2p3q4r5s6t7u8v9w0x",
  "inserted_at": "2026-09-18T09:00:00.000Z",
  "link_clicked_at": null,
  "read_at": null,
  "recipient": "user_1",
  "scheduled_at": null,
  "seen_at": "2026-09-18T09:04:00.000Z",
  "status": "delivered",
  "tenant": "acme",
  "updated_at": "2026-09-18T09:00:05.000Z",
  "workflow": "welcome-email",
  "workflow_run_id": "1a2b3c4d5e6f7g8h9i"
}

Get a tenant

Read one tenant and its settings.

Inputs

Tenant IDtenant_idtextRequired: Which tenant to read.
Resolve full preferencesresolve_full_preferencestrue/false: Also merge the environment's default preferences into the tenant's preference set, so you see what would actually apply.Default: false.

Outputs

idtext
nametext
propertiesobject
settingsobject

Example output

{
  "id": "acme",
  "name": "Acme Inc",
  "properties": {
    "industry": "manufacturing"
  },
  "settings": {}
}

Get a user

Read one Knock user and everything stored on them.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.

Outputs

avatartext
created_attext
emailtext
idtext
localetext
nametext
phone_numbertext
propertiesobject
timezonetext
updated_attext

Example output

{
  "avatar": "https://example.com/ada.png",
  "created_at": "2026-09-18T09:00:00.000Z",
  "email": "ada@example.com",
  "id": "user_1",
  "locale": "en-GB",
  "name": "Ada Lovelace",
  "phone_number": "+15550001111",
  "properties": {
    "plan": "pro"
  },
  "timezone": "Europe/London",
  "updated_at": "2026-09-18T09:00:00.000Z"
}

Get an object

Read one record out of a collection.

Inputs

CollectioncollectiontextRequired: The kind of record this is: Knock creates the collection the first time you write to it, so any name you use consistently works.
Object IDobject_idtextRequired: Your own id for this record, unique within the collection.

Outputs

collectiontext
created_attext
idtext
propertiesobject
updated_attext

Example output

{
  "collection": "projects",
  "created_at": "2026-09-18T09:00:00.000Z",
  "id": "project-42",
  "properties": {
    "name": "Apollo",
    "owner": "user_1"
  },
  "updated_at": "2026-09-18T09:00:00.000Z"
}

Identify a user

Create a Knock user, or update one that already exists. Only the fields you fill in are changed, so this is safe to run on every sign-in. There is no separate create step.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.
Namenametext: What templates should call them.
Emailemailtext: Where email notifications go.
Phone numberphone_numbertext: In E.164 form, for SMS: '+15550001111'.
Avatar URLavatartext: A picture of them, for in-app feeds.
Time zonetimezonetext: A tz database name such as 'America/New_York'. Knock uses it for send windows and for local times in templates.
Localelocaletext: A language tag such as 'en-GB' or 'fr'.
Custom propertiespropertiesobject: Anything else you want stored on the user and usable in templates and conditions.

Outputs

avatartext
created_attext
emailtext
idtext
localetext
nametext
phone_numbertext
propertiesobject
timezonetext
updated_attext

Example output

{
  "avatar": "https://example.com/ada.png",
  "created_at": "2026-09-18T09:00:00.000Z",
  "email": "ada@example.com",
  "id": "user_1",
  "locale": "en-GB",
  "name": "Ada Lovelace",
  "phone_number": "+15550001111",
  "properties": {
    "plan": "pro"
  },
  "timezone": "Europe/London",
  "updated_at": "2026-09-18T09:00:00.000Z"
}

List a user's messages

Every notification sent to one person, newest first, with filters for how it was delivered and what they did with it.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.
Tenanttenanttext: Only messages sent for this tenant.
Delivery statusstatustext: Only messages in these delivery states.One or more of: queued (Queued — accepted, not yet sent), sent (Sent to the channel provider), delivered (Delivered to the recipient), delivery_attempted (Delivery attempted), undelivered, not_sent (Not sent), bounced.
Engagementengagement_statustext: Only messages the recipient engaged with in these ways.One or more of: seen, unseen (Not seen), read, unread (Not read), archived, unarchived (Not archived), link_clicked (A link was clicked), interacted (Interacted with).
Workflow keysourcetext: Only messages sent by this workflow.
Workflow run IDworkflow_run_idtext: Only the messages from one run: the value a 'Trigger a workflow' step hands back.
Channel IDchannel_idtext: Only messages sent through this Knock channel.
Created afterinserted_afterdate and time: Only messages created at or after this moment.
Created beforeinserted_beforedate and time: Only messages created at or before this moment.
How many per pagepage_sizenumber: Defaults to 50 if left blank.From 1 to 100.
Next page cursoraftertext: Pass the 'after' value from a previous run of this step to get the next page. Knock pages by cursor, not by page number.
Previous page cursorbeforetext: The 'before' value from a previous run of this step.

Outputs

aftertext
beforetext
countnumber
has_moretrue/false
itemslist

Example output

{
  "after": null,
  "before": null,
  "count": 1,
  "has_more": false,
  "items": [
    {
      "archived_at": null,
      "channel_id": "8f2a1c3e-0b4d-4f7a-9c1e-2d3b4a5c6d7e",
      "channel_name": "Transactional email",
      "channel_type": "email",
      "data": {
        "plan": "pro"
      },
      "engagement_statuses": [
        "seen"
      ],
      "id": "2p3q4r5s6t7u8v9w0x",
      "inserted_at": "2026-09-18T09:00:00.000Z",
      "link_clicked_at": null,
      "read_at": null,
      "recipient": "user_1",
      "scheduled_at": null,
      "seen_at": "2026-09-18T09:04:00.000Z",
      "status": "delivered",
      "tenant": "acme",
      "updated_at": "2026-09-18T09:00:05.000Z",
      "workflow": "welcome-email",
      "workflow_run_id": "1a2b3c4d5e6f7g8h9i"
    }
  ]
}

List a user's preferences

Every preference set stored for one user. Most accounts have one, called 'default'; a user who has never set anything has none, which is not the same as having opted out.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.

Outputs

countnumber
preference_setslist
user_idtext

Example output

{
  "count": 1,
  "preference_sets": [
    {
      "categories": {
        "marketing": false
      },
      "channel_types": {
        "email": true,
        "sms": false
      },
      "channels": null,
      "commercial_subscribed": true,
      "id": "default",
      "workflows": null
    }
  ],
  "user_id": "user_1"
}

List messages

Every notification this Knock environment has sent, newest first, with filters for the workflow, the channel, how it was delivered and what the recipient did with it.

Inputs

Tenanttenanttext: Only messages sent for this tenant.
Delivery statusstatustext: Only messages in these delivery states.One or more of: queued (Queued — accepted, not yet sent), sent (Sent to the channel provider), delivered (Delivered to the recipient), delivery_attempted (Delivery attempted), undelivered, not_sent (Not sent), bounced.
Engagementengagement_statustext: Only messages the recipient engaged with in these ways.One or more of: seen, unseen (Not seen), read, unread (Not read), archived, unarchived (Not archived), link_clicked (A link was clicked), interacted (Interacted with).
Workflow keysourcetext: Only messages sent by this workflow.
Workflow run IDworkflow_run_idtext: Only the messages from one run: the value a 'Trigger a workflow' step hands back.
Channel IDchannel_idtext: Only messages sent through this Knock channel.
Created afterinserted_afterdate and time: Only messages created at or after this moment.
Created beforeinserted_beforedate and time: Only messages created at or before this moment.
How many per pagepage_sizenumber: Defaults to 50 if left blank.From 1 to 100.
Next page cursoraftertext: Pass the 'after' value from a previous run of this step to get the next page. Knock pages by cursor, not by page number.
Previous page cursorbeforetext: The 'before' value from a previous run of this step.

Outputs

aftertext
beforetext
countnumber
has_moretrue/false
itemslist

Example output

{
  "after": null,
  "before": null,
  "count": 1,
  "has_more": false,
  "items": [
    {
      "archived_at": null,
      "channel_id": "8f2a1c3e-0b4d-4f7a-9c1e-2d3b4a5c6d7e",
      "channel_name": "Transactional email",
      "channel_type": "email",
      "data": {
        "plan": "pro"
      },
      "engagement_statuses": [
        "seen"
      ],
      "id": "2p3q4r5s6t7u8v9w0x",
      "inserted_at": "2026-09-18T09:00:00.000Z",
      "link_clicked_at": null,
      "read_at": null,
      "recipient": "user_1",
      "scheduled_at": null,
      "seen_at": "2026-09-18T09:04:00.000Z",
      "status": "delivered",
      "tenant": "acme",
      "updated_at": "2026-09-18T09:00:05.000Z",
      "workflow": "welcome-email",
      "workflow_run_id": "1a2b3c4d5e6f7g8h9i"
    }
  ]
}

List objects

List the records in one collection, a page at a time. Pass the 'after' cursor from one run into the next.

Inputs

CollectioncollectiontextRequired: The kind of record this is: Knock creates the collection the first time you write to it, so any name you use consistently works.
Include preferencesinclude_preferencestrue/false: Also return each record's notification preferences.Default: false.
How many per pagepage_sizenumber: Defaults to 50 if left blank.From 1 to 100.
Next page cursoraftertext: Pass the 'after' value from a previous run of this step to get the next page. Knock pages by cursor, not by page number.
Previous page cursorbeforetext: The 'before' value from a previous run of this step.

Outputs

aftertext
beforetext
countnumber
has_moretrue/false
itemslist

Example output

{
  "after": null,
  "before": null,
  "count": 1,
  "has_more": false,
  "items": [
    {
      "collection": "projects",
      "created_at": "2026-09-18T09:00:00.000Z",
      "id": "project-42",
      "properties": {
        "name": "Apollo",
        "owner": "user_1"
      },
      "updated_at": "2026-09-18T09:00:00.000Z"
    }
  ]
}

List tenants

List the tenants in this Knock environment, optionally filtered by name or id.

Inputs

Name containsnametext: Only tenants whose name matches.
Tenant IDtenant_idtext: Only the tenant with this id.
How many per pagepage_sizenumber: Defaults to 50 if left blank.From 1 to 100.
Next page cursoraftertext: Pass the 'after' value from a previous run of this step to get the next page. Knock pages by cursor, not by page number.
Previous page cursorbeforetext: The 'before' value from a previous run of this step.

Outputs

aftertext
beforetext
countnumber
has_moretrue/false
itemslist

Example output

{
  "after": null,
  "before": null,
  "count": 1,
  "has_more": false,
  "items": [
    {
      "id": "acme",
      "name": "Acme Inc",
      "properties": {
        "industry": "manufacturing"
      },
      "settings": {}
    }
  ]
}

List users

List the users in this Knock environment, a page at a time. Pass the 'after' cursor from one run into the next to keep going.

Inputs

Include preferencesinclude_preferencestrue/false: Also return each record's notification preferences.Default: false.
How many per pagepage_sizenumber: Defaults to 50 if left blank.From 1 to 100.
Next page cursoraftertext: Pass the 'after' value from a previous run of this step to get the next page. Knock pages by cursor, not by page number.
Previous page cursorbeforetext: The 'before' value from a previous run of this step.

Outputs

aftertext
beforetext
countnumber
has_moretrue/false
itemslist

Example output

{
  "after": null,
  "before": null,
  "count": 1,
  "has_more": false,
  "items": [
    {
      "avatar": "https://example.com/ada.png",
      "created_at": "2026-09-18T09:00:00.000Z",
      "email": "ada@example.com",
      "id": "user_1",
      "locale": "en-GB",
      "name": "Ada Lovelace",
      "phone_number": "+15550001111",
      "properties": {
        "plan": "pro"
      },
      "timezone": "Europe/London",
      "updated_at": "2026-09-18T09:00:00.000Z"
    }
  ]
}

Mark a message as read

Mark an in-app message read on the recipient's behalf, for when they acted on it somewhere other than the feed.

Inputs

Message IDmessage_idtextRequired: The id of one notification. A 'List messages' step returns these, and the Messages page in Knock shows them.

Outputs

archived_attext
channel_idtext
channel_nametext
channel_typetext
dataobject
engagement_statuseslist
idtext
inserted_attext
link_clicked_attext
read_attext
recipient
scheduled_attext
seen_attext
statustext
tenanttext
updated_attext
workflowtext
workflow_run_idtext

Example output

{
  "archived_at": null,
  "channel_id": "8f2a1c3e-0b4d-4f7a-9c1e-2d3b4a5c6d7e",
  "channel_name": "Transactional email",
  "channel_type": "email",
  "data": {
    "plan": "pro"
  },
  "engagement_statuses": [
    "seen"
  ],
  "id": "2p3q4r5s6t7u8v9w0x",
  "inserted_at": "2026-09-18T09:00:00.000Z",
  "link_clicked_at": null,
  "read_at": "2026-09-18T09:05:00.000Z",
  "recipient": "user_1",
  "scheduled_at": null,
  "seen_at": "2026-09-18T09:04:00.000Z",
  "status": "delivered",
  "tenant": "acme",
  "updated_at": "2026-09-18T09:00:05.000Z",
  "workflow": "welcome-email",
  "workflow_run_id": "1a2b3c4d5e6f7g8h9i"
}

Set a tenant

Create or update a tenant: the customer or workspace a notification belongs to. The record, its name and its custom properties work on every Knock plan; the branding fields and tenant-level preference defaults are an Enterprise feature and Knock refuses them otherwise.

Inputs

Tenant IDtenant_idtextRequired: Your own id for the customer or workspace. Writing to an id that doesn't exist yet creates it.
Namenametext: What to call the tenant in templates.
Branding (Enterprise)brandingobject: icon_url, logo_url, primary_color and primary_color_contrast. Only applied on Knock's Enterprise plan: leave it blank otherwise.
Custom propertiespropertiesobject: Anything else to store on the tenant.

Outputs

idtext
nametext
propertiesobject
settingsobject

Example output

{
  "id": "acme",
  "name": "Acme Inc",
  "properties": {
    "industry": "manufacturing"
  },
  "settings": {}
}

Set a user's preferences

Write what a user does and doesn't want to be notified about, by channel type, by category or by workflow. Knock's own default replaces everything not sent, so this step defaults to merging instead: switch it to Replace only when you mean to discard the rest.

Inputs

User IDuser_idtextRequired: Your own id for the person, exactly as you send it to Knock. Knock stores whatever you use, so this is usually your database id.
How to apply thispersistence_strategytext: Merge keeps preferences this step doesn't mention. Replace discards them.One of: merge (Merge — keep preferences this step doesn't mention), replace (Replace — discard every preference this step doesn't send). Default: merge.
Channel typeschannel_typesobject: True or false per channel type: email, in_app_feed, sms, push, chat, http.
Categoriescategoriesobject: True or false per workflow category, keyed by the category key from Knock.
Workflowsworkflowsobject: True or false per workflow key.
Channelschannelsobject: True or false per Knock channel id.
Subscribed to commercial messagescommercial_subscribedtrue/false: Whether they accept marketing notifications.
Preference setpreference_set_idtext: Leave blank for 'default', which is the set Knock consults unless a workflow names another.Default: default.

Outputs

categoriesobject
channel_typesobject
channelsobject
commercial_subscribedtrue/false
idtext
workflowsobject

Example output

{
  "categories": {
    "marketing": false
  },
  "channel_types": {
    "email": true,
    "sms": false
  },
  "channels": null,
  "commercial_subscribed": true,
  "id": "default",
  "workflows": null
}

Set an object

Create or update a record that isn't a person: a project, a document, a repository. Objects can be subscribed to and notified just like users. Only the fields you fill in change.

Inputs

CollectioncollectiontextRequired: The kind of record this is: Knock creates the collection the first time you write to it, so any name you use consistently works.
Object IDobject_idtextRequired: Your own id for this record, unique within the collection.
Namenametext: What templates should call this record.
Time zonetimezonetext: A tz database name, for send windows.
Localelocaletext: A language tag such as 'en-GB'.
Custom propertiespropertiesobject: Anything else to store on the record. These come back nested under 'properties' when you read it.

Outputs

collectiontext
created_attext
idtext
propertiesobject
updated_attext

Example output

{
  "collection": "projects",
  "created_at": "2026-09-18T09:00:00.000Z",
  "id": "project-42",
  "properties": {
    "name": "Apollo",
    "owner": "user_1"
  },
  "updated_at": "2026-09-18T09:00:00.000Z"
}

Trigger a workflow

Run one of your Knock workflows: Knock decides the channels, the template and the batching from what you built in the dashboard. The workflow must be committed to the environment this connection's key belongs to before the API can trigger it, in development as well as production.

Inputs

Workflow keyworkflow_keytextRequired: The key shown under the workflow's name in Knock. Not the display name: 'new-comment', not 'New comment'.
RecipientsrecipientslistRequired: Who to notify: user ids, or whole user objects to identify and notify in one step. Up to 1,000.
Datadataobject: What the template fills itself in with: every variable your workflow references.
Actoractortext: Who caused this, if anybody. A user id, or a whole user object to identify at the same time.
Tenanttenanttext: The customer or workspace this notification belongs to. Used for per-tenant branding and preferences.
Cancellation keycancellation_keytext: Your own id for this run, so a later 'Cancel a workflow run' step can stop it while it is still waiting in a delay or batch.
Idempotency keyidempotency_keytext: Send the same key twice and Knock only runs the workflow once. Use it when a retry must not notify anybody twice.
Sandbox modesandbox_modetrue/false: Run the workflow without actually delivering anything. Messages are still recorded.Default: false.
Skip delaysskip_delaytrue/false: Run the workflow's delay steps through immediately.Default: false.

Outputs

cancellation_keytext
recipient_countnumber
workflow_keytext
workflow_run_idtext

Example output

{
  "cancellation_key": null,
  "recipient_count": 1,
  "workflow_key": "new-comment",
  "workflow_run_id": "1a2b3c4d5e6f7g8h9i"
}

ActionsCopy Anchor Link

Cancel a workflow runCopy Anchor Link

Inputs

Outputs

Delete a tenantCopy Anchor Link

Inputs

Outputs

Delete a userCopy Anchor Link

Inputs

Outputs

Delete an objectCopy Anchor Link

Inputs

Outputs

Get a messageCopy Anchor Link

Inputs

Outputs

Get a tenantCopy Anchor Link

Inputs

Outputs

Get a userCopy Anchor Link

Inputs

Outputs

Get an objectCopy Anchor Link

Inputs

Outputs

Identify a userCopy Anchor Link

Inputs

Outputs

List a user's messagesCopy Anchor Link

Inputs

Outputs

List a user's preferencesCopy Anchor Link

Inputs

Outputs

List messagesCopy Anchor Link

Inputs

Outputs

List objectsCopy Anchor Link

Inputs

Outputs

List tenantsCopy Anchor Link

Inputs

Outputs

List usersCopy Anchor Link

Inputs

Outputs

Mark a message as readCopy Anchor Link

Inputs

Outputs

Set a tenantCopy Anchor Link

Inputs

Outputs

Set a user's preferencesCopy Anchor Link

Inputs

Outputs

Set an objectCopy Anchor Link

Inputs

Outputs

Trigger a workflowCopy Anchor Link

Inputs

Outputs

On this page

Actions

Cancel a workflow run

Delete a tenant

Delete a user

Delete an object

Get a message

Get a tenant

Get a user

Get an object

Identify a user

List a user's messages

List a user's preferences

List messages

List objects

List tenants

List users

Mark a message as read

Set a tenant

Set a user's preferences

Set an object

Trigger a workflow