> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/engineering-reference/api/account.md).

# Account API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/api/account.md).
{% endhint %}

The user's own profile, GDPR consent, on-call status, preferences and account deletion, and the dynamic links that invite people to a site's groups; sign-in and passwords are in the [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md).

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`). The profile, GDPR, on-call and deletion routes act on the token's user; preferences also need a relation with the site. The dynamic link routes check nothing about the caller beyond the token. `DELETE /v1/app/user` also needs a fresh token. php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). `delete_user_account`, `read_on_call_status` and `update_on_call_status` take the user from the token's payload, and don't check its signature themselves; the dispatcher checks it only when `JWT_AUTH_ENABLED` is on. The php-apis GDPR actions take the user from the request, not from the token.
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent (Simon, the AI assistant); 5 of the 18 endpoints have no known caller
* **Errors:** the envelope and the codes every `/v1/app` route can return are in [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); the php-apis envelope is in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). Each endpoint lists its own.
* **Logs:** Laravel calls go to the request log, with the response when it is under about 100 KB; php-apis calls go to its daily request log, with the response when it is under about 100 KB. See [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).
* **Methods on php-apis:** the dispatcher accepts any HTTP method except `OPTIONS`, which answers `200` with `result` `false` and "invalid http method" (php-apis @ aee9175122, `html/api/snapfix/index.php:231-237`). The table lists the method the apps send.
* **Related:** the on-call roster, `POST /v1/app/user/on-call`, is in the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md). The screens that use these endpoints are in [account screens](https://docs.snapfix.com/how-the-apps-work/screens/account.md).

| Method | Path                                                                          | Service            | Purpose                                                                                                                                                                                     |
| ------ | ----------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | [`/v1/app/generate-dynamic-link`](#post-v1appgenerate-dynamic-link)           | api\_php\_live\_v2 | Create a QR invitation link for sites and groups                                                                                                                                            |
| PUT    | [`/v1/app/generate-dynamic-link/{uuid}`](#put-v1appgenerate-dynamic-linkuuid) | api\_php\_live\_v2 | Replace a QR invitation link, retiring the old one                                                                                                                                          |
| GET    | [`/v1/app/user`](#get-v1appuser)                                              | api\_php\_live\_v2 | Get the user's profile                                                                                                                                                                      |
| PUT    | [`/v1/app/user`](#put-v1appuser)                                              | api\_php\_live\_v2 | Change the user's profile; names are saved as sent                                                                                                                                          |
| DELETE | [`/v1/app/user`](#delete-v1appuser)                                           | api\_php\_live\_v2 | Delete the user's profile                                                                                                                                                                   |
| GET    | [`/v1/app/user/gdpr`](#get-v1appusergdpr)                                     | api\_php\_live\_v2 | Get the user's GDPR consent (no caller) \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)]  |
| POST   | [`/v1/app/user/gdpr`](#post-v1appusergdpr)                                    | api\_php\_live\_v2 | Save the user's GDPR consent (no caller) \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)] |
| GET    | [`/v1/app/user/on-call-status`](#get-v1appuseron-call-status)                 | api\_php\_live\_v2 | Get the user's on-call status per site                                                                                                                                                      |
| PUT    | [`/v1/app/user/on-call-status`](#put-v1appuseron-call-status)                 | api\_php\_live\_v2 | Set the user's on-call status for one or more sites                                                                                                                                         |
| GET    | [`/v1/app/user/preferences`](#get-v1appuserpreferences)                       | api\_php\_live\_v2 | Get one saved preference for a site                                                                                                                                                         |
| PUT    | [`/v1/app/user/preferences`](#put-v1appuserpreferences)                       | api\_php\_live\_v2 | Save one preference for a site                                                                                                                                                              |
| DELETE | [`?action=delete_user_account`](#delete-actiondelete_user_account)            | php-apis           | Delete the user's account from the mobile apps                                                                                                                                              |
| GET    | [`?action=read_on_call_status`](#get-actionread_on_call_status)               | php-apis           | Get the user's on-call status per site (mobile)                                                                                                                                             |
| ANY    | `?action=read_pri_log_usergdpr`                                               | php-apis           | Read the user's GDPR consent (no caller)                                                                                                                                                    |
| POST   | [`?action=save_pri_log_usergdpr`](#post-actionsave_pri_log_usergdpr)          | php-apis           | Save the mobile apps' GDPR consent rows                                                                                                                                                     |
| POST   | [`?action=update_on_call_status`](#post-actionupdate_on_call_status)          | php-apis           | Set the user's on-call status for one site (mobile)                                                                                                                                         |
| ANY    | `?action=webcust_get_user_gdpr`                                               | php-apis web       | Get the user's GDPR consent (no caller)                                                                                                                                                     |
| ANY    | `?action=webcust_update_user_gdpr`                                            | php-apis web       | Change the user's GDPR consent (no caller)                                                                                                                                                  |

The two `/v1/app/user/gdpr` routes have a client in web\_app\_v2 (`ProfileCommunicationPreferencesComponent`), but no page places that component, so nothing calls them \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)]. They keep a short section because other docs link to them. The mobile apps save consent through [`save_pri_log_usergdpr`](#post-actionsave_pri_log_usergdpr).

## POST /v1/app/generate-dynamic-link

Creates a QR invitation link: someone who opens it can join the named groups of one or more sites, with the named roles. The apps show the link as a QR code on the add-user sheet.

* **Auth:** user token. Any signed-in user can call it. The code checks that each site exists and that each group belongs to its site, but not that the caller belongs to them or may manage them.
* **Used by:** iOS and Android, on the add-user QR sheet.

**Request** (JSON)

| Name                          | In   | Type   | Required | Rules                                                                                                                                                                                            |
| ----------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`                       | body | string | no       | The link's title; empty when omitted. Neither app sends it                                                                                                                                       |
| `description`                 | body | string | no       | The link's description; empty when omitted. Neither app sends it                                                                                                                                 |
| `parents`                     | body | array  | yes      | One item per site; an empty array fails                                                                                                                                                          |
| `parents[].uuid`              | body | string | yes      | A site that exists and isn't deleted                                                                                                                                                             |
| `parents[].userType`          | body | string | yes      | `Admin` or `User`: the invitee's role in the site                                                                                                                                                |
| `parents[].groups`            | body | array  | yes      | One item per group; an empty array fails, so every invitation names groups \[[ASK-33](https://github.com/snapfix/docs/blob/main/ASK.md#ask-33-are-invitations-for-a-whole-site-no-group-wanted)] |
| `parents[].groups[].uuid`     | body | string | yes      | A group that isn't deleted and belongs to the site of its item                                                                                                                                   |
| `parents[].groups[].userType` | body | string | yes      | `Admin` or `User`: the invitee's role in the group                                                                                                                                               |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "shorturl": "https://links.example.com/?ctx=123"
  }
}
```

`uuid` is the link's ID. `shorturl` is the link to share: the server's `DYNAMIC_LINK_DOMAIN` followed by `/?ctx=` and the ID. It is built locally; no Firebase Dynamic Link is created.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when a site or group is unknown or deleted, when a group belongs to another site, or when a role isn't `Admin` or `User`. The message is the first failed rule, for example "Group 123 does not belong to parent 45.".

**Side effects:**

* Adds a row to [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md): a new ID, the title, the description, the type `qrcode-invitation`, `origin` from the `fOrigin` header (`na` when missing), and the caller as `uuid_tUser_CreatedBy`.
* Adds one row per group to [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md), with the site, the site role, the group, the group role and the default group permissions (view tasks on, everything else off), created by the caller.
* Sends no email, SMS or push: the caller shares the link.

## PUT /v1/app/generate-dynamic-link/{uuid}

Replaces a QR invitation link: makes a new link with the same title, description, type and invitations, and marks the old link and its invitations deleted, so a QR code shown earlier stops working.

* **Auth:** user token. Any signed-in user can replace any link by its ID. The code doesn't check that the caller created the link or belongs to its sites.
* **Used by:** iOS and Android, to regenerate the QR sheet's link.

**Request**

| Name   | In   | Type   | Required | Rules                                          |
| ------ | ---- | ------ | -------- | ---------------------------------------------- |
| `uuid` | path | string | yes      | The ID of a link that exists and isn't deleted |

No body.

**Response** `200`: the new link, in the same shape as [POST /v1/app/generate-dynamic-link](#post-v1appgenerate-dynamic-link).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "124",
    "shorturl": "https://links.example.com/?ctx=124"
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when the link doesn't exist or is deleted (the path ID is validated like a body field).

**Side effects:**

* Adds a [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md) row with a new ID and short URL, the old title, description and type, `origin` from the current request, and the caller as `uuid_tUser_CreatedBy`.
* Marks each old [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md) row deleted, then the old link (`fDeleted`), and only then adds copies of the invitations under the new link. The copies keep the site, site role, group, group role, permissions, and the original creator and last editor.

## GET /v1/app/user

Returns the signed-in user's profile.

* **Auth:** user token. Returns the token's user only.
* **Used by:** web (profile drawer).

**Request:** none.

**Response** `200`: a [user object](#user-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "username": "jane@example.com",
    "name": "Jane Smith",
    "firstname": "Jane",
    "lastname": "Smith",
    "countryCode": 44,
    "mobile": 5550100,
    "image": null,
    "address": null,
    "language": "en",
    "emailVerified": 1,
    "mobileVerified": 0,
    "notes": null,
    "showAiAgentTooltip": 0,
    "userType": "User",
    "userParentDeleted": null
  }
}
```

