# Store — Data API Docs

**App ID:** `434`
**Version UUID:** `ced1fb5b-c6a4-4305-b85d-3c263d9d618e`
**Workflow UUID:** `2f827d27-b7a4-4ed9-9336-879fa46dbcba`

## Base URLs

| Key  | URL                          |
| ---- | ---------------------------- |
| core | `https://sandbox.getzino.in` |
| view | `https://sandbox.getzino.in` |
| user | `https://sandbox.getzino.in` |

All requests require header `Authorization: Bearer <JWT_TOKEN>` (user session JWT from login).

---

## 1. Activity Submission

Calls that create an instance or submit an activity's form. Init = `/start`; subsequent = `/activity`. Upload/OCR fire during fill for file-bearing fields.

### 1.1 Init Activity (init)

Create a new workflow instance and run the init activity.

- **Method:** `POST`
- **Path:** `/app/434/start` (base: core)
- **Content-Type:** `application/json`

**Request body**

```json
{
  "activity_id": "8626a77f-9e70-448e-8ac9-2c51eae5015b",
  "data": {
    "area_2": "string_value",
    "business_name_2": "string_value",
    "complete_address_2": "string_value",
    "distributor_email_2": "user@example.com",
    "distributor_name_2": "option_value",
    "distributor_owner_name_2": "string_value",
    "distributor_phone_number_2": {
      "dial_code": "+1",
      "phone": "2345678901",
      "phone_with_dial_code": "+12345678901"
    },
    "email_2": "user@example.com",
    "notes_2": "string_value",
    "owner_name_2": "string_value",
    "phone_number_2": {
      "dial_code": "+1",
      "phone": "2345678901",
      "phone_with_dial_code": "+12345678901"
    },
    "pin_code_2": 123,
    "potential_2": [
      { "product_category_1": "option_value", "quantity_1": 123 }
    ],
    "route_code_2": "option_value",
    "route_name_2": "option_value",
    "store_image_2": "<IMAGE_UPLOAD>",
    "store_location_2": "string_value",
    "sub_route_2": "option_value"
  },
  "version": 1,
  "workflow_uuid": "2f827d27-b7a4-4ed9-9336-879fa46dbcba"
}
```

**Request fields**

| Key                        | Type        | Required | Note                             |
| -------------------------- | ----------- | -------- | -------------------------------- |
| workflow_uuid              | string      | ✅       | Clone-portable workflow UID.     |
| activity_id                | string      | ✅       | The init activity UID.           |
| version                    | int         | ❌       | Deployed workflow version.       |
| data                       | object      | ❌       | Field values keyed by field id.  |
| business_name_2            | text        | ❌       | "Business Name" (text)           |
| area_2                     | text        | ❌       | "Area" (text)                    |
| complete_address_2         | longtext    | ❌       | "Complete Address" (longtext)    |
| pin_code_2                 | number      | ❌       | "PIN Code" (number)              |
| owner_name_2               | text        | ❌       | "Owner Name" (text)              |
| phone_number_2             | phone       | ❌       | "Phone Number" (phone)           |
| email_2                    | email       | ❌       | "Email" (email)                  |
| store_location_2           | geolocation | ❌       | "Store Location" (geolocation)   |
| store_image_2              | image       | ❌       | "Store Image" (image)            |
| route_name_2               | select      | ❌       | "Route Name" (select)            |
| route_code_2               | select      | ❌       | "Route Code" (select)            |
| sub_route_2                | select      | ❌       | "Sub Route" (select)             |
| distributor_name_2         | select      | ❌       | "Distributor Name" (select)      |
| distributor_owner_name_2   | text        | ❌       | "Distributor Owner Name" (text)  |
| distributor_email_2        | email       | ❌       | "Distributor Email" (email)      |
| distributor_phone_number_2 | phone       | ❌       | "Distributor Phone Number" (phone) |
| notes_2                    | longtext    | ❌       | "Notes" (longtext)               |
| potential_2                | grid        | ❌       | "Potential" (grid)               |

### 1.2 Edit Store

Advance an existing instance through this activity (normal submission).

- **Method:** `POST`
- **Path:** `/app/434/activity` (base: core)
- **Content-Type:** `application/json`

**Request body**

