Sync opinions and answers
Copy new opinions and answers into your CRM, data warehouse, or support tool on a schedule.
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 as well.
Opinions and answers are different
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, 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
Pick up everything since the last run
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.
}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 and both ends are inclusive, so store rows by their id to skip any you already have.
Match feedback to your customers
If your website passes an externalUserId to the embedded form, 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
Filters
| Parameter | Default | Values |
|---|---|---|
page, limit | 1, 10 | See 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
Filters
| Parameter | Default | Values |
|---|---|---|
page, limit | 1, 10 | See 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. |
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
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.