> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fyno.io/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fyno.io/docs/_mcp/server. # Set an Unset Property POST https://api.fyno.io/v1/{WSID}/{version}/profiles/properties/set-once Content-Type: application/json 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. **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`. The property values can take the following data types: - **String:** Can be alphanumeric and contain a maximum of 255 characters. Example: `user_type=Premium` or `membership_number=ABC123`. - **Number:** Can be an integer or a decimal. Example: `ltv=23000` or `cost=20.34`. - **Boolean:** Can only contain `true` or `false` values. - **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`. - **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']` 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. 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). Reference: https://fyno.io/docs/api-reference/set-an-unset-property ## Authentication - `Authorization` header (bearer token, required) — Enter your API Key. If you don't have it already, you can create one from the API Keys page within your Fyno account ## Request ### Path parameters - `WSID` (string, required) — Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account. - `version` (string, required) — Specify the version for which you would like to update the user property. ### Body (application/json) This endpoint expects a set_user_property_once. - `$once` (map from string to SetUserPropertyOnceFields, required) — Enter the property name as JSON key and the value to set as JSON value - `distinct_id` (string, required) — Enter the distinct ID that you use to identify the recipient. ## Response ### 202 Request has been accepted and will be processed asynchronously. - `request_id` (string, required) ## Errors ### 400 Bad Request Error $once object is empty - `_message` (string, required) - `status` (string, required) ### 401 Unauthorized Error API Key or Workspace ID is invalid. User is unauthorised. - `_message` (string, required) - `status` (string, required) ## Types ### SetUserPropertyOnceFields ## Examples **Request** ```json { "$once": { "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" ] }, "distinct_id": "XXXXXXXX" } ``` **Response** ```json { "request_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" } ``` **SDK Code** ```python import requests url = "https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once" payload = { "$once": { "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"] }, "distinct_id": "XXXXXXXX" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"$once":{"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"]},"distinct_id":"XXXXXXXX"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once" payload := strings.NewReader("{\n \"$once\": {\n \"property_1\": \"some text\",\n \"property_2\": 123,\n \"property_3\": 45.67,\n \"property_4\": true,\n \"property_5\": false,\n \"property_6\": \"2020-10-01T18:30:00.000Z\",\n \"property_7\": \"2021-12-01\",\n \"property_8\": [\n \"iPhone 16 Pro\",\n \"iPad 32 GB\"\n ],\n \"property_9\": [\n 23000,\n 20.34\n ],\n \"property_n\": [\n \"2020-10-01T18:30:00Z\",\n \"2021-11-01T13:35:00+02:00\",\n \"2023-12-05\"\n ]\n },\n \"distinct_id\": \"XXXXXXXX\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"$once\": {\n \"property_1\": \"some text\",\n \"property_2\": 123,\n \"property_3\": 45.67,\n \"property_4\": true,\n \"property_5\": false,\n \"property_6\": \"2020-10-01T18:30:00.000Z\",\n \"property_7\": \"2021-12-01\",\n \"property_8\": [\n \"iPhone 16 Pro\",\n \"iPad 32 GB\"\n ],\n \"property_9\": [\n 23000,\n 20.34\n ],\n \"property_n\": [\n \"2020-10-01T18:30:00Z\",\n \"2021-11-01T13:35:00+02:00\",\n \"2023-12-05\"\n ]\n },\n \"distinct_id\": \"XXXXXXXX\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"$once\": {\n \"property_1\": \"some text\",\n \"property_2\": 123,\n \"property_3\": 45.67,\n \"property_4\": true,\n \"property_5\": false,\n \"property_6\": \"2020-10-01T18:30:00.000Z\",\n \"property_7\": \"2021-12-01\",\n \"property_8\": [\n \"iPhone 16 Pro\",\n \"iPad 32 GB\"\n ],\n \"property_9\": [\n 23000,\n 20.34\n ],\n \"property_n\": [\n \"2020-10-01T18:30:00Z\",\n \"2021-11-01T13:35:00+02:00\",\n \"2023-12-05\"\n ]\n },\n \"distinct_id\": \"XXXXXXXX\"\n}") .asString(); ``` ```php request('POST', 'https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once', [ 'body' => '{ "$once": { "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" ] }, "distinct_id": "XXXXXXXX" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"$once\": {\n \"property_1\": \"some text\",\n \"property_2\": 123,\n \"property_3\": 45.67,\n \"property_4\": true,\n \"property_5\": false,\n \"property_6\": \"2020-10-01T18:30:00.000Z\",\n \"property_7\": \"2021-12-01\",\n \"property_8\": [\n \"iPhone 16 Pro\",\n \"iPad 32 GB\"\n ],\n \"property_9\": [\n 23000,\n 20.34\n ],\n \"property_n\": [\n \"2020-10-01T18:30:00Z\",\n \"2021-11-01T13:35:00+02:00\",\n \"2023-12-05\"\n ]\n },\n \"distinct_id\": \"XXXXXXXX\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "$once": [ "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"] ], "distinct_id": "XXXXXXXX" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.fyno.io/v1/FYXXXXXXXX/version/profiles/properties/set-once")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```