Skip to main content
Read the same current-catalog matching pairs and review statuses as the review workspace with your Public API bearer key. Results include rejected pairs so an uploader can avoid resending them and retain corrected links.
The verified key selects the organization. Do not supply an organization ID. API-key reads remain available independently of whether the matching dashboard is enabled.

​
Select pairs

Rows always use match_id ASC ordering. This endpoint has no public sort parameter or observation-date filter. needs_review means the pair currently requires review; auto means it meets the automatic review policy; approved means it is currently approved; rejected means it has been rejected or manually removed. These are review-workspace statuses. They do not by themselves establish whether a price qualifies for downstream pricing inputs.

​
Read identity and decisions

Each entry in matches contains its stable match_id, current version, rg_item_id and competitor_product_id, plus the item details, competitor, listing URL, relation, method, confidence, manual flag and review metadata. Item details come from the catalog used by the review workspace. Observations and confidence may be null. competitor.id is the registry ID when available. Legacy rows may have a null ID; use the returned canonical competitor.domain to identify and filter those rows. Display names can change and are not identifiers. Decision timestamps include a timezone offset. Missing legacy decision metadata stays unknown; observation time and matched_at do not stand in for decision time. match.is_manual includes explicit human intent such as approving an automatically produced link. It does not prove the original match was created manually. A rematch leaves the old pair readable as rejected and exposes the replacement with its actual link-add metadata. Do not transfer the old pair’s approval to the replacement.

​
Follow pages and reconcile changes

The response includes external_org_id, matches, total, counts, next_cursor and has_more:
  • counts always contains needs_review, auto, approved and rejected, including zeroes. Counts apply the item and competitor filters but omit the selected status filter.
  • total is the count after applying the status filter, or the sum of all four counters when no status is selected.
  • Counts and totals cover the complete selection, independently of the current page and cursor.
  • When has_more is true, request the returned next_cursor. A final page has has_more: false and next_cursor: null.
Keep the same selection while following a cursor:
Process one page at a time and apply pairs idempotently by their identity. Rows and counts are consistent within each response; subsequent pages read current state. This is a live traversal, not an immutable export or an incremental change feed. New or changed pairs that sort before the current cursor appear on a fresh traversal. Start again without cursor when reconciling subsequent reviewer decisions; latest_decided_at is not a synchronization checkpoint. Cursors are bound to the organization, catalog generation and selection. A catalog-generation change returns 409; restart without a cursor. Ordinary review decisions and observation updates do not require a traversal restart. Invalid, altered or mismatched cursors are rejected. Invalid query values return 422; missing, invalid or revoked API keys return 401. An unavailable upstream workspace returns an error rather than an empty success. Existing usage limits apply. For an upload reconciliation example, see Matching uploads.