openapi: 3.0.2
info:
title: Fyno Rest Fire an Event User Properties API
version: v1
servers:
- url: https://api.fyno.io/v1
security:
- BearerAuth: []
tags:
- name: User Properties
paths:
/{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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/increment_user_property'
required: true
responses:
'202':
$ref: '#/components/responses/PropertyUpdateRequestAccepted'
'400':
$ref: '#/components/responses/EmptyAddObject'
'401':
$ref: '#/components/responses/APIKeyInvalid'
/{WSID}/{version}/profiles/properties/list-append:
post:
tags:
- User Properties
summary: Append Values to List
description: 'This API enables you to append values to list type 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 set to `List`. For example, if you `$append` a new property called `order_ids=245`, it will create the `order_ids` property with `List` type and value `[245]`. A list may contain only unique values, so if a value already exists, and you try to add the same value, it will be ignored. <br/><br/>You can append values with the following data types:<ul> <li>**String:** Can be alphanumeric and contain a maximum of 255 characters. Example: `products_order=[''iPhone 16 Pro'', ''iPad 32 GB'']`.</li> <li>**Number:** Can be an integer or a decimal. Example: `purchase_amount=[23000, 20.34]`.</li> <li>**Date:** Must be in ISO 8601 format: `YYYY-MM-DDTHH:MM:SS.sssZ`. 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> </ul>You can append only one value to a property at a time. Although not recommended, a list property can contain a mix of different data types.<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/append_to_user_property'
required: true
responses:
'202':
$ref: '#/components/responses/PropertyUpdateRequestAccepted'
'400':
$ref: '#/components/responses/EmptyAppendObject'
'401':
$ref: '#/components/responses/APIKeyInvalid'
/{WSID}/{version}/profiles/properties/list-remove:
post:
tags:
- User Properties
summary: Remove Value From List
description: This API enables you to remove existing values from the list type properties of your users listed in your [User Profiles](../user-profiles-overview). If the specified distinct ID or list property doesn't exist, it simply accepts the remove request and ignores it.<br/><br/>**Note:** This API can only be used to remove values from list and can remove only one value from a property at a time. To unset (nullify) other property types, please use [Unset User Property API.](./unset-user-property)
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/remove_from_user_property_list'
required: true
responses:
'202':
$ref: '#/components/responses/PropertyUpdateRequestAccepted'
'400':
$ref: '#/components/responses/EmptyRemoveObject'
'401':
$ref: '#/components/responses/APIKeyInvalid'
/{WSID}/{version}/profiles/properties/unset:
post:
tags:
- User Properties
summary: Unset User Property
description: 'This API enables you to unset (nullify) user properties of your users listed in your [User Profiles](../user-profiles-overview). If the specified distinct ID or property doesn''t exist, it simply accepts the unset request and ignores it. This API can be used to unset all property data types: String, Number, Boolean, Date, List.'
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/unset_user_property'
required: true
responses:
'202':
$ref: '#/components/responses/PropertyUpdateRequestAccepted'
'400':
$ref: '#/components/responses/EmptyUnsetObject'
'401':
$ref: '#/components/responses/APIKeyInvalid'
/{WSID}/{version}/profiles/properties/batch:
post:
tags:
- User Properties
summary: Batch Update User Properties
description: This API enables you to modify user properties of your users listed in your [User Profiles](../user-profiles-overview) in bulk:<br/><ul><li>[Update User Properties](./update-user-property) - `$set`</li><li>[Set Unset Properties](./set-an-unset-property) - `$once`</li><li>[Increment/Decrement Numeric Properties](./increment-decrement-numeric-property) - `$add`</li><li>[Append Values to List](./append-values-to-list) - `$append`</li><li>[Remove Values From List](./remove-value-from-list) - `$remove`, and</li><li>[Unset User Properties](./unset-user-property) `$unset`</li></ul><strong>Please refer to function specific API documentation for [$set](./update-user-property), [$once](./set-an-unset-property), [$add](./increment-decrement-numeric-property), [$append](./append-values-to-list), [$remove](./remove-value-from-list), [$unset](./unset-user-property) before using this API.</strong><br/></br><br/>**Note:** The user properties in User Profiles 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/user_property_bulk'
responses:
'202':
$ref: '#/components/responses/PropertyUpdateRequestAcceptedBulk'
'400':
$ref: '#/components/responses/EmptyActionBulkProperty'
'401':
$ref: '#/components/responses/APIKeyInvalid'
components:
responses:
EmptySetObject:
description: $set object is empty
content:
application/json:
schema:
properties:
_message:
example: $set has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
APIKeyInvalid:
description: API Key or Workspace ID is invalid. User is unauthorised.
content:
application/json:
schema:
properties:
_message:
example: Invalid API details
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
EmptyRemoveObject:
description: $remove object is empty
content:
application/json:
schema:
properties:
_message:
example: $remove has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
EmptyAddObject:
description: $add object is empty
content:
application/json:
schema:
properties:
_message:
example: $add has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
EmptyActionBulkProperty:
description: $unset object is empty
content:
application/json:
schema:
properties:
_message:
example: $set has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
EmptyUnsetObject:
description: $unset object is empty
content:
application/json:
schema:
properties:
_message:
example: $unset channel should have atleast one item in array
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
PropertyUpdateRequestAccepted:
description: Request has been accepted and will be processed asynchronously.
content:
application/json:
schema:
properties:
request_id:
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
type: string
type: object
required:
- request_id
EmptyAppendObject:
description: $append object is empty
content:
application/json:
schema:
properties:
_message:
example: $append has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
EmptySetOnceObject:
description: $once object is empty
content:
application/json:
schema:
properties:
_message:
example: $once has object/keys that is not allowed
type: string
status:
example: error
type: string
type: object
required:
- _message
- status
PropertyUpdateRequestAcceptedBulk:
description: Request has been accepted and will be processed asynchronously.
content:
application/json:
schema:
properties:
request_id:
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
type: string
batch:
type: array
items:
properties:
$set:
type: string
example: ok
$once:
type: string
example: ok
$add:
type: string
example: ok
$append:
type: string
example: ok
$remove:
type: string
example: ok
$unset:
type: string
example: ok
type: object
type: object
required:
- request_id
- batch
schemas:
distinct_id:
description: Enter the distinct ID that you use to identify the recipient.
example: XXXXXXXX
type: string
set_user_property_fields:
description: Enter the property name as JSON key and the value to set as JSON value
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
- type: string
format: date
- type: array
example:
property_1: some text
property_2: 123
property_3: 45.67
property_4: true
property_5: false
property_6: '2020-10-01T18:30:00.000Z'
property_7: '2021-12-01'
property_8:
- iPhone 16 Pro
- iPad 32 GB
property_9:
- 23000
- 20.34
property_n:
- '2020-10-01T18:30:00Z'
- '2021-11-01T13:35:00+02:00'
- '2023-12-05'
type: object
set_user_property_once:
properties:
$once:
$ref: '#/components/schemas/set_user_property_once_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $once
type: object
unset_user_property:
properties:
$unset:
$ref: '#/components/schemas/unset_user_property_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $unset
type: object
append_to_user_property:
properties:
$append:
$ref: '#/components/schemas/append_to_user_property_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $append
type: object
increment_user_property:
properties:
$add:
$ref: '#/components/schemas/increment_user_property_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $add
type: object
set_user_property:
properties:
$set:
$ref: '#/components/schemas/set_user_property_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $set
type: object
set_user_property_once_fields:
description: Enter the property name as JSON key and the value to set as JSON value
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
- type: string
format: date
- type: array
example:
property_1: some text
property_2: 123
property_3: 45.67
property_4: true
property_5: false
property_6: '2020-10-01T18:30:00.000Z'
property_7: '2021-12-01'
property_8:
- iPhone 16 Pro
- iPad 32 GB
property_9:
- 23000
- 20.34
property_n:
- '2020-10-01T18:30:00Z'
- '2021-11-01T13:35:00+02:00'
- '2023-12-05'
type: object
user_property_bulk:
properties:
batch:
description: Enter an array of objects with `distinct_id` and `action` to perform on the user properties
items:
type: object
properties:
distinct_id:
$ref: '#/components/schemas/distinct_id'
action:
type: object
properties:
$set:
$ref: '#/components/schemas/set_user_property_fields'
$once:
$ref: '#/components/schemas/set_user_property_once_fields'
$add:
$ref: '#/components/schemas/increment_user_property_fields'
$append:
$ref: '#/components/schemas/append_to_user_property_fields'
$remove:
$ref: '#/components/schemas/remove_from_user_property_list_fields'
$unset:
$ref: '#/components/schemas/unset_user_property_fields'
example:
distinct_id: XXXXX
action:
$set:
property_1: some text
property_2: 123
property_3: 45.67
$once:
property_4: true
property_5:
- iPhone 16 Pro
- iPad 32 GB
property_6: '2020-10-01T18:30:00.000Z'
$add:
property_7: 10.23
property_8: -11.9
property_9: 223
$append:
property_10: '#12345'
property_11: 2030
property_12: '2022-11-11T10:30:00+02:00'
$remove:
property_13: '2023-11-10'
property_14: ABC1234
property_15: 4010
$unset:
- property_0
- old_property1
required:
- distinct_id
- action
type: array
required:
- batch
increment_user_property_fields:
description: Enter the property name as JSON key and the numeric value to increment/decrement as JSON value
example:
property_1: 23.4
property_2: 20301
property_n: -39.45
additionalProperties:
type: number
type: object
remove_from_user_property_list_fields:
description: Enter the property name as JSON key and the value to remove as JSON value
additionalProperties:
oneOf:
- type: number
- type: string
- type: string
format: date
example:
property_1: some text
property_2: 123
property_3: 45.67
property_4: '2020-10-01T18:30:00.000Z'
property_5: '2021-12-01'
property_n: '2021-11-01T13:35:00+02:00'
type: object
remove_from_user_property_list:
properties:
$remove:
$ref: '#/components/schemas/remove_from_user_property_list_fields'
distinct_id:
$ref: '#/components/schemas/distinct_id'
required:
- distinct_id
- $remove
type: object
append_to_user_property_fields:
description: Enter the property name as JSON key and the numeric or string value to append as JSON value
additionalProperties:
oneOf:
- type: number
- type: string
- type: string
format: date
example:
property_1: some text
property_2: 123
property_3: 45.67
property_4: '2020-10-01T18:30:00.000Z'
property_5: '2021-12-01'
property_n: '2021-11-01T13:35:00+02:00'
type: object
unset_user_property_fields:
description: Enter the property names to unset in an array
example:
- property_1
- property_2
- property_n
items:
type: string
type: array
securitySchemes:
BearerAuth:
type: http
description: Enter your API Key. If you don't have it already, you can create one from the API Keys page within your Fyno account
scheme: bearer
x-fern-bearer:
name: apiKey
env: FYNO_API_KEY