`userType` is always `User` in this response, and `userParentDeleted` is always `null`, because the code reads both from site-membership fields that this call doesn't load.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors).

**Side effects:** none.

## PUT /v1/app/user

Changes the signed-in user's name fields, photo URL, language and Simon tooltip setting. Fields that are not sent stay as they are.

* **Auth:** user token. Changes the token's user only.
* **Used by:** web (the profile drawer's name and language screens, and the Simon tour, which turns the tooltip off).

**Request** (JSON; unknown fields are ignored)

| Name                 | In   | Type    | Required | Rules                                                                                                                                                                                                                                                                                                                                         |
| -------------------- | ---- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstname`          | body | string  | no       | Saved as `fFirstName`                                                                                                                                                                                                                                                                                                                         |
| `lastname`           | body | string  | no       | Saved as `fLastName`; may be null                                                                                                                                                                                                                                                                                                             |
| `name`               | body | string  | no       | The display name, saved as `fName`. Nothing keeps it in step with `firstname` and `lastname`                                                                                                                                                                                                                                                  |
| `imageUrl`           | body | string  | no       | Saved as `fImage`; may be null; any string is accepted                                                                                                                                                                                                                                                                                        |
| `language`           | body | string  | no       | May be null. One of `en`, `hy`, `ht`, `da`, `nl`, `fr`, `de`, `el`, `hi`, `hu`, `it`, `lt`, `no`, `pl`, `pt`, `ro`, `ru`, `es`, `sv`, `th`, `tr`, `pt-BR`, `uk`, `mn`, `bg`, `bn` (`SupportedLanguage`) \[[ASK-37](https://github.com/snapfix/docs/blob/main/ASK.md#ask-37-which-languages-should-each-platform-offer)]; saved as `fLanguage` |
| `showAiAgentTooltip` | body | boolean | no       | Saved as `fShowAiAgentTooltip`; `1` and `0` are accepted                                                                                                                                                                                                                                                                                      |

The server sets no length limit and stores names exactly as sent. The web's own name fields stop at 30 characters.

**Response** `200` (no data)

```json
{
  "status": "success",
  "message": "Profile updated successfully.",
  "data": null
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` when a value has the wrong type or `language` isn't a supported code.

**Side effects:**

* Updates the user's row in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).

## DELETE /v1/app/user

Deletes the signed-in user's account. The row is kept and marked deleted, and its first name, username and mobile number change. The mobile apps delete accounts through [`delete_user_account`](#delete-actiondelete_user_account) instead.

* **Auth:** user token with the `fresh` claim, which only a token from sign-in has; a token from a refresh is not fresh. Changes the token's user only.
* **Used by:** web (the profile drawer's delete screen).

**Request:** none.

**Response** `200` (no data)

```json
{
  "status": "success",
  "message": "User deleted successfully.",
  "data": null
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `406` "Fresh access token required" when the token isn't fresh.

**Side effects:**

* Changes the user's row in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md):
  * `fFirstName` gets "DEL -" in front of the first name.
  * `fUsername` becomes `del-$-$-$-`, the time in milliseconds, `-$-$-$-` and the old username. Without an old username it is only the prefix and the time.
  * When the user has a country code, `-$-$-$-`, the country code, `-$-$-$-` and the mobile number are added to `fUsername`, and `fCountryCode` and `fMobile` are cleared.
* Marks the row deleted (`fDeleted`).
* Keeps the rest of the row: the display name (`fName`), last name, photo, address and notes. The old username and mobile number stay in the new `fUsername` \[[ASK-25](https://github.com/snapfix/docs/blob/main/ASK.md#ask-25-what-should-deleting-a-profile-remove)]. Some screens show deleted users as "Del -".
* Changes no other table: memberships, tasks and chat lines that point at the user stay as they are \[[ASK-25](https://github.com/snapfix/docs/blob/main/ASK.md#ask-25-what-should-deleting-a-profile-remove)].

## GET /v1/app/user/gdpr

Returns the user's three GDPR consent choices. **No caller** \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)].

* **Auth:** user token. Returns the token's user only.
* **Response** `200`: `data` has `receiveAccountUpdates`, `receiveGroupTaskUpdates` and `receiveProductFeatureUpdates`, each `0` or `1`, from the user's newest row in [`tPri_Log_UserGdpr`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usergdpr.md) by `fServerTs`. All three are `0` when the user has no row.

## POST /v1/app/user/gdpr

Saves the user's three GDPR consent choices and returns them in the shape of the [GET](#get-v1appusergdpr). **No caller** \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)].

* **Auth:** user token. Changes the token's user only.
* **Request** (JSON): `receiveAccountUpdates`, `receiveGroupTaskUpdates` and `receiveProductFeatureUpdates`, each required, `0` or `1`; otherwise `422`.
* **Side effects:** updates the user's row in [`tPri_Log_UserGdpr`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usergdpr.md), found by user only, or adds one; earlier values are replaced \[[ASK-27](https://github.com/snapfix/docs/blob/main/ASK.md#ask-27-where-do-users-change-their-communication-consent-and-how-should-it-be-stored)].

## GET /v1/app/user/on-call-status

Lists the sites the user belongs to, with the user's on-call status in each. The mobile apps read [`read_on_call_status`](#get-actionread_on_call_status) instead.

* **Auth:** user token. Returns the token's user only.
* **Used by:** web (the profile drawer's on-call screen, cached), snapfix\_ai\_agent (Simon, to answer on-call questions).

**Request:** none.

**Response** `200`: one [on-call status object](#on-call-status-object) per site.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    { "uuid": "45", "name": "Maple Court", "status": 1 },
    { "uuid": "46", "name": "Harbour View", "status": 0 }
  ]
}
```

The sites are the ones the user has a relation row with, plus the ones reached through a live membership of a live group in a live site. Sites where the user's latest relation row is deleted are left out. Unlike the php-apis version, sites that have blocked the user are listed.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `400` "User is not part of any business!" when the user has no group membership.

**Side effects:** none.

## PUT /v1/app/user/on-call-status

Turns the user's on-call status on or off for one site or several at once (the "all accounts" toggle).

* **Auth:** user token. Changes the token's user only. Sites the user doesn't belong to (by the same rule as the GET) are dropped from the request without an error.
* **Used by:** web (the profile drawer's toggle), iOS and Android (the profile's all-accounts toggle), snapfix\_ai\_agent (Simon, opting the user in or out).

**Request** (JSON)

| Name          | In   | Type             | Required       | Rules                                                     |
| ------------- | ---- | ---------------- | -------------- | --------------------------------------------------------- |
| `parentUuid`  | body | string           | one of the two | One site; merged into `parentUuids`                       |
| `parentUuids` | body | array of strings | one of the two | Several sites; duplicates are removed                     |
| `status`      | body | integer          | yes            | `0` (off) or `1` (on), applied to every site that is kept |

**Response** `200` (no data)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": null
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `400` "The provided account IDs doesn't belong to the current user" when none of the sites belongs to the user; `422` when no site or no status is sent, or `status` isn't `0` or `1`.

**Side effects:**

* For each site the user belongs to: when the user has no relation row there that isn't blocked, adds a [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) row with `on_call` set to `status` and the type `normal`. Otherwise it sets `on_call` on the user's latest relation row. For a site that has blocked the user, this adds a new row that isn't blocked.
* Sends no push.

## GET /v1/app/user/preferences

Returns one saved preference of the user for a site. Without a `key`, the preference is the feed filter, `feed.filter`. The web also stores the housekeeping timeline scale, `housekeeping.timeline.scale`.

* **Auth:** user token. The user needs a relation row with the site that isn't deleted, as any member has; a blocked row still counts.
* **Used by:** web (the feed filter and the housekeeping timeline), iOS (restoring the feed filter), Android (restoring the feed filter; it sends no `key`, so it always gets `feed.filter`).

**Request** (query; the same names in a body also work)

| Name         | In    | Type   | Required | Rules                                                                                            |
| ------------ | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `parentUuid` | query | string | yes      | The site                                                                                         |
| `key`        | query | string | no       | Up to 64 characters; default `feed.filter`                                                       |
| `scope`      | query | string | no       | Up to 36 characters; default `feed`. Used only when nothing is saved: the lookup is by key alone |

**Response** `200`: a [preference object](#preference-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "123",
    "key": "feed.filter",
    "scope": "feed",
    "value": { "colors": ["red"] },
    "modifiedTs": 1794387600000
  }
}
```

When nothing is saved for the key, the response has `uuid` `null`, the requested `key` and `scope`, `value` `{}` and `modifiedTs` `null`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" when the user has no relation row with the site; `422` when `parentUuid` is missing.

**Side effects:** none.

## PUT /v1/app/user/preferences

Saves one preference of the user for a site. It creates the preference, or replaces the value of the existing one for that key.

* **Auth:** user token. Any member of the site, as for the GET.
* **Used by:** web (feed filter, housekeeping timeline scale), iOS (feed filter, without waiting for the answer), Android (feed filter, retried when offline).

**Request** (JSON)

| Name         | In   | Type            | Required | Rules                                                                                                                                                           |
| ------------ | ---- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid` | body | string          | yes      | The site                                                                                                                                                        |
| `key`        | body | string          | yes      | Up to 64 characters; `feed.filter` or `housekeeping.timeline.scale` in use                                                                                      |
| `scope`      | body | string          | no       | Up to 36 characters; default `feed`. Set only when the row is created                                                                                           |
| `value`      | body | object or array | yes      | Stored as sent; the code sets no size limit. The feed filter holds colours, task types, assignees, tags and sort order; the timeline scale holds `scaleMinutes` |

Other fields are ignored, such as `updateFilter` (web, iOS) and `uuid` and `modifiedTs` (Android).

**Response** `200`: the saved [preference object](#preference-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `403` "Access denied" when the user has no relation row with the site; `422` when a field is missing or too long, or `value` isn't an object or a list.

**Side effects:**

* Creates or updates the row in `tPri_UserPreference` for the user, the site and the key. An existing row keeps its scope. The staging schema has no `tPri_UserPreference` table.

## DELETE ?action=delete\_user\_account

Deletes the signed-in user's account, as the mobile apps do. The change is the same as in [DELETE /v1/app/user](#delete-v1appuser).

* **Auth:** the user's Bearer token. The user comes from the token's `identity` (or `sub`) claim; the token must not be expired and must have the `fresh` claim. The action decodes the payload without checking the signature; only the dispatcher checks it, when `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. A token with the wrong number of parts doesn't stop the action at that check: the error comes from a later step.
* **Used by:** iOS (the delete-profile screen) and Android (the delete-profile dialog). Both send `DELETE`; the dispatcher accepts any method.

**Request:** none.

**Response** `200`

```json
{
  "result": true,
  "message": "account deleted successfully",
  "serverTs": 1794387595000
}
```

**Errors:** `406` "Fresh access token required" when the token isn't fresh (php-apis @ aee9175122, `html/api/snapfix/index.php:4357-4369`). Other failures answer `200` with `result` `false` and the reason in `message`: "invalid access" (no `Authorization` header), "invalid token" (the payload doesn't decode), "access token expired", "user account got deleted already", "error in deleting user account".

**Side effects:**

* Changes the user's row in [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) as in [DELETE /v1/app/user](#delete-v1appuser), and sets the token's user as `uuid_tUser_ModifiedBy`.

## GET ?action=read\_on\_call\_status

Lists the signed-in user's sites with the user's on-call status in each: the mobile version of [GET /v1/app/user/on-call-status](#get-v1appuseron-call-status). Unlike that one, it leaves out sites that have blocked the user, and sites blocked for the caller's device.

* **Auth:** the user's Bearer token. The user comes from the token's payload, with the same signature rule as in [delete\_user\_account](#delete-actiondelete_user_account).
* **Used by:** iOS (the site list's on-call badges) and Android (the profile's on-call switches). Both send `GET`.

**Request:** none. A `device-id` (or `device_id`) header names the device; sites blocked for it in [`tPri_ParentDevice`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentdevice.md) are left out.

**Response** `200`: one [on-call status object (php-apis)](#on-call-status-object-php-apis) per site.

```json
{
  "result": true,
  "message": "success",
  "data": [
    { "parent_uuid": "45", "parent_name": "Maple Court", "on_call_status": 1 }
  ],
  "serverTs": 1794387595000
}
```

A site is listed when the user has a live membership of a live group in it, or, for a site that isn't deleted, when the user is its admin or a user of a multi-site that holds it. Sites blocked for the device, or blocked on one of the user's [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) rows, are left out.

**Errors:** `200` with `result` `false` and the reason in `message`: "invalid access!" when no user comes from the token; "invalid user" when the user doesn't exist or is deleted; "user is not part of any business!"; "no business found!" when no site is left.

**Side effects:** none.

## POST ?action=save\_pri\_log\_usergdpr

Saves the GDPR consent rows that the mobile apps keep locally and upload in their sync.

* **Auth:** the user's Bearer token, checked by the dispatcher when `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. Each row names its own user in `uuid_tUser`, and nothing compares it with the token.
* **Used by:** iOS and Android (background sync). Both send `POST` with a JSON body.

**Request** (JSON)

| Name          | In   | Type  | Required | Rules                                                                                                                                                                                                                                                                                                                                |
| ------------- | ---- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `insert_data` | body | array | yes      | The rows. Each row has the columns of [`tPri_Log_UserGdpr`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usergdpr.md): `uuid`, `uuid_tUser`, `fReceiveAccountUpdates`, `fReceiveGroupTaskUpdates`, `fReceiveProductFeatureUpdates`, `fDeleted`, `fCreatedTs`, `uuid_tUser_CreatedBy`. Values are stored as sent |

**Response** `200`: a [save result object](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

```json
{
  "result": true,
  "message": "Please find the processed record count",
  "total_record_count": 1,
  "inserted_record_count": 1,
  "updated_record_count": 0,
  "insert_failed_record_count": 0,
  "update_failed_record_count": 0,
  "serverTs": 1794387595000
}
```

When `LEGACY_QUEUE_SUPPORT` is on, every row is counted as inserted. Otherwise the counts come from the save, and `result` is `false` when any row failed \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

**Errors:** an empty body answers `{"success": "0", "message": "Data cannot be blank!"}`. A body without `insert_data` answers `200` with `result` `false` and "something went wrong" when `LEGACY_QUEUE_SUPPORT` is on; otherwise the save fails with a PHP error instead of a JSON answer.

**Side effects:**

* Without the legacy queue, writes the rows to [`tPri_Log_UserGdpr`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usergdpr.md): a row whose `uuid` exists is updated, any other row is added. Foreign key checks are off for this table (php-apis @ aee9175122, `htmlphp/api/snapfix/class/class.functions.php:760-768`).
* With `LEGACY_QUEUE_SUPPORT` on, gives each row without a `uuid` a new one and queues the rows, which are written after the response \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## POST ?action=update\_on\_call\_status

Turns the user's on-call status on or off for one site: the mobile single toggle. It answers with the same list as [read\_on\_call\_status](#get-actionread_on_call_status). The bulk toggle uses [PUT /v1/app/user/on-call-status](#put-v1appuseron-call-status).

* **Auth:** the user's Bearer token. The user comes from the token's payload, with the same signature rule as in [delete\_user\_account](#delete-actiondelete_user_account).
* **Used by:** iOS (the profile and the settings on-call switches) and Android (the profile's on-call switches).

**Request** (form fields, not JSON)

| Name          | In   | Type    | Required | Rules                      |
| ------------- | ---- | ------- | -------- | -------------------------- |
| `parent_uuid` | body | string  | yes      | A site the user belongs to |
| `status`      | body | integer | yes      | `0` or `1`                 |

The action reads `$_POST` (php-apis @ aee9175122, `html/api/snapfix/index.php:1293-1300`), which a JSON body doesn't fill: a JSON body answers "Data cannot be blank!".

**Response** `200`: the same as [read\_on\_call\_status](#get-actionread_on_call_status), after the change.

**Errors:** `200` with `result` `false` and the reason in `message`:

* "Data cannot be blank!" when no form field is sent; "parent\_uuid, status must be mentioned in the request!" (the missing names) when a field is missing.
* "invalid status!" when `status` isn't `0` or `1`.
* "invalid access!", "invalid user", "user is not part of any business!" and "no business found!", as in [read\_on\_call\_status](#get-actionread_on_call_status); "invalid parent" when the site doesn't exist or is deleted.
* "invalid parent!" when the site isn't one the user belongs to through a live group membership or as its admin.
* "You are not enabled for ON CALL yet for the mentioned business" when `status` is `0` and the user has no row for the site.
* "Please contact your business admin to enable your account for using this feature!" when the user's latest row for the site is deleted.
* "Your on call status set to be 'enabled' already!" or "Your on call status set to be 'disabled' already!" when nothing would change. iOS treats these two as success.
* "error while updating on call status" when the new row can't be added.

**Side effects:**

* Adds a row to [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) with `on_call` `1` and the type `normal` when `status` is `1` and the user has no row for the site. Otherwise it sets `on_call` on the user's latest row for the site. This path doesn't check `blocked`.

## User object

The profile that [GET /v1/app/user](#get-v1appuser) returns.

| Field                | Type            | Meaning                                                                                                                                                     |
| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`               | string          | The user's ID                                                                                                                                               |
| `username`           | string          | The sign-in name (`fUsername`), an email address; after a deletion, the `del-$-$-$-…` value                                                                 |
| `name`               | string          | The display name (`fName`)                                                                                                                                  |
| `firstname`          | string or null  | The first name                                                                                                                                              |
| `lastname`           | string or null  | The last name                                                                                                                                               |
| `countryCode`        | integer or null | The country code of the mobile number                                                                                                                       |
| `mobile`             | integer or null | The mobile number                                                                                                                                           |
| `image`              | string or null  | The photo URL                                                                                                                                               |
| `address`            | string or null  | The address                                                                                                                                                 |
| `language`           | string or null  | The language code, such as `en`                                                                                                                             |
| `emailVerified`      | integer         | `1` when the email address is verified, otherwise `0`                                                                                                       |
| `mobileVerified`     | integer         | `1` when the mobile number is verified, otherwise `0`                                                                                                       |
| `notes`              | string or null  | The user's `fNotes`, which staff set in the admin API \[[ASK-26](https://github.com/snapfix/docs/blob/main/ASK.md#ask-26-should-users-see-their-own-notes)] |
| `showAiAgentTooltip` | integer         | `1` to show the Simon tooltip, otherwise `0`                                                                                                                |
| `userType`           | string          | `Admin` or `User`; always `User` in [GET /v1/app/user](#get-v1appuser)                                                                                      |
| `userParentDeleted`  | integer or null | `null` in [GET /v1/app/user](#get-v1appuser)                                                                                                                |

The same object serves the admin API, where staff callers get more fields: the staff username, origin, created and modified times, and the user's group memberships.

## On-call status object

One site's on-call state for the user, from [GET /v1/app/user/on-call-status](#get-v1appuseron-call-status).

| Field    | Type    | Meaning                                                                                                                                                             |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`   | string  | The site's ID                                                                                                                                                       |
| `name`   | string  | The site's name                                                                                                                                                     |
| `status` | integer | `1` when the user is on call at the site, otherwise `0`; `0` also when the user has no live relation row there. Read from the user's most recently changed live row |

## On-call status object (php-apis)

One site's on-call state for the user, from [read\_on\_call\_status](#get-actionread_on_call_status) and [update\_on\_call\_status](#post-actionupdate_on_call_status).

| Field            | Type    | Meaning                                                                             |
| ---------------- | ------- | ----------------------------------------------------------------------------------- |
| `parent_uuid`    | string  | The site's ID                                                                       |
| `parent_name`    | string  | The site's name                                                                     |
| `on_call_status` | integer | `1` when the user is on call there, otherwise `0`; `0` also when no value is stored |

## Preference object

One saved preference of the user for a site, from [GET](#get-v1appuserpreferences) and [PUT /v1/app/user/preferences](#put-v1appuserpreferences).

| Field        | Type            | Meaning                                                                           |
| ------------ | --------------- | --------------------------------------------------------------------------------- |
| `uuid`       | string or null  | The preference's ID; `null` when nothing is saved                                 |
| `key`        | string          | Such as `feed.filter` or `housekeeping.timeline.scale`; the server stores any key |
| `scope`      | string          | Such as `feed` or `housekeeping`                                                  |
| `value`      | object or array | The saved JSON; `{}` when nothing is saved                                        |
| `modifiedTs` | integer or null | The last save, in milliseconds since the epoch; `null` when nothing is saved      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/engineering-reference/api/account.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
