# Sync opinions and answers

URL: /docs/developers/feedback/sync

Bring what customers say into the tools your team already works in. A scheduled job reads everything created since its last run and writes it wherever you need it. To react within seconds instead, add [webhooks](/docs/developers/feedback/webhooks) as well.

## Opinions and answers are different [#opinions-and-answers-are-different]

### Read both [#read-both]

- **Opinions** are what customers write about their experience, with votes and your replies. Read them with `opinions.list`.
- **Answers** are their replies to [your questions](/docs/developers/questions/create), one row per answer. Read them with `answers.list`.

A customer can answer questions without writing an opinion, so the opinion list never contains every answer. Reading needs `opinions` read and `answers` read, which new API keys include.

## Run a sync job [#run-a-sync-job]

### Pick up everything since the last run [#pick-up-everything-since-the-last-run]

**TypeScript SDK**

```ts
import { opinions } from '@orvelt/business';

export async function syncOpinions(since: number) {
  const startedAt = Date.now();
  for (let page = 1; ; page += 1) {
    const result = await opinions.list({
      projectId: 'PROJECT_ID',
      dateFrom: since,
      sort: 'oldest',
      page,
      limit: 100,
    });
    if (result.error) throw new Error(result.error.message);

    await saveOpinions(result.data.opinions); // Your CRM, warehouse, or support tool.
    if (page >= result.data.pagination.totalPages) break;
  }
  return startedAt; // Save this as `since` for the next run only after every page succeeded.
}
```

**Python SDK**

```python
import os
import time
from orvelt_business import Orvelt

def sync_opinions(since, save_opinions):
    started_at = time.time_ns() // 1_000_000
    with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
        page = client.opinions.list(
            project_id="PROJECT_ID",
            date_from=since,
            sort="oldest",
            limit=100,
        )
        while page is not None:
            save_opinions(page.result.opinions)  # Your CRM, warehouse, or support tool.
            page = page.next()
    return started_at  # Save as `since` only after every page succeeded.
```

Filter tables below use the HTTP API's camelCase. Python uses snake_case, such as `date_from`, `external_user_id`, and `question_id`.

Run the same loop with `answers.list`. Dates are [milliseconds since the epoch](/docs/developers/pagination#filter-by-date) and both ends are inclusive, so store rows by their `id` to skip any you already have.

### Match feedback to your customers [#match-feedback-to-your-customers]

If your website passes an `externalUserId` to the [embedded form](/docs/developers/collect/website-embed), every opinion and answer carries it, and both lists can filter by it exactly. Use it to attach feedback to the right customer or order. It is unverified reference data, never proof of identity, and it never appears publicly.

## `opinions.list` filters [#opinionslist-filters]

### Filters [#filters]

| Parameter | Default | Values |
| --- | --- | --- |
| `page`, `limit` | `1`, `10` | See [pagination](/docs/developers/pagination). |
| `sort` | `newest` | `newest`, `oldest`, `most-upvoted`, or `least-upvoted`. |
| `replyStatus` | `all` | `all`, `replied`, or `unreplied`. |
| `visibility` | `all` | `all`, `public`, or `private`, based on the opinion's `privateAt`. |
| `query` | Empty | Case-insensitive search, up to 200 characters, across the opinion ID and text, external reference, customer name, and store name, caption, city, and state. Not replies or answer text. |
| `dateFrom`, `dateTo` | None | The opinion's `createdAt`. |
| `externalUserId` | None | Exact, case-sensitive match, up to 256 characters. |
| `opinionId` | None | One opinion. |

Returns `{ opinions, pagination }` with only published opinions from submitted responses. Date sorts break ties by ID in the same direction; vote sorts rank by `upvotes` (not `voteTotal`), then newest `createdAt`, then descending ID.

## `answers.list` filters [#answerslist-filters]

### Filters [#filters-1]

| Parameter | Default | Values |
| --- | --- | --- |
| `page`, `limit` | `1`, `10` | See [pagination](/docs/developers/pagination). |
| `sort` | `newest` | `newest` or `oldest`, by the answer's `createdAt`, with IDs breaking ties. |
| `questionId` | None | Answers to one question, using its ID from [`questions.list`](/docs/developers/questions/results#see-your-question-library). |
| `responseVisibility` | `all` | `all`, `default` (can appear with a public opinion), or `private` (your team only). |
| `query` | Empty | Case-insensitive search, up to 200 characters, across answer, response, and question IDs, external reference, question and answer text, tags, and selected options. |
| `dateFrom`, `dateTo` | None | The answer's own `createdAt`, not its response's. |
| `responseId` | None | Answers from one response. |
| `externalUserId` | None | Exact, case-sensitive match, up to 256 characters. |

Returns `{ answers, pagination }` with submitted answers from submitted responses. Each answer includes `responseId`, the question text, the answer, `selectedOptions` (option text), and `externalUserId`. `default` is a setting, not proof that a public opinion exists. Both lists trim `externalUserId` before matching and ignore an empty one.

## Export a CSV instead [#export-a-csv-instead]

### Session-only exports [#session-only-exports]

Orvelt Business exports opinions, answers, and responses as CSV through session-only operations, which API keys and the SDK cannot call. Each takes its list's filters and sort, exports every matching row, and returns `{ filename, csv }`.

| Session operation | Contract path (GET) |
| --- | --- |
| `project.responses.export` | `/project/{projectId}/responses/export` |
| `project.answers.export` | `/project/{projectId}/answers/export` |
| `project.opinions.export` | `/project/{projectId}/opinions/export` |

These paths are served only to the first-party oRPC client, not the public REST API. Answer and opinion exports need Outcomes read access. The session-only `project.responses.list` and `project.responses.export` need Delivery read access, filter by `query`, `externalUserId`, `responseId`, `dateFrom`, and `dateTo` (the response's `createdAt`), sort by `newest` or `oldest`, and search response and answer IDs, question and answer text, tags, selected options, external reference, customer name and ID, and store details, but not opinion text. Response exports have one row per submitted response, including those with no opinion or answers, and never fall back to answers. Response counts need Outcomes read access and count started responses. The removed `responses.list({ resource, format: 'csv' })` behavior is replaced by these export operations.