Update a Profile

PATCH https://api.botsi.com/v2/profiles/{profileId}

Update a Profile's details after it's created. For example, call it when the user signs in and you learn their email, or after an app or OS update, resending os, appVersion, and device. AI Pricing reads the Profile's os and device, so keep them current.

This route accepts $BOTSI_SECRET_KEY or $BOTSI_PUBLIC_KEY in the Authorization header, with no Bearer prefix. The sample sends the secret key. From inside the app, send the public key. Delete a Profile is the exception and accepts the secret key only. See Authentication.

Sending a partial update#

Every field is optional. What you send for a field decides what happens to it:

You send	What happens
Nothing, because the field is omitted	The field is left unchanged
A value	The field is set to that value
`null`	The field is cleared
`{}` as the whole body	Nothing changes, and the current Profile is returned

device, os, appVersion, and country can be changed but not cleared

Sending null or an empty string for any of them returns 400. Omit the field to leave it as it is.

Path parameters#

Parameter	Type	Required	Description
`profileId`	string	Required	Botsi profile ID from Create a Profile

Request body#

Parameter	Type	Can clear with `null`	Description
`email`	string	Yes	Must be a valid email address
`phone`	string	Yes	Phone number
`username`	string	Yes	Username
`gender`	string	Yes	Gender
`birthday`	string	Yes	Strict ISO 8601 date, for example `1990-04-12`. Botsi recalculates the Profile's age from it, and `null` clears both birthday and age
`idfa`	string	Yes	Apple identifier for advertisers
`advertisingId`	string	Yes	Google advertising ID
`ipAddress`	string	Yes	Must be a valid IPv4 or IPv6 address
`device`	string	No	Device model. Botsi normalizes it the same way as on Create a Profile. For example, the iOS machine identifier `iPhone17,2` is stored as its model name
`os`	string	No	Operating system and version, for example `iOS 26.5`
`appVersion`	string	No	App version, for example `2.0.0`
`appBuild`	string	Yes	Build number, for example `412`
`locale`	string	Yes	Locale code, for example `en-US`
`country`	string	No	Two-letter ISO 3166-1 alpha-2 code such as `US`, or an uppercase alpha-3 code such as `USA`, which is stored as alpha-2. An alpha-3 code Botsi can't map returns `400`

# Authorization: $BOTSI_SECRET_KEY or $BOTSI_PUBLIC_KEY
curl -X PATCH "https://api.botsi.com/v2/profiles/fff3c120-0ca8-480f-9b19-3955a5428e39" \
  -H "Authorization: $BOTSI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "os": "iOS 26.5",
    "appVersion": "2.0.0",
    "appBuild": "412",
    "phone": null
  }'

Fields this endpoint doesn't change#

These fields are dropped without an error

Sending them returns 200 with the field unchanged, so a request that looks successful can leave the Profile exactly as it was.

Field	Change it with
`custom`	Add Custom Attributes or Update Custom Attributes
`appUserId`	Set once on Create a Profile
`platform`	Fixed when the Profile is created

Any other field Botsi doesn't recognize is dropped the same way.

Response#

The response is the updated Profile in the same shape as Get a Profile, custom included. It isn't a bare { "ok": true }.

That shape carries the Profile's access and custom attributes, not the details you sent, so email and os don't come back. A 200 confirms the write.

{
  "ok": true,
  "data": {
    "profileId": "fff3c120-0ca8-480f-9b19-3955a5428e39",
    "appUserId": "user-123",
    "state": "never-subscribed",
    "totalRevenueUsd": 0,
    "accessLevels": {},
    "subscriptions": {},
    "nonSubscriptions": {},
    "custom": [
      { "id": "Kj3xQz9a", "key": "user_level", "value": "vip" }
    ]
  }
}

Errors#

A 400 lists every validation failure in error, separated by commas.

Code	Message	Cause
`400`	`email must be an email`	A malformed email, IP address, or date. Also returned for an alpha-3 country Botsi can't map, or for `null` or an empty string in `device`, `os`, `appVersion`, or `country`
`401`	`No valid API key provided.`	The `Authorization` header is missing or holds an unknown key
`404`	`No profile found by id: fff3c120-0ca8-480f-9b19-3955a5428e39`	No Profile with that ID belongs to your app. A Profile owned by another app returns the same response