---
title: "Start Places Reviews"
method: POST
path: "/api/places/reviews/start"
tags: ["places"]
---

# Start Places Reviews

`POST /api/places/reviews/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/places/reviews/start`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Request body

- PlacesReviewsStartRequest
  - `contract_version` 'places-reviews.v2', required
  - `max_reviews` integer: Maximum newest reviews requested per place.
  - `place_ids` string[], required: Exact case-sensitive physical-place identities.
  - `since` string, nullable: Optional provider lower date bound forwarded as text; whitespace-only values are omitted.

## Response `202`

Successful Response

- PlacesReviewsJobStartResponse: Durable admission receipt for physical-place review collection.
  - `accepted_pricing` AcceptedJobPricing, required: Immutable rule used to rate this job; final usage determines the actual charge.
    - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
    - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
    - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
    - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
    - `unit` string, required: Unit counted by basis, such as a record or execution.
  - `artifact_id` string, required: Immutable result artifact identity.
  - `execution_contract_digest` string, required: Digest of the executable operation contract.
  - `execution_id` string, required: Customer-credit accounting execution identity.
  - `failed` boolean, required: Whether the terminal state is failed.
  - `finished` boolean, required: Whether the job reached a terminal state.
  - `generation_id` string, required: Immutable durable generation identity.
  - `job_id` string, required: Durable job identity.
  - `operation_key` string, required: Stable logical operation identity.
  - `phase` string, required: Current producer phase.
  - `progress_current` integer, required: Completed progress units.
  - `progress_total` integer, required: Total admitted progress units.
  - `request_digest` string, required: Digest of the canonical public request.
  - `result_kind` 'places_reviews', required
  - `rows` PlaceReviewResultRow[], required: Preview rows; empty at admission.
    - `likes_count` integer, nullable, required: Observed helpful-like count, including zero.
    - `place_id` string, required: Physical-place identity this review belongs to.
    - `published_at` string, required: Provider publication timestamp or date representation, or empty.
    - `rating` union, required: Review rating, including zero.
      - integer
      - number
    - `response_text` string, required: Place-owner response text, or empty when unavailable.
    - `review_id` string, required: Provider review identity, or empty if absent.
    - `reviewer_name` string, required: Provider reviewer display name, or empty.
    - `text` string, required: Review text, or empty when unavailable.
  - `semantic_fingerprint` string, required: Digest of request and runtime semantics.
  - `source_digest` string, nullable, required: Managed source digest when supplied.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed', required: Current durable job lifecycle state.
  - `summary` PlacesReviewsJobSummary, required: Known durable progress and terminal fields for a places-review job.
    - `accepted_pricing` union: Immutable customer-credit rule accepted at admission.
      - AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
        - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
        - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
        - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
        - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
        - `unit` string, required: Unit counted by basis, such as a record or execution.
      - UnavailablePlacesJobPricing: Empty historical receipt when a legacy worker had no admitted pricing snapshot.
    - `accounting_started_at` string: UTC accounting admission timestamp.
    - `artifact_id` string: Immutable result artifact identity.
    - `cancel_reason` string: Bounded durable cancellation reason.
    - `cancelled` boolean: Whether processing was durably cancelled.
    - `capability_id` 'places.reviews': Metered capability.
    - `columns` string[]: Committed artifact column order.
    - `committed_batch_count` integer: Durable artifact batches committed.
    - `completeness` 'complete' | 'capped': Complete or caller-capped result.
    - `error` string, nullable: Bounded terminal failure detail, or null after recovery.
    - `execution_contract_digest` string: Digest of the executable contract.
    - `generation_id` string: Immutable result generation identity.
    - `materialized_partition_count` integer: Place partitions used.
    - `materialized_partitions_reused` integer: Place partitions recovered without another provider call.
    - `materializer_activity_timeout_seconds` integer: Maximum worker activity runtime in seconds.
    - `materializer_no_progress_timeout_seconds` integer: Maximum interval without partition progress in seconds.
    - `materializer_operation_id` string: Reviewed materializer operation identity.
    - `materializer_operation_version` string: Reviewed materializer operation version.
    - `max_reviews` integer: Maximum reviews per place.
    - `operation_key` string: Durable logical operation identity.
    - `place_count` integer: Number of admitted physical place ids.
    - `play_id` string, nullable: Owning durable Play identity, or null.
    - `recovery_committed_row_count` integer: Rows retained from the failed generation.
    - `recovery_held_partition_count` integer: Held provider partitions adopted for recovery.
    - `recovery_ordinal` integer: One-based recovery attempt ordinal.
    - `recovery_parent_execution_id` string: Prior failed accounting execution recovered by this run.
    - `replayed` boolean: Whether admission reused the durable generation.
    - `request_digest` string: Digest of the canonical public request.
    - `requested_units` integer: Customer-credit units reserved.
    - `result_kind` 'places_reviews': Terminal result discriminator.
    - `result_manifest_digest` string: Digest of committed rows and coverage.
    - `row_count` integer: Review rows committed to the artifact.
    - `sdk_artifact_binding_version` 1: Artifact SDK binding format version.
    - `semantic_fingerprint` string: Digest of the request semantics.
    - `since` string, nullable: Normalized lower publication-date bound, or null.
    - `source_digest` string: Managed source digest when provided.
    - `start_http_status` integer: HTTP status recorded at admission.
    - `temporal_workflow_id` string: Durable worker workflow identity during recovery.
    - `termination` 'provider_exhausted' | 'request_limit_reached': Whether providers exhausted or a per-place review bound was reached.
    - `tool_kind` 'places_reviews': Worker discriminator.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)