> 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/reference.md).

# Reference 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/reference.md).
{% endhint %}

Lookup data: the country and currency lists, the translation endpoint, the time zone list, the global values, the server time and the apps' endpoint list. The country, currency and time zone lists are the same for every caller; nothing is filtered by site.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`, `/v1/guest`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `authpy` at `https://z3.snapfix.com`
* **Auth:** api\_php\_live\_v2: `/v1/app` takes a user token (authpy JWT in `Authorization: Bearer`). `/v1/guest` takes the shared guest Basic login, which is also in public web bundles. php-apis: a Bearer user token when `JWT_AUTH_ENABLED` is on, and the shared Basic login when it is off; the actions on the open list (`$openAPIs`, php-apis @ 238ca4414e, `html/api/snapfix/index.php:355`), among them `countries_list_py` and `read_api_end_points_v7`, take the Basic login even when it is on (`:383-457`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. When `SNAPFIX_AUTH_ENABLED` is on, the other actions also want a `Snapfix` header with a token from [`api_token_auth`](https://docs.snapfix.com/engineering-reference/db/tables/api_token_auth.md) (`:356-381`). See [basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins). authpy: the shared Basic login built into the apps. Translations are the only endpoint here where the caller names a site, and the site is only checked to exist.
* **Used by:** web\_app\_v2, iOS, Android, webadmin\_angular, web\_onboarding\_form, web\_payments, snapfix\_ai\_agent (`/v1/app/currencies`), and authpy (`/countries` calls php-apis). 10 of the 19 endpoints have no known caller \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* **Errors:** the envelope and 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 and authpy 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 ([Logging](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)). See [common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects).
* **Tables:** [std\_countries](https://docs.snapfix.com/engineering-reference/db/tables/std_countries.md) and [std\_currencies](https://docs.snapfix.com/engineering-reference/db/tables/std_currencies.md) hold the lists. The global-values actions use [tPub\_GlobalValues](https://docs.snapfix.com/engineering-reference/db/tables/tpub_globalvalues.md), and the endpoint-list actions [tPub\_ApiEndPoint](https://docs.snapfix.com/engineering-reference/db/tables/tpub_apiendpoint.md) and [tPub\_ApiEndPoint\_v7](https://docs.snapfix.com/engineering-reference/db/tables/tpub_apiendpoint_v7.md). Row counts in this doc are from staging (see [infrastructure](https://docs.snapfix.com/engineering-reference/infra.md)).
* **Related:** the staff app's lookups, `GET /v1/admin/countries`, `GET /v1/admin/currencies` and `GET /v1/admin/timezones`, are in the [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md); the frequency list, `GET /v1/app/frequencies`, is in the [Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appfrequencies).

| Method | Path                                                                | Service            | Purpose                                                                               |
| ------ | ------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------- |
| GET    | [`/v1/app/countries`](#get-v1appcountries)                          | api\_php\_live\_v2 | List countries                                                                        |
| GET    | [`/v1/app/currencies`](#get-v1appcurrencies)                        | api\_php\_live\_v2 | List currencies                                                                       |
| POST   | [`/v1/app/translations/batch`](#post-v1apptranslationsbatch)        | api\_php\_live\_v2 | Translate texts in a batch                                                            |
| GET    | `/v1/app/translations/languages`                                    | api\_php\_live\_v2 | List translation languages (no caller)                                                |
| GET    | [`/v1/guest/countries`](#get-v1guestcountries)                      | api\_php\_live\_v2 | List countries                                                                        |
| GET    | [`?action=countries_list`](#get-actioncountries_list)               | php-apis           | List countries                                                                        |
| POST   | [`?action=countries_list_py`](#post-actioncountries_list_py)        | php-apis           | List countries, for authpy's `/countries`                                             |
| ANY    | `?action=create_global_values`                                      | php-apis           | Create global values (no caller)                                                      |
| GET    | [`?action=currencies_list`](#get-actioncurrencies_list)             | php-apis           | List currencies                                                                       |
| ANY    | `?action=get_server_time`                                           | php-apis           | Get the server time (no caller)                                                       |
| ANY    | `?action=modify_global_values`                                      | php-apis           | Change global values (no caller)                                                      |
| ANY    | `?action=read_api_end_points`                                       | php-apis           | Read the API endpoint list (no caller)                                                |
| ANY    | `?action=read_api_end_points_v7`                                    | php-apis           | Read the API endpoint list (v7), for authpy's `/read-api-end-points-v7` (no caller)   |
| ANY    | `?action=read_global_values`                                        | php-apis           | Read global values by UUID, generic table action (no caller)                          |
| GET    | [`?action=read_parent_timezones`](#get-actionread_parent_timezones) | php-apis           | List time zones for sites                                                             |
| ANY    | `?action=read_parent_timezones_v2`                                  | php-apis           | List time zones for sites (v2) (no caller)                                            |
| ANY    | `?action=save_global_values`                                        | php-apis           | Save global values (no caller)                                                        |
| GET    | [`/countries`](#get-countries)                                      | authpy             | List countries, from php-apis                                                         |
| POST   | `/read-api-end-points-v7`                                           | authpy             | Get the endpoint list that the mobile apps once downloaded, from php-apis (no caller) |

Notes on the rows with no caller (each path and action was searched for in every client and service repo):

* `read_global_values`: the iOS function that sends it has no caller (its one call is commented out, ios @ aa31967ac8, `AppUtility.swift:4342`), and Android's `getGlobalValues` is called only from commented-out code (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:464`, `:1398-1404`).
* `read_api_end_points_v7` is reached only through authpy's `/read-api-end-points-v7` (authpy @ 5d5758661c, `app.py:603-613`, `model/feature_php_api.py:123-127`). The only code that posts to that route is `getAllEndPoints` in iOS's `RegisterBusiness` and `RegisterPersonal` screens (ios @ aa31967ac8, `SnapFix/RegisterBusiness.swift:265`, `SnapFix/RegisterPersonal.swift:249`), which sit only in `PageViewControllerRegister`, a screen nothing opens. So neither the route nor the action has a caller.
* `read_api_end_points`, `get_server_time` and `read_parent_timezones_v2` appear only in the apps' endpoint registries and the dispatcher (php-apis @ 238ca4414e, `html/api/snapfix/index.php:3059-3062`, `:3266-3268`, `:1377-1379`). `read_parent_timezones_v2` returns the same list as [`read_parent_timezones`](#get-actionread_parent_timezones).
* The three global-values write actions take no staff check, so any caller who passes the gates in the intro can change the app-wide values in `tPub_GlobalValues` (`html/api/snapfix/index.php:3080-3103`). authpy reads two of those values, `web_gsm_registration_enabled` and `mobile_gsm_registration_enabled`, to decide whether phone-number sign-up is open (authpy @ 5d5758661c, `model/t_log_ip_blocked_v3.py:100-118`, `:169`).
* `read_global_values` reads by UUID, but `tPub_GlobalValues` has only `id`, `fKey` and `fValue` columns ([schema](https://github.com/snapfix/docs/blob/main/spec/db/schema.sql)), so a read by UUID has nothing to match.

## GET /v1/app/countries

Lists every row of `std_countries` for the country pickers. The [site details screen](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md) loads it with the currencies.

* **Auth:** user token. Any signed-in user gets the same list.
* **Used by:** web\_app\_v2 (`CommonService.getCountryList`, web\_app\_v2 @ 0989b8e685, `src/app/services/common/common.service.ts:41-54`; called from `src/app/pages/account-settings/account-settings-account-details/account-settings-account-details.component.ts:162` and `:300-304`).

**Request:** none. The handler reads no `limit` or `offset` and returns every row (249 in staging). The list is in database order, not sorted (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/CountryService.php:13-16`), and names are English whatever `Accept-Language` is.

**Response** `200`: a list of [country objects](#country-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "code": "FR",
      "name": "France",
      "fullName": "French Republic",
      "vatType": "eu_vat"
    },
    {
      "code": "IE",
      "name": "Ireland",
      "fullName": "Ireland",
      "vatType": null
    }
  ]
}
```

The list has duplicate names, and accented names sort last in the web app.

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

**Side effects:** none.

## GET /v1/app/currencies

Lists every row of `std_currencies`, not only the supported ones. `snapfixSupported` marks the currencies Snapfix supports, which is 6 of the 179 rows in staging; clients filter on it themselves.

* **Auth:** user token. Any signed-in user gets the same list.
* **Used by:**
  * web\_app\_v2 (`CommonService.getCurrencyList`, `src/app/services/common/common.service.ts:56-69`; called from `account-settings-account-details.component.ts:163` and `:306-309`, `src/app/pages/task/task-time-cost/task-time-cost.component.ts:64` and `:144-145`, and `src/app/pages/assets/asset-detail/asset-task-list/asset-task-list.component.ts:86` and `:186-187`).
  * snapfix\_ai\_agent (`CurrenciesApi.supported`, snapfix\_ai\_agent @ e5e18caef5, `src/snapfix/currencies/__init__.py:16-18`, called from `src/agent/tools/resolve.py:232-238`). It keeps only the supported currencies.

**Request:** none. Like the countries list, it has no paging.

**Response** `200`: a list of [currency objects](#currency-object).

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": [
    {
      "code": "EUR",
      "name": "Euro",
      "entity": "EUROPEAN UNION",
      "number": "978",
      "symbol": "€",
      "snapfixSupported": 1
    }
  ]
}
```

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

**Side effects:** none.

## POST /v1/app/translations/batch

Translates up to 30 texts into one language for one site. It answers from the site's cache first, then sends the rest to the translation provider. The same text in one batch is translated once.

* **Auth:** user token. Any signed-in user may send a batch for any site: `parentUuid` is only checked to exist, not that the caller belongs to the site. The server does not check the site's AI translation switch (`fAiLanguageTranslationEnabled`); the web app checks it before it calls (`computeTranslationEnabled()`, web\_app\_v2 @ 0989b8e685, `src/app/services/translation/translation-manager/translation-manager.service.ts:233-234`).
* **Used by:**
  * web\_app\_v2 (`TranslationHttpService.translateBatch`, `src/app/services/translation/translation-http/translation-http.service.ts:22-30`; from `translation-manager.service.ts:207` and `:320`).
  * iOS (ios @ aa31967ac8, `Managers/TranslationManager.swift:254` for one text and `:387` for a batch).
  * Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/TranslationManager.kt:341`, through `repository/TranslationRepository.kt:53-101`). Android can fall back to the test server for translations.
  * Translated text shows on the [chat](https://docs.snapfix.com/how-the-apps-work/screens/chat/conversation.md), [checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md) and [assistant](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md) screens.

**Request** (JSON; api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Requests/v1/Translation/BatchTranslateRequest.php`)

| Name              | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                       |
| ----------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentUuid`      | body | string | yes      | The site. It must exist; the caller's membership is not checked                                                                                                                                                                                                             |
| `targetLanguage`  | body | string | yes      | One of the 26 codes in `SupportedLanguage`, such as `fr` or `pt-BR`; the list is also returned by `GET /v1/app/translations/languages`, which has no caller \[[ASK-37](https://github.com/snapfix/docs/blob/main/ASK.md#ask-37-which-languages-should-each-platform-offer)] |
| `items`           | body | array  | yes      | 1 to 30 items                                                                                                                                                                                                                                                               |
| `items[].id`      | body | string | yes      | Sent back unchanged, so the caller can match each answer                                                                                                                                                                                                                    |
| `items[].text`    | body | string | yes      | Up to 5000 characters                                                                                                                                                                                                                                                       |
| `items[].context` | body | string | no       | Up to 1000 characters; the provider gets it as a hint about the text                                                                                                                                                                                                        |

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "targetLanguage": "fr",
    "items": [
      {
        "id": "item-1",
        "translatedText": "Nettoyage au départ",
        "sourceLanguage": "en",
        "cached": false
      },
      {
        "id": "item-2",
        "translatedText": "Hors service",
        "sourceLanguage": "en",
        "cached": true
      }
    ]
  }
}
```

* The items come back in request order, with their `id`. Two items with the same text get the same answer.
* `sourceLanguage` is the language the provider found. It is `unknown` when the provider call failed or the provider left the item out; then `translatedText` is the original text, and the request still answers `200` (`app/Services/Translation/TranslationService.php:64-93`, `app/Services/Translation/Providers/OpenAiTranslationProvider.php:262-272`). The web app and the apps keep that text as the translation.
* `cached` is `true` when the answer came from the cache.
* The default provider is `dummy` (`config/translation.php:14`), which makes no external call and returns the text with the language in front, such as `[fr] Departure Clean` (`app/Services/Translation/Providers/DummyTranslationProvider.php:24-25`). Which provider runs in production is not in any repo \[[ASK-236](https://github.com/snapfix/docs/blob/main/ASK.md#ask-236-which-translation-provider-and-cache-run-in-production)]. With the `openai` provider, the texts and their context go to OpenAI.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` with the first failed rule's message for a `parentUuid` that does not exist, a `targetLanguage` outside the list, an empty `items` or one with more than 30 entries, a `text` over 5000 characters, or a `context` over 1000 characters. A provider failure is not an error; it gives the `200` answer above.

**Side effects:**

* With the `openai` provider, one [`ai_token_usage`](https://docs.snapfix.com/engineering-reference/db/tables/ai_token_usage.md) row for each provider call that had misses, failed calls included. The row names the site as `uuid_tParent` and the caller as `uuid_tUser`, so another user's requests add to the site's AI usage. The dummy provider and batches answered fully from the cache write no row (`TranslationService.php:107-170`, `:201-216`).
* When a cache driver is set (`TRANSLATION_CACHE_DRIVER`, `null` by default, and never while the provider is `dummy`), fresh answers are kept for 30 days (`TRANSLATION_CACHE_TTL`), per site and language, keyed by the text (`config/translation.php:51-54`, `app/Services/Translation/Cache/TranslationCacheResolver.php:19-40`) \[[ASK-236](https://github.com/snapfix/docs/blob/main/ASK.md#ask-236-which-translation-provider-and-cache-run-in-production)]. Items the provider left out are cached as untranslated text too; the answers of a failed provider call are not cached (`TranslationService.php:70-92`).
* The Laravel request log keeps the texts and contexts.

## GET /v1/guest/countries

The same list as [`/v1/app/countries`](#get-v1appcountries), for the [setup form](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md), which a person opens from a link without signing in.

* **Auth:** shared guest Basic login. `AuthorizeGuestApi` compares the `Authorization: Basic` user and password with `app.auth_user_guest` and `app.auth_pass_guest` (`config/app.php:289-290`, values not reproduced) and answers `401` with `{"error": "Unauthorized."}` and `WWW-Authenticate: Basic` when they do not match (`app/Http/Middleware/AuthorizeGuestApi.php:21-27`). The login ships in the web bundles, so it identifies the app, not a person.
* **Limits:** the group runs the blacklist, the per-route limiter and the named limits of 60 calls a minute and 1,000 a day per user or IP (`app/Providers/RouteServiceProvider.php:107-117`, `:140-150`).
* **Used by:** web\_onboarding\_form (`OnboardingService.getCountries`, web\_onboarding\_form @ 099b91d4e3, `src/app/services/onboarding/onboarding.service.ts:39-48`; called from `src/app/components/account/account.component.ts:50` and `:95-99`). If the list fails to load, the form still lets the user submit without a country.

**Request:** none.

**Response** `200`: a list of [country objects](#country-object), the same as the signed-in list.

**Errors:** the common errors do not apply, because the route has no user.

* `401` for a wrong or missing login (above).
* `400` from the blacklist middleware for a blocked caller (see [blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).
* `429` from the per-route limiter while throttling is on, and `500` when a named limit is reached.

**Side effects:** none. The request is kept in the Laravel request log.

## GET ?action=countries\_list

Lists the `std_countries` rows for the pickers in the staff app, the iOS app and the web payment pages. The rows carry the Stripe VAT id as `vat_type`.

* **Auth:** the php-apis gates in the intro; this action is not on the open list.
* **Used by:**
  * webadmin\_angular: `AccountService.getCountries` (webadmin\_angular @ db972390b8, `src/app/services/account/account.service.ts:80-88`, `GET`); called from `src/app/pages/account/components/account-modal/account-modal.component.ts:42` and `:141-144`, `src/app/pages/invoices/components/onboarding-url-modal/onboarding-url-modal.component.ts:41` and `:65-68`, `src/app/pages/survey/components/survey-details/survey-details.component.ts:47` and `:96-99`, and `src/app/pages/marketing-popup/components/marketing-popup-modal/marketing-popup-modal.component.ts:63` and `:248-251`. See [staff accounts](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md).
  * iOS: `BusinessListingVC.getCounries` (ios @ aa31967ac8, `SnapFix/BusinessListingVC.swift:151` and `:808-815`), through the registry name `countries_list_v2`, which maps to this action (`APIManagers/ApiEndpointManager.swift:2199-2205`).
  * web\_payments: `CountryService.getCountriesList(false)` sends it as `POST` with an empty JSON body when a site is selected (web\_payments @ 7c2c3ddffd, `src/app/services/country/country.service.ts:22-26`), from `src/app/pages/auth/pay/components/pay-business-detail/pay-business-detail.component.ts:112`. See [payment page](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md).

**Request:** none. The action reads no paging parameters and does the same for `GET` and `POST`.

**Response** `200`: every row, as [country objects](#country-object) in php-apis form (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:21735-21739`).

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "code": "FR",
      "name": "France",
      "full_name": "French Republic",
      "vat_type": "eu_vat"
    }
  ],
  "serverTs": 1700000000000
}
```

The action does not filter on `blacklisted`; no row has it set in staging.

**Errors:** token and login failures come back in the php-apis envelope with `result` `false`; a blocked caller gets the abuse check's answer (see [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses) and [blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)).

**Side effects:** none. The call goes to the request log ([Logs](#reference-api)).

## POST ?action=countries\_list\_py

The same country list, for authpy's [`GET /countries`](#get-countries) proxy.

* **Auth:** the shared Basic login, with no user token, even when `JWT_AUTH_ENABLED` is on: the action is on the open list (`html/api/snapfix/index.php:355`, `:434-457`) \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* **Used by:** authpy `GET /countries` (authpy @ 5d5758661c, `app.py:586-596`, which calls `listCountries` in `model/feature_php_api.py:161-165`).

**Request** (JSON): `SP_FORWARDED_FOR`, which authpy fills with the caller's `X-Forwarded-For` header. The abuse check reads it; the action reads nothing else.

**Response** `200`: the same answer as [`?action=countries_list`](#get-actioncountries_list) (`html/api/snapfix/index.php:2143-2145`).

**Errors:** as [`?action=countries_list`](#get-actioncountries_list).

**Side effects:** none. The call goes to the request log ([Logs](#reference-api)).

## GET ?action=currencies\_list

Lists the `std_currencies` rows for the currency pickers in the staff app, the iOS app and the Android app. The flag comes as stored, `snapfix_supported`.

* **Auth:** the php-apis gates in the intro; this action is not on the open list.
* **Used by:**
  * webadmin\_angular: `PaymentService.getCurrenciesList` (`src/app/services/payment/payment.service.ts:37-45`, `GET`); called from `src/app/pages/paywall/paywall.component.ts:148`, `src/app/pages/credit-card-payment/credit-card-payment.component.ts:33` and `:62-63`, and `src/app/pages/stripe-payment/components/stripe-payment-modal/stripe-payment-modal.component.ts:39` and `:97-98`. See [paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md), [card payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/card-payment.md) and [stripe payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md).
  * iOS: `BusinessListingVC.getCurrencies` (`SnapFix/BusinessListingVC.swift:150` and `:794-805`); the action name is in `APIManagers/APIManager.swift:169`.
  * Android: `BusinessListingActivity.callGetCurrency` (`app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:507` and `:3285-3292`), through `network/ApiService.java:494-496` (`GET`).

**Request:** none.

**Response** `200`: every row, with `code`, `name`, `entity`, `number`, `symbol` and `snapfix_supported` (`0` or `1`) (`htmlphp/api/snapfix/class/class.functions.php:22652-22656`). See [currency object](#currency-object).

```json
{
  "result": true,
  "message": "success",
  "data": [
    {
      "code": "EUR",
      "name": "Euro",
      "entity": "EUROPEAN UNION",
      "number": "978",
      "symbol": "€",
      "snapfix_supported": 1
    }
  ],
  "serverTs": 1700000000000
}
```

**Errors:** as [`?action=countries_list`](#get-actioncountries_list).

**Side effects:** none. The call goes to the request log ([Logs](#reference-api)).

## GET ?action=read\_parent\_timezones

Lists the time zone names that a site can use. The list is PHP's `timezone_identifiers_list()` and is not stored in any table (`htmlphp/api/snapfix/class/class.functions.php:29507-29509`).

* **Auth:** the php-apis gates in the intro; this action is not on the open list.
* **Used by:** webadmin\_angular: `AccountService.getTimezones` (`src/app/services/account/account.service.ts:70-78`, `GET`); called from `src/app/pages/onboard/onboard.component.ts:45` and `:150-153`, `src/app/pages/account/components/account-modal/account-modal.component.ts:41` and `:131-134`, and `src/app/pages/marketing-popup/components/marketing-popup-modal/marketing-popup-modal.component.ts:62` and `:238-241`. See [staff onboard](https://docs.snapfix.com/how-the-apps-work/screens/staff/onboard.md) and [staff accounts](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md).

**Request:** none.

**Response** `200`: `data` is a list of IANA time zone names.

```json
{
  "result": true,
  "message": "success",
  "data": ["Africa/Abidjan", "Africa/Accra", "Europe/Dublin"],
  "serverTs": 1700000000000
}
```

**Errors:** as [`?action=countries_list`](#get-actioncountries_list).

**Side effects:** none. The call goes to the request log ([Logs](#reference-api)).

## GET /countries

The country list for web\_payments' pay page when no site is picked (a guest checkout). authpy answers it from php-apis' [`countries_list_py`](#post-actioncountries_list_py) and passes the answer through unchanged.

* **Auth:** the shared Basic login, checked by `verifyBasicAuth()` (authpy @ 5d5758661c, `app.py:586-590`). authpy calls its IP-block check but ignores the result, so a blocked caller still gets the list (`app.py:591`).
* **Used by:** web\_payments (`CountryService.getCountriesList(true)`, `src/app/services/country/country.service.ts:27-30`; called from `pay-business-detail.component.ts:112` when no site is selected). See [payment page](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md).

**Request:** none.

**Response** `200`: the php-apis answer: `result`, `message`, `data` ([country objects](#country-object) in php-apis form) and `serverTs`, as in [`?action=countries_list`](#get-actioncountries_list).

**Errors:** a missing or wrong login gets `200` with `result` `false` and "invalid authentication" (`app.py:595-596`, `config/constant.py:137`), not a `401`. php-apis errors are passed through.

**Side effects:** the php-apis call above, and the IP check's log.

## Country object

One row of [std\_countries](https://docs.snapfix.com/engineering-reference/db/tables/std_countries.md) (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Resources/v1/CountryResource.php`).

| Field (`/v1/app`, `/v1/guest`) | Field (php-apis, authpy) | Type           | Meaning                                                                 |
| ------------------------------ | ------------------------ | -------------- | ----------------------------------------------------------------------- |
| `code`                         | `code`                   | string         | Two-letter ISO 3166-1 code, such as `GB`                                |
| `name`                         | `name`                   | string         | English name                                                            |
| `fullName`                     | `full_name`              | string         | English full name                                                       |
| `vatType`                      | `vat_type`               | string or null | The Stripe VAT id (`stripe_vat_enum`), `null` when the country has none |

The objects do not include `blacklisted`, and every row is returned.

## Currency object

One row of [std\_currencies](https://docs.snapfix.com/engineering-reference/db/tables/std_currencies.md) (`app/Http/Resources/v1/CurrencyResource.php`).

| Field (`/v1/app`)  | Field (php-apis)    | Type           | Meaning                                                                     |
| ------------------ | ------------------- | -------------- | --------------------------------------------------------------------------- |
| `code`             | `code`              | string         | Three-letter ISO 4217 code, such as `EUR`                                   |
| `name`             | `name`              | string         | Currency name                                                               |
| `entity`           | `entity`            | string         | The entity that issues the currency                                         |
| `number`           | `number`            | string         | Three-digit ISO 4217 number                                                 |
| `symbol`           | `symbol`            | string or null | The currency symbol                                                         |
| `snapfixSupported` | `snapfix_supported` | integer        | `1` when Snapfix supports the currency, `0` otherwise; no cast to a boolean |


---

# 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/reference.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.