```json
{
  "activity_id": "87647fae-3b07-445f-9615-21881b163276",
  "data": {
    "area_3": "string_value",
    "business_name_3": "string_value",
    "complete_address_3": "string_value",
    "distributor_email_3": "user@example.com",
    "distributor_name_3": "option_value",
    "distributor_owner_name_3": "string_value",
    "distributor_phone_number_3": {
      "dial_code": "+1",
      "phone": "2345678901",
      "phone_with_dial_code": "+12345678901"
    },
    "email_3": "user@example.com",
    "notes_3": "string_value",
    "owner_name_3": "string_value",
    "phone_number_3": {
      "dial_code": "+1",
      "phone": "2345678901",
      "phone_with_dial_code": "+12345678901"
    },
    "pin_code_3": 123,
    "potential_3": [
      { "col_1": "option_value", "col_2": 123 }
    ],
    "route_code_3": "option_value",
    "route_name_3": "option_value",
    "store_image_3": "<IMAGE_UPLOAD>",
    "store_location_3": "string_value",
    "sub_route_3": "option_value"
  },
  "instance_id": "<INSTANCE_ID>",
  "workflow_uuid": "2f827d27-b7a4-4ed9-9336-879fa46dbcba"
}
```

**Request fields**

| Key                        | Type        | Required | Note                             |
| -------------------------- | ----------- | -------- | -------------------------------- |
| workflow_uuid              | string      | ✅       | Clone-portable workflow UID.     |
| activity_id                | string      | ✅       | This activity's UID.             |
| instance_id                | int64       | ✅       | Target instance (runtime value). |
| data                       | object      | ❌       | Field values keyed by field id.  |
| business_name_3            | text        | ❌       | "Business Name" (text)           |
| area_3                     | text        | ❌       | "Area" (text)                    |
| complete_address_3         | longtext    | ❌       | "Complete Address" (longtext)    |
| pin_code_3                 | number      | ❌       | "PIN Code" (number)              |
| owner_name_3               | text        | ❌       | "Owner Name" (text)              |
| phone_number_3             | phone       | ❌       | "Phone Number" (phone)           |
| email_3                    | email       | ❌       | "Email" (email)                  |
| store_location_3           | geolocation | ❌       | "Store Location" (geolocation)   |
| store_image_3              | image       | ❌       | "Store Image" (image)            |
| route_name_3               | select      | ❌       | "Route Name" (select)            |
| route_code_3               | select      | ❌       | "Route Code" (select)            |
| sub_route_3                | select      | ❌       | "Sub Route" (select)             |
| distributor_name_3         | select      | ❌       | "Distributor Name" (select)      |
| distributor_owner_name_3   | text        | ❌       | "Distributor Owner Name" (text)  |
| distributor_email_3        | email       | ❌       | "Distributor Email" (email)      |
| distributor_phone_number_3 | phone       | ❌       | "Distributor Phone Number" (phone) |
| notes_3                    | longtext    | ❌       | "Notes" (longtext)               |
| potential_3                | grid        | ❌       | "Potential" (grid)               |

### 1.3 Upload file

Upload a file/image during form fill; returns `blob_path` that replaces the File in the submit payload.

- **Method:** `POST`
- **Path:** `/app/434/upload` (base: core)
- **Content-Type:** `multipart/form-data` (browser sets the boundary automatically)

**Form fields**

| Key           | Type   | Required | Note                                        |
| ------------- | ------ | -------- | ------------------------------------------- |
| file          | binary | ✅       | The file contents.                          |
| workflow_uuid | string | ✅       | Fixed: `2f827d27-b7a4-4ed9-9336-879fa46dbcba`. |
| activity_id   | string | ✅       |                                             |
| field_id      | string | ✅       |                                             |
| column_id     | string | ❌       | Only for grid-cell file columns.            |
| version_uuid  | string | ❌       |                                             |
| instance_id   | int64  | ❌       | Runtime value when editing an instance.     |

**Response body**

```json
{
  "blob_path": "12/a1b2c3.png",
  "mime_type": "image/png",
  "original_name": "photo.png",
  "size_bytes": 20480,
  "url": "<STORAGE_URL>"
}
```

| Key           | Type   | Note                                          |
| ------------- | ------ | --------------------------------------------- |
| blob_path     | string | Storage path that replaces the File in `data[field_id]`. |
| original_name | string |                                               |
| mime_type     | string |                                               |
| size_bytes    | int64  |                                               |
| url           | string |                                               |

### Common submission response

Applies to Init Activity and Edit Store.

```json
{
  "data": {},
  "instance_id": 1024,
  "message": "Activity completed successfully",
  "status_code": 200,
  "success": true
}
```

| Key         | Type   | Note                                                            |
| ----------- | ------ | --------------------------------------------------------------- |
| success     | bool   | Whether the activity ran.                                       |
| status_code | int    | HTTP status; mirrors a Response node if the trigger graph has one. |
| message     | string | Human-readable result; from a Response node when present.       |
| data        | object | Response-node payload; empty object by default.                 |
| instance_id | int64  | The workflow instance affected/created.                         |

---

## 2. View APIs

Read endpoints that power record/detail/activity/chart views, segregated by source type with each view's UI name.

### 2.1 Record Views

Paginated records + tiles + charts.

