openapi: 3.0.2
info:
title: Fyno Rest API
version: v1
servers:
- url: https://api.fyno.io/v1
security:
- BearerAuth: []
paths:
/{WSID}/{version}/event:
post:
tags:
- Fire an Event
summary: Notify a single user
description: This API enables you to fire a notification event, which sends out notifications to your users. <br/><br/>Before firing your first notification event, you must perform the following actions in your Fyno account:<br/>- Create a Template<br/>- Create a Notification Event<br/>- Create an API Key<br/>- And obtain your workspace ID from the API Keys page.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Enter the version for which you wish to fire the notification.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
description: Your event payload must specify at least *`distinct_id`* or *`to`* while firing a notification event.<br/><br/>If the payload contains:<br/><br/>- <b>Option 1:</b> ONLY *`to`* (and no *`distinct_id`*) - the notification event uses all destination values from the *`to`* object (as it is).<br/><br/>- <b>Option 2:</b> ONLY *`distinct_id`* (and no *`to`*) - the notificaton event uses all destination values (such as SMS, WhatsApp, Email, Push, Voice and so on) from the user's profile and sends the notification.<br/><br/>- <b>Option 3:</b> BOTH *`distinct_id`* and *`to`* - the `to` and `distinct_id` channel data merges (`to` object take precedences) and sends the notification. The sent notification is tagged to the ID specified, which can be then used to search the logs by using `distinct_id`.
content:
application/json:
schema:
$ref: "#/components/schemas/version_event_body"
required: true
responses:
"202":
$ref: "#/components/responses/EventRequestAccepted"
"400":
$ref: "#/components/responses/EventNameDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/event/bulk:
post:
tags:
- Fire an Event
summary: Notify multiple users
description: This API enables you to notify multiple users with one event trigger.<br/><br/>Before firing your first notification event, you must perform the following actions in your Fyno account:<br/>- Create a Template<br/>- Create an Event<br/>- Create an API Key<br/>- And obtain your workspace ID from the API Keys page.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Enter the version for which you wish to fire the notification.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/event_bulk_body"
required: true
responses:
"202":
$ref: "#/components/responses/BulkEventRequestAccepted"
"400":
$ref: "#/components/responses/EventNameDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles:
post:
tags:
- Manage User Profiles
summary: Create user profile
description: This API enables you to create a user profile within Fyno, which you can then use to send out notifications.<br/><br/>Before creating your first user profile, you should obtain the following values needed for authentication:<br/>- API Key<br/>- Workspace ID
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/version_profiles_body"
required: true
responses:
"201":
$ref: "#/components/responses/ProfileCreatedSuccessfully"
"400":
$ref: "#/components/responses/DistinctIDAlreadyExists"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/{distinct_id}:
get:
tags:
- Manage User Profiles
summary: Get user profile
description: This API enables you to get an existing user profile.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: path
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
responses:
"200":
$ref: "#/components/responses/ProfileFetched"
"400":
$ref: "#/components/responses/DistinctIDDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
put:
tags:
- Manage User Profiles
summary: Update user profile
description: This API enables you to update an existing user profile. It updates the entire user profile including `distinct_id` (if specified).<br/><br/>**Note:** If there were existing values in the profile, they will be completely replaced (if those keys are passed) or ignored (if those keys are not passed).
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: path
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/profiles_distinct_id_body"
required: true
responses:
"200":
$ref: "#/components/responses/ProfileUpdated"
"400":
$ref: "#/components/responses/DistinctIDDoesNotExist3"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/{source_distinct_id}/merge/{target_distinct_id}:
patch:
tags:
- Manage User Profiles
summary: Merge user profiles
description: This API enables you to merge the attributes of a user profile to another user profile. The profile with source distinct ID is merged with the target profile, after which the source profile is automatically deleted. If the target distinct ID does not exist, the source distinct ID is updated to target distinct ID.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: source_distinct_id
in: path
description: Enter the source distinct ID that you wish to merge from.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
- name: target_distinct_id
in: path
description: Enter the target distinct ID to which the profile should merge into.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
responses:
"200":
$ref: "#/components/responses/ProfileMergedSuccessfully"
"400":
$ref: "#/components/responses/SourceDistinctIDDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/delete:
post:
tags:
- Manage User Profiles
summary: Delete user profile
description: This API enables you to delete existing user profiles by using `distinct_id`.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/profiles_delete_body"
required: true
responses:
"200":
$ref: "#/components/responses/ProfileDeletedSuccessfully"
"400":
$ref: "#/components/responses/DistinctIDDoesNotExist2"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/{distinct_id}/channel:
patch:
tags:
- Manage User Profiles
summary: Add/Update channel data
description: This API enables you to update existing data for `sms`, `whatsapp`, `email`, `slack`, `discord`, and `teams` channels, and add new tokens for `push` and `inapp` channels. It works like an update for channels that can hold a single destination only and like an insert for channels that can hold multiple destinations/tokens.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: path
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/distinct_id_channel_body"
required: true
responses:
"200":
$ref: "#/components/responses/ProfileChannelUpdated"
"400":
$ref: "#/components/responses/DistinctIDDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/{distinct_id}/channel/delete:
post:
tags:
- Manage User Profiles
summary: Delete channel data
description: This API enables you to delete existing data for all channels. You can use either of the following approaches:<br/><br/>- **Option 1:** Use the `channel` key in the payload to delete all tokens in the specified channel.<br/>- **Option 2:** Use the `push` and `inapp` keys in the payload to delete specific tokens in these channels.<br/><br/>**Note:** You can use either option 1 or option 2. It is not allowed to use both approaches in one request.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: path
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: simple
explode: false
schema:
type: string
example: XXXXXXXX
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/channel_delete_body"
required: true
responses:
"200":
$ref: "#/components/responses/ProfileChannelUpdated"
"400":
$ref: "#/components/responses/DistinctIDOrChannelDataDoesNotExist"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/subscriptions/preference:
get:
tags:
- Manage User Subscriptions & Preferences
summary: Get user preference
description: This API enables you to get all the subscriptions topics (with sections) defined in your workspace along with the opted-in/opted-out preference of a particular user.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: query
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: form
explode: true
schema:
type: string
example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: event_list
in: query
description: Set this value to 'true' to receive list of notification events attached to each subscription topic.
required: false
style: form
explode: false
schema:
type: boolean
default: false
enum:
- true
- false
example: false
responses:
"200":
$ref: "#/components/responses/PrefProfileFetched"
"400":
$ref: "#/components/responses/DistinctIDMissing"
"401":
$ref: "#/components/responses/APIKeyInvalid"
put:
tags:
- Manage User Subscriptions & Preferences
summary: Update user preference
description: This API enables you to update the channel preference of a user for multiple subscription topics. In the JSON payload, enter the subscription ID as keys to update the channel preference. To update the user preference for all subscription topics at once (global preference), use 'all' instead of the subscription id.<br/><br/>**Note:** If the channel configuration for a subscription topic is set to 'required', then the user preference for the channel cannot be updated.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: distinct_id
in: query
description: Enter the distinct ID that you currently use to identify the user.
required: true
style: form
explode: true
schema:
type: string
example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/update_subscription_multiple"
required: true
responses:
"200":
$ref: "#/components/responses/SubscriptionUpdated"
"400":
$ref: "#/components/responses/DistinctIDChannelStatusMissing"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/subscriptions/list/{subscription_id}/user:
post:
tags:
- Manage User Subscriptions & Preferences
summary: Update user preference (single)
description: This API enables you to update the channel preference of a user for a particular subscription topic.<br/><br/>**Note:** If the channel configuration for a subscription topic is set to 'required', then the user preference for the channel cannot be updated.
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: subscription_id
in: path
description: Enter the subscription ID to update the channel preference for the subscription topic. To update the user preference for all subscription topics at once (global preference), use 'all' instead of the subscription id.
required: true
style: simple
explode: true
schema:
type: string
example: SXXXXXXXXX
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/update_subscription_single"
required: true
responses:
"200":
$ref: "#/components/responses/SubscriptionUpdated"
"400":
$ref: "#/components/responses/DistinctIDChannelStatusMissing"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/verify/validate:
post:
tags:
- Fyno Verify
summary: Verify OTP
description: This API enables you to validate the OTP entered by the user using either `request_id` (received in response of the Fire an Event API) or `destination` (such as phone number, email).
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to manage the user profile.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
- name: request_id
in: query
description: Specify the request id of the triggered notification event that sent the OTP to the user.<br/>You must use this query parameter if **you've disabled "Use destination as id"** in the Fyno Verify setting.
required: false
style: form
explode: true
schema:
type: string
example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- name: destination
in: query
description: Enter the destination where the OTP is sent. It can be either mobile no or email id.<br/>You must use this query parameter if **you've enabled "Use destination as id"** in the Fyno Verify setting.
required: false
style: form
explode: true
schema:
type: string
example: xxxxxxxxxx
- name: otp
in: query
description: Enter the OTP which you want to validate.
required: true
style: form
explode: true
schema:
type: string
example: 1234
responses:
"200":
$ref: "#/components/responses/OTPSuccess"
"400":
$ref: "#/components/responses/OTPInvalid"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/properties/set:
post:
tags:
- User Properties
summary: "Update User Property"
description: "This API enables you to update user properties of your users listed in your [User Profiles](../user-profiles-overview). If the user with distinct ID doesn't exist, it creates a new user with the provided distinct ID and updates values for all the provided properties.<br/><br/>**Note:** If a [property was not created earlier](../adding-new-user-property#how-to-add-a-new-user-property-from-user-profile-page), it will create a new property and the data type of the property will be determined based on the data type of the value. For example, if you `$set` a new property called `premium_user=true`, it will create the `premium_user` property with `Boolean` type and value `true`.<br/><br/>The property values can take the following data types:<ul> <li>**String:** Can be alphanumeric and contain a maximum of 255 characters. Example: `user_type=Premium` or `membership_number=ABC123`.</li> <li>**Number:** Can be an integer or a decimal. Example: `ltv=23000` or `cost=20.34`.</li> <li>**Boolean:** Can only contain `true` or `false` values.</li> <li>**Date:** Must be in ISO 8601 format. Example: `membership_date=2020-10-01T18:30:00.000Z` or `membership_date=2020-10-01T18:30:00Z` or `membership_date=2020-10-01T18:30:00.000+05:30` or `membership_date=2020-10-01T18:30:00+02:00` or `membership_date=2020-10-01`.</li> <li>**List:** Can contain an array of strings, numbers, and dates. Example: `products_ordered=['iPhone 16 Pro', 'iPad 32 GB']` or `purchase_amount=[23000, 20.34]` or `purchase_date=['2020-10-01T18:30:00Z', '2021-11-01T13:35:00+02:00', '2023-12-05']`</li></ul>If you try to set a value with a data type that does not match the predefined property type, the API will accept the request but ignore the invalid value. For example, if a predefined property `cost` expects a numeric value and you try to set it to `ABC`, the API will not store the value.<br/><br/>These user properties can be used to filter your users for creating [user cohorts](../creating-cohorts) and [campaigns](../campaign_creation#creating-a-campaign-using-cohort)."
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to update the user property.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/set_user_property"
required: true
responses:
"202":
$ref: "#/components/responses/PropertyUpdateRequestAccepted"
"400":
$ref: "#/components/responses/EmptySetObject"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/properties/set-once:
post:
tags:
- User Properties
summary: "Set an Unset Property"
description: "This API enables you to set user properties of your users listed in your [User Profiles](../user-profiles-overview) **only if it is currently unset.** If the given payload contains a mix of properties that are currently set and unset, then it will only add values to the properties that are currently unset and ignore the other properties. If the user with distinct ID doesn't exist, it creates a new user with the provided distinct ID and sets values for all the provided properties.<br/><br/>**Note:** If a [property was not created earlier](../adding-new-user-property#how-to-add-a-new-user-property-from-user-profile-page), it will create a new property and the data type of the property will be determined based on the data type of the value. For example, if you `$once` a new property called `premium_user=true`, it will create the `premium_user` property with `Boolean` type and value `true`.<br/><br/>The property values can take the following data types:<ul> <li>**String:** Can be alphanumeric and contain a maximum of 255 characters. Example: `user_type=Premium` or `membership_number=ABC123`.</li> <li>**Number:** Can be an integer or a decimal. Example: `ltv=23000` or `cost=20.34`.</li> <li>**Boolean:** Can only contain `true` or `false` values.</li> <li>**Date:** Must be in ISO 8601 format. Example: `membership_date=2020-10-01T18:30:00.000Z` or `membership_date=2020-10-01T18:30:00Z` or `membership_date=2020-10-01T18:30:00.000+05:30` or `membership_date=2020-10-01T18:30:00+02:00` or `membership_date=2020-10-01`.</li> <li>**List:** Can contain an array of strings, numbers, and dates. Example: `products_ordered=['iPhone 16 Pro', 'iPad 32 GB']` or `purchase_amount=[23000, 20.34]` or `purchase_date=['2020-10-01T18:30:00Z', '2021-11-01T13:35:00+02:00', '2023-12-05']`</li> </ul>If you try to set a value with a data type that does not match the predefined property type, the API will accept the request but ignore the invalid value. For example, if a predefined property `cost` expects a numeric value and you try to set it to `ABC`, the API will not store the value.<br/><br/>These user properties can be used to filter your users for creating [user cohorts](../creating-cohorts) and [campaigns](../campaign_creation#creating-a-campaign-using-cohort)."
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to update the user property.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/set_user_property_once"
required: true
responses:
"202":
$ref: "#/components/responses/PropertyUpdateRequestAccepted"
"400":
$ref: "#/components/responses/EmptySetOnceObject"
"401":
$ref: "#/components/responses/APIKeyInvalid"
/{WSID}/{version}/profiles/properties/numerical-add:
post:
tags:
- User Properties
summary: "Increment/Decrement Numeric Property"
description: "This API enables you to increment/decrement values of numeric properties of your users listed in your [User Profiles](../user-profiles-overview). If the user with distinct ID doesn't exist, it creates a new user with the provided distinct ID and updates values for all the provided properties. To decrement property values, you can pass a negative value.<br/><br/>**Note:** If a [property was not created earlier](../adding-new-user-property#how-to-add-a-new-user-property-from-user-profile-page), it will create a new property and the data type of the property will set to `Number`. For example, if you `$add` a new property called `ltv=1200`, it will create the `ltv` property with `Number` type and value `1200`. Do not enclose the value in double quotes as they must be of numeric type.<br/><br/>These user properties can be used to filter your users for creating [user cohorts](../creating-cohorts) and [campaigns](../campaign_creation#creating-a-campaign-using-cohort)."
parameters:
- name: WSID
in: path
description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
required: true
style: simple
explode: false
schema:
type: string
example: FYXXXXXXXX
- name: version
in: path
description: Specify the version for which you would like to update the user property.
required: true
style: simple
explode: false
schema:
type: string
default: live
enum:
- live
- test
# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fyno/refs/heads/main/openapi/fyno-notification-events-openapi.yml