Knock Users API
A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/knock-users-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Knock Users API
version: '1.0'
description: A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
tags:
- description: A user is an individual from your system, represented in Knock. They are most commonly a recipient of a notification.
name: Users
paths:
/v1/users/{user_id}:
delete:
callbacks: {}
description: Permanently delete a user and all associated data.
operationId: deleteUser
parameters:
- description: The ID of the user to delete.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'204':
description: No Content
summary: Delete user
tags:
- Users
x-ratelimit-tier: 2
get:
callbacks: {}
description: Retrieve a specific user by their ID.
operationId: getUser
parameters:
- description: The ID of the user to retrieve.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: OK
summary: Get user
tags:
- Users
x-ratelimit-tier: 4
put:
callbacks: {}
description: Create or update a user with the provided identification data. When you identify an existing user, the system merges the properties you specific with what is currently set on the user, updating only the fields included in your requests.
operationId: identifyUser
parameters:
- description: The unique identifier of the user.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
requestBody:
content:
application/json:
example:
channel_data:
97c5837d-c65c-4d54-aa39-080eeb81c69d:
tokens:
- push_token_123
email: ian.malcolm@chaos.theory
name: Dr. Ian Malcolm
preferences:
default:
channel_types:
email: true
workflows:
dinosaurs-loose:
channel_types:
email: true
timezone: America/New_York
schema:
$ref: '#/components/schemas/IdentifyUserRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: OK
summary: Identify user
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/preferences/{id}/categories/{key}:
put:
callbacks: {}
deprecated: true
description: Updates a single category in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceCategory
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update category in user preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/merge:
post:
callbacks: {}
description: Merge two users together, where the user specified with the `from_user_id` param will be merged into the user specified by `user_id`.
operationId: mergeUser
parameters:
- description: The id of the user to merge into.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
requestBody:
content:
application/json:
example:
from_user_id: user_1
schema:
$ref: '#/components/schemas/MergeUserRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: OK
summary: Merge users
tags:
- Users
x-ratelimit-tier: 2
/v1/users/bulk/preferences:
post:
callbacks: {}
description: Bulk sets the preferences for up to 1,000 users at a time. The preference set `:id` can be either `default` or a `tenant.id`. Learn more about [per-tenant preferences](/preferences/tenant-preferences). Note that this is a destructive operation and will replace any existing users' preferences with the preferences sent.
operationId: bulkSetUserPreferences
parameters: []
requestBody:
content:
application/json:
example:
preferences:
__persistence_strategy__: merge
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
channels:
2f641633-95d3-4555-9222-9f1eb7888a80:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
commercial_subscribed: true
workflows:
dinosaurs-loose:
channel_types:
email: false
user_ids:
- user_1
- user_2
schema:
$ref: '#/components/schemas/BulkSetUserPreferencesRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperation'
description: OK
summary: Bulk set preferences
tags:
- Users
x-ratelimit-tier: 1
/v1/users/bulk/identify:
post:
callbacks: {}
description: Identifies multiple users in a single operation. Allows creating or updating up to 1,000 users in a single batch with various properties, preferences, and channel data.
operationId: bulkIdentifyUsers
parameters: []
requestBody:
content:
application/json:
example:
users:
- email: jane@ingen.net
id: user_1
name: Jane Doe
timezone: America/New_York
schema:
$ref: '#/components/schemas/BulkIdentifyUsersRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperation'
description: OK
summary: Bulk identify users
tags:
- Users
x-ratelimit-tier: 1
/v1/users/{user_id}/preferences/{id}/workflows:
put:
callbacks: {}
deprecated: true
description: Updates the workflows in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceWorkflows
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update workflows in preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/preferences/{id}/categories:
put:
callbacks: {}
deprecated: true
description: Updates the categories in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceCategories
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update categories in user preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/bulk/delete:
post:
callbacks: {}
description: Permanently deletes up to 1,000 users at a time.
operationId: bulkDeleteUsers
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDeleteUsersRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperation'
description: OK
summary: Bulk delete users
tags:
- Users
x-ratelimit-tier: 1
/v1/users/{user_id}/preferences/{id}/channel_types/{type}:
put:
callbacks: {}
deprecated: true
description: Updates a single channel type in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceChannelType
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update channel type in preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/preferences:
get:
callbacks: {}
description: Retrieves a list of all preference sets for a specific user.
operationId: listUserPreferenceSets
parameters:
- description: The unique identifier of the user.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
description: A list of preference sets for the user.
example:
- categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
push: false
sms:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
commercial_subscribed: true
id: default
workflows: null
items:
$ref: '#/components/schemas/PreferenceSet'
title: ListUserPreferenceSetsResponse
type: array
x-struct: null
x-validate: null
description: OK
summary: List user preference sets
tags:
- Users
x-ratelimit-tier: 4
/v1/users:
get:
callbacks: {}
description: Retrieve a paginated list of users in the environment. Defaults to 50 users per page.
operationId: listUsers
parameters:
- description: Associated resources to include in the response.
in: query
name: include[]
required: false
schema:
items:
enum:
- preferences
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
- description: The cursor to fetch entries after.
in: query
name: after
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries before.
in: query
name: before
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The number of items per page (defaults to 50).
in: query
name: page_size
required: false
schema:
type: integer
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListUsersResponse'
description: OK
summary: List users
tags:
- Users
x-ratelimit-tier: 4
/v1/users/{user_id}/preferences/{id}/workflows/{key}:
put:
callbacks: {}
deprecated: true
description: Updates a single workflow in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceWorkflow
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update workflow in user preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/preferences/{id}:
delete:
callbacks: {}
description: Unsets the preference set for the user, removing it entirely.
operationId: deleteUserPreferenceSet
parameters:
- description: The unique identifier of the user.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: Unique identifier for the preference set.
in: path
name: id
required: true
schema:
default: default
example: default
type: string
x-struct: null
x-validate: null
responses:
'204':
description: No Content
summary: Delete user preference set
tags:
- Users
x-ratelimit-tier: 3
get:
callbacks: {}
description: Retrieves a specific preference set for a user identified by the preference set ID.
operationId: getUserPreferenceSet
parameters:
- description: The unique identifier of the user.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: Unique identifier for the preference set.
in: path
name: id
required: true
schema:
default: default
example: default
type: string
x-struct: null
x-validate: null
- description: The unique identifier for the tenant.
in: query
name: tenant
required: false
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Get user preference set
tags:
- Users
x-ratelimit-tier: 4
put:
callbacks: {}
description: 'Updates a complete preference set for a user. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use ''__persistence_strategy__'': ''merge'' to merge with existing preferences instead.'
operationId: updateUserPreferenceSet
parameters:
- description: The unique identifier of the user.
in: path
name: user_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: Unique identifier for the preference set.
in: path
name: id
required: true
schema:
default: default
example: default
type: string
x-struct: null
x-validate: null
requestBody:
content:
application/json:
example:
__persistence_strategy__: merge
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
channels:
2f641633-95d3-4555-9222-9f1eb7888a80:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
commercial_subscribed: true
workflows:
dinosaurs-loose:
channel_types:
email: false
schema:
$ref: '#/components/schemas/PreferenceSetRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update user preference set
tags:
- Users
x-ratelimit-tier: 3
/v1/users/{user_id}/preferences/{id}/channel_types:
put:
callbacks: {}
deprecated: true
description: Updates the channel types in a specific user preference set. This operation is deprecated.
operationId: updateUserPreferenceChannelTypes
parameters: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceSet'
description: OK
summary: Update channel types in preference set
tags:
- Users
x-ratelimit-tier: 3
components:
schemas:
BulkSetUserPreferencesRequest:
description: A request to set preferences for a set of users in bulk.
example:
preferences:
__persistence_strategy__: merge
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
channels:
2f641633-95d3-4555-9222-9f1eb7888a80:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
commercial_subscribed: true
workflows:
dinosaurs-loose:
channel_types:
email: false
user_ids:
- user_1
- user_2
properties:
preferences:
$ref: '#/components/schemas/PreferenceSetRequest'
user_ids:
description: A list of user IDs.
items:
description: The unique identifier of the user.
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
required:
- preferences
- user_ids
title: BulkSetUserPreferencesRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.BulkSetUserPreferencesRequest
x-validate: null
DiscordIncomingWebhookConnection:
description: Discord incoming webhook connection.
example:
incoming_webhook:
url: https://example.com/webhook
properties:
incoming_webhook:
description: Discord incoming webhook object.
properties:
url:
description: Incoming webhook URL.
example: https://example.com/webhook
type: string
x-struct: null
x-validate: null
required:
- url
type: object
x-struct: null
x-validate: null
required:
- incoming_webhook
title: DiscordIncomingWebhookConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.IncomingWebhookConnection
x-validate: null
BulkDeleteUsersRequest:
description: A request to delete users in bulk.
example:
user_ids:
- user_1
- user_2
properties:
user_ids:
description: A list of user IDs.
items:
description: The unique identifier of the user.
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
required:
- user_ids
title: BulkDeleteUsersRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.BulkDeleteUsersRequest
x-validate: null
InlineChannelDataRequest:
additionalProperties:
description: Channel data for a given channel type.
oneOf:
- $ref: '#/components/schemas/PushChannelDataTokensOnly'
- $ref: '#/components/schemas/PushChannelDataDevicesOnly'
- $ref: '#/components/schemas/AWSSNSPushChannelDataTargetARNsOnly'
- $ref: '#/components/schemas/AWSSNSPushChannelDataDevicesOnly'
- $ref: '#/components/schemas/OneSignalChannelDataPlayerIdsOnly'
- $ref: '#/components/schemas/SlackChannelData'
- $ref: '#/components/schemas/MsTeamsChannelData'
- $ref: '#/components/schemas/DiscordChannelData'
x-struct: null
x-validate: null
description: A request to set channel data for a type of channel inline.
example:
97c5837d-c65c-4d54-aa39-080eeb81c69d:
tokens:
- push_token_xxx
title: InlineChannelDataRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.InlineChannelDataRequest
x-validate: null
PushChannelDataTokensOnly:
description: Push channel data.
example:
tokens:
- push_token_1
- push_token_2
properties:
tokens:
description: A list of push channel tokens.
items:
description: The device token to send the push notification to.
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
required:
- tokens
title: PushChannelDataTokensOnly
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PushChannelDataTokensOnly
x-validate: null
PreferenceSet:
description: A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.
example:
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
push: false
sms:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
commercial_subscribed: true
id: default
workflows: null
properties:
categories:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the category and the values are the preference settings for that category.
example:
marketing:
channel_types:
email: false
title: PreferenceSetCategories
type: object
x-struct: null
x-validate: null
- x-struct: null
x-validate: null
description: An object where the key is the category and the values are the preference settings for that category.
x-struct: null
x-validate: null
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- x-struct: null
x-validate: null
description: An object where the key is the channel type and the values are the preference settings for that channel type.
x-struct: null
x-validate: null
channels:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannels'
- x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
x-struct: null
x-validate: null
commercial_subscribed:
description: Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
type:
- boolean
- 'null'
x-struct: null
x-validate: null
id:
description: Unique identifier for the preference set.
example: default
type: string
x-struct: null
x-validate: null
workflows:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
example:
dinosaurs-loose:
channel_types:
email: false
title: PreferenceSetWorkflows
type: object
x-struct: null
x-validate: null
- x-struct: null
x-validate: null
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
x-struct: null
x-validate: null
required:
- id
title: PreferenceSet
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSet
x-validate: null
OneSignalChannelDataPlayerIdsOnly:
description: OneSignal channel data.
example:
player_ids:
- 123e4567-e89b-12d3-a456-426614174000
properties:
player_ids:
description: A list of OneSignal player IDs.
example:
- 123e4567-e89b-12d3-a456-426614174000
items:
description: OneSignal player ID.
format: uuid
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
required:
- player_ids
title: OneSignalChannelDataPlayerIdsOnly
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.OneSignalChannelDataPlayerIdsOnly
x-validate: null
DiscordChannelConnection:
description: Discord channel connection.
example:
channel_id: '123456789012345678'
properties:
channel_id:
description: Discord channel ID.
example: '123456789012345678'
type: string
x-struct: null
x-validate: null
required:
- channel_id
title: DiscordChannelConnection
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.DiscordChannelData.ChannelConnection
x-validate: null
PreferenceSetRequest:
description: A request to set a preference set for a recipient.
example:
__persistence_strategy__: merge
categories:
marketing: false
transactional:
channel_types:
email: false
channel_types:
email: true
channels:
2f641633-95d3-4555-9222-9f1eb7888a80:
conditions:
- argument: US
operator: equal_to
variable: recipient.country_code
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
commercial_subscribed: true
workflows:
dinosaurs-loose:
channel_types:
email: false
properties:
__persistence_strategy__:
description: Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.
enum:
- merge
- replace
type: string
x-struct: null
x-validate: null
categories:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the category and the values are the preference settings for that category.
example:
marketing:
channel_types:
email: false
transactional: true
title: PreferenceSetRequestCategories
type: object
x-struct: null
x-validate: null
- x-struct: null
x-validate: null
description: An object where the key is the category and the values are the preference settings for that category.
x-struct: null
x-validate: null
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- x-struct: null
x-validate: null
description: An object where the key is the channel type and the values are the preference settings for that channel type.
x-struct: null
x-validate: null
channels:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannels'
- x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
x-struct: null
x-validate: null
commercial_subscribed:
description: Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.
type:
- boolean
- 'null'
x-struct: null
x-validate: null
workflows:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/PreferenceSetWorkflowCategorySetting'
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
example:
dinosaurs-loose:
channel_types:
email: false
sms: true
welcome-sequence: true
title: PreferenceSetRequestWorkflows
type: object
x-struct: null
x-validate: null
- x-struct: null
x-validate: null
description: An object where the key is the workflow key and the values are the preference settings for that workflow.
x-struct: null
x-validate: null
title: PreferenceSetRequest
type: object
x-struct: Elixir.SwitchboardWeb.V1.Specs.PreferenceSetRequest
x-validate: null
PreferenceSetWorkflowCategorySetting:
description: Workflow or category preferences within a preference set
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
oneOf:
- example: false
type: boolean
x-struct: null
x-validate: null
- description: The settings object for a workflow or category, where you can specify channel types or conditions.
example:
channel_types:
email: false
channels:
aef6e715-df82-4ab6-b61e-b743e249f7b6: true
conditions: null
properties:
channel_types:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannelTypes'
- x-struct: null
x-validate: null
description: An object where the key is the channel type and the values are the preference settings for that channel type.
x-struct: null
x-validate: null
channels:
anyOf:
- $ref: '#/components/schemas/PreferenceSetChannels'
- x-struct: null
x-validate: null
description: An object where the key is the channel ID and the values are the preference settings for that channel ID.
x-struct: null
x-validate: null
conditions:
description: A list of conditions to apply to a channel type.
items:
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock/refs/heads/main/openapi/knock-users-api-openapi.yml