- **Method:** `POST`
- **Path:** `/app/434/view/recordview` (base: view)
- **Content-Type:** `application/json`

| UI Name | rv_template_uid                        |
| ------- | -------------------------------------- |
| Store   | `c03b411a-8454-4d8b-8220-00095e92a5de` |

**Request body**

```json
{
  "params": {},
  "preset_alias": "",
  "rv_template_uid": "c03b411a-8454-4d8b-8220-00095e92a5de",
  "search_query": {
    "filters": [],
    "limit": 25,
    "page": 1,
    "search": "",
    "sort_by": "",
    "sort_dir": "desc"
  }
}
```

**Request fields**

| Key                   | Type   | Required | Note                                                        |
| --------------------- | ------ | -------- | ----------------------------------------------------------- |
| rv_template_uid       | string | ✅       | This view's template UID.                                   |
| preset_alias          | string | ❌       | Optional; selects a named prefilter preset on this view.    |
| params                | object | ❌       | Values for declared input params (`${input.<key>}` refs).   |
| search_query.page     | int    | ❌       | 1-based page.                                               |
| search_query.limit    | int    | ❌       | Default 25, max 200.                                        |
| search_query.sort_by  | string | ❌       | `field_key` \| `created_at` \| `updated_at` \| `instance_id`. |
| search_query.sort_dir | string | ❌       | `asc` \| `desc`.                                            |
| search_query.search   | string | ❌       | ILIKE term across searchable fields.                        |
| search_query.filters  | array  | ❌       | `[{field_key, value, value2?, data_type}]`.                 |

**Response body**

```json
{
  "chart_data": [],
  "data": [],
  "pagination": { "limit": 25, "page": 1, "total_records": 0 },
  "tile_values": {}
}
```

| Key         | Type   | Note                            |
| ----------- | ------ | ------------------------------- |
| data        | array  | Companion-table rows.           |
| tile_values | object |                                 |
| chart_data  | array  |                                 |
| pagination  | object | `{page, limit, total_records}`. |

### 2.2 Detail Views

Single-instance detail record.

- **Method:** `GET`
- **Base:** view

| UI Name | Path                                                                         |
| ------- | ---------------------------------------------------------------------------- |
| Store   | `/app/434/view/detailview/af868269-d340-4ea9-9793-5fabe4f6ae27?instance_id=<INSTANCE_ID>` |

**Request fields**

| Key         | Type  | Required | Note                                                              |
| ----------- | ----- | -------- | ----------------------------------------------------------------- |
| instance_id | int64 | ✅       | Query param (runtime value); some DVs use declared extra_params.  |

**Response body**

```json
{ "config": {}, "data": {} }
```

| Key    | Type   | Note              |
| ------ | ------ | ----------------- |
| config | object |                   |
| data   | object | `field_key→value`. |

---

## 3. In-form Activity Helper APIs

Calls a form makes while being filled, segregated per activity: lookup, workflow-lookup, app-user, dataset options, field actions, and peer-instance prefetch.

### Activity: Init Activity (`8626a77f-9e70-448e-8ac9-2c51eae5015b`)

#### Dataset options — Route Name

Dataset-backed options: mount + dependency change.

- **Method:** `POST`
- **Path:** `/app/434/dataset-options` (base: core)
- **Content-Type:** `application/json`

**Request body**

```json
{
  "activity_id": "8626a77f-9e70-448e-8ac9-2c51eae5015b",
  "field_id": "route_name_2",
  "form_data": {},
  "limit": 50,
  "offset": 0,
  "search": "",
  "workflow_uuid": "2f827d27-b7a4-4ed9-9336-879fa46dbcba"
}
```

**Request fields**

| Key           | Type   | Required | Note                                            |
| ------------- | ------ | -------- | ----------------------------------------------- |
| workflow_uuid | string | ✅       | Fixed: `2f827d27-b7a4-4ed9-9336-879fa46dbcba`.  |
| activity_id   | string | ✅       |                                                 |
| field_id      | string | ✅       |                                                 |
| search        | string | ❌       | Search term.                                    |
| limit         | int    | ❌       | Default 50, max 200.                            |
| offset        | int    | ❌       |                                                 |
| filters       | array  | ❌       | `[{column, operator, value}]`.                  |
| form_data     | object | ❌       | Current form values for filter_options.         |
| version_uuid  | string | ❌       | Pins filter_options to the deployed version.    |

**Response body**

```json
{ "limit": 50, "offset": 0, "records": [], "total": 0 }
```

| Key     | Type  | Note                                              |
| ------- | ----- | ------------------------------------------------- |
| records | array | For dataset-options this is `options:[{value,label}]`. |
| total   | int   |                                                   |
| limit   | int   |                                                   |
| offset  | int   |                                                   |