Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(warehouse-sources): add quo contact notes table (#119542)

Tom Owers6ba1f8d33f77
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index 4a5724c2fc24..1a4d3a4c64da 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -9966,6 +9966,7 @@ Diffed against: <https://www.quo.com/docs/mdx/api-reference/openapi.md>
- [ ] `Call transcriptions (GET /v1/call-transcripts/{id})` — analyze customer requests and call content alongside existing call records (medium)
- [ ] `Call recordings (GET /v1/call-recordings/{callId})` — measure recording availability, segment duration, and processing failures for calls (medium)
- [ ] `Call voicemails (GET /v1/call-voicemails/{callId})` — analyze missed-call messages and voicemail processing outcomes (medium)
+- [x] `Contact notes (GET /contacts/{contactId}/notes)` — the notes your team keeps on each contact, joinable to the contacts table (medium)
Note: The official v1 OpenAPI specification was fetched with curl and its GET operations were compared with both source version maps. Call artifacts need requests for each call, and transcripts require a Business or Scale plan. The dated calls table already requests summaries, so summaries are excluded as a general gap. Webhooks and write operations are excluded.
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py
index 320a0d2e1284..32b1261fa452 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py
@@ -61,6 +61,19 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"type": "The data type of the custom contact field.",
},
},
+ "contact_notes": {
+ "description": "The notes your team left on contacts in your Quo workspace.",
+ "docs_url": "https://www.quo.com/docs/2026-03-30/contact-notes/list-notes-for-a-contact",
+ "columns": {
+ "id": "The unique identifier of the note.",
+ "contactId": "The unique identifier of the contact the note belongs to.",
+ "text": "The body of the note.",
+ "media": "The attachments on the note, each with a URL, MIME type and file name.",
+ "actorId": "The unique identifier of the user who wrote the note.",
+ "createdAt": "Timestamp of note creation, in ISO 8601 format.",
+ "updatedAt": "Timestamp of last note update, in ISO 8601 format.",
+ },
+ },
"conversations": {
"description": "The call and message conversations in your Quo workspace, one per phone number and participant set.",
"docs_url": "https://www.quo.com/docs/mdx/api-reference/conversations/list-conversations",
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py
index 7176398a3544..3edbc2d8cb86 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py
@@ -1,12 +1,16 @@
from collections.abc import Callable, Iterable, Iterator
from typing import Any, Optional
+from urllib.parse import quote
from requests import Session
from posthog.dataclasses import frozen
from products.warehouse_sources.backend.temporal.data_imports.sources.common.datetime_utils import parse_datetime_value
-from products.warehouse_sources.backend.temporal.data_imports.sources.common.http import make_tracked_session
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.http import (
+ default_request_timeout,
+ make_tracked_session,
+)
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source import (
RESTAPIConfig,
rest_api_resource,
@@ -20,6 +24,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.sou
from products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponse
from products.warehouse_sources.backend.temporal.data_imports.sources.quo.settings import (
DATED_ENDPOINTS_BY_VERSION,
+ QUO_2026_03_30_ENDPOINTS,
+ QUO_API_VERSION_2026_03_30,
QUO_API_VERSION_HEADER,
QUO_API_VERSION_V1,
QUO_BASE_URL,
@@ -34,6 +40,10 @@ class QuoResumeConfig:
page_token: str
# The dated version the cursor was issued under. None is the v1 wire, which pages with incompatible cursors.
api_version: str | None = None
+ # Contact notes only: the contact whose notes were last yielded, and its next notes page.
+ # A None notes cursor means that contact is done.
+ contact_id: str | None = None
+ notes_cursor: str | None = None
def _to_iso(value: Any) -> Optional[str]:
@@ -150,6 +160,87 @@ def _fan_out_rows(api_key: str, config: QuoEndpointConfig, params: dict[str, Any
)
+def _contact_notes_rows(
+ api_key: str,
+ config: QuoEndpointConfig,
+ resumable_source_manager: ResumableSourceManager[QuoResumeConfig],
+) -> Iterator[list[dict[str, Any]]]:
+ """Fan contact notes out over the dated contacts list.
+
+ Each staged cursor points just past the notes page it is staged with. Full refresh appends a
+ resumed run's rows without a merge, so a resumed run must not read a written note again.
+ """
+ session = make_tracked_session(
+ headers={**_auth_headers(api_key), QUO_API_VERSION_HEADER: QUO_API_VERSION_2026_03_30},
+ redact_values=(api_key,),
+ )
+ contacts = QUO_2026_03_30_ENDPOINTS["contacts"]
+
+ contacts_cursor: Optional[str] = None
+ resume: Optional[QuoResumeConfig] = None
+ if resumable_source_manager.can_resume():
+ saved = resumable_source_manager.load_state()
+ if saved is not None and saved.api_version == QUO_API_VERSION_2026_03_30:
+ resume = saved
+ contacts_cursor = saved.page_token or None
+
+ while True:
+ params: dict[str, Any] = {"limit": contacts.page_size}
+ if contacts_cursor is not None:
+ params["after"] = contacts_cursor
+ response = session.get(f"{QUO_BASE_URL}{contacts.path}", params=params, timeout=default_request_timeout())
+ response.raise_for_status()
+ body = response.json()
+ resumable_source_manager.safe_point()
+
+ contact_ids = [contact["id"] for contact in body.get("data") or [] if contact.get("id")]
+ start = 0
+ notes_cursor: Optional[str] = None
+ # A resume contact missing from the page was deleted, so the page is read from its start.
+ if resume is not None and resume.contact_id in contact_ids:
+ start = contact_ids.index(resume.contact_id)
+ notes_cursor = resume.notes_cursor
+ if notes_cursor is None:
+ start += 1
+ resume = None
+
+ for contact_id in contact_ids[start:]:
+ path = config.path.replace("{contactId}", quote(contact_id, safe=""))
+ while True:
+ notes_params: dict[str, Any] = {"limit": config.page_size}
+ if notes_cursor is not None:
+ notes_params["after"] = notes_cursor
+ notes_response = session.get(
+ f"{QUO_BASE_URL}{path}", params=notes_params, timeout=default_request_timeout()
+ )
+ # A contact deleted after the contacts page was read answers 404; its notes are gone too.
+ if notes_response.status_code == 404:
+ break
+ notes_response.raise_for_status()
+ notes_body = notes_response.json()
+ notes = notes_body.get("data") or []
+ notes_cursor = notes_body.get("nextCursor") or None
+ if notes:
+ resumable_source_manager.save_state(
+ QuoResumeConfig(
+ page_token=contacts_cursor or "",
+ api_version=QUO_API_VERSION_2026_03_30,
+ contact_id=contact_id,
+ notes_cursor=notes_cursor,
+ )
+ )
+ yield [{**note, "contactId": contact_id} for note in notes]
+ else:
+ resumable_source_manager.safe_point()
+ if notes_cursor is None:
+ break
+ notes_cursor = None
+
+ contacts_cursor = body.get("nextCursor")
+ if not contacts_cursor:
+ return
+
+
def _rest_source(
api_key: str,
name: str,
@@ -219,7 +310,7 @@ def _source_response(endpoint: str, config: QuoEndpointConfig, items: Callable[[
return SourceResponse(
name=endpoint,
items=items,
- primary_keys=[config.primary_key],
+ primary_keys=list(config.primary_keys),
# Quo lists return newest-first and the fan-out restarts per conversation, so rows never
# arrive globally ascending. "desc" defers the watermark commit to the end of a
# successful sync instead of checkpointing it mid-run.
@@ -247,6 +338,11 @@ def quo_source(
dated_endpoints = _dated_endpoints(api_version)
dated_config = dated_endpoints.get(endpoint) if dated_endpoints is not None else None
+ if config.fan_out_over_contacts:
+ return _source_response(
+ endpoint, config, lambda: _contact_notes_rows(api_key, config, resumable_source_manager)
+ )
+
last_value = db_incremental_field_last_value if should_use_incremental_field else None
cursor_field = incremental_field or (config.incremental_fields[0]["field"] if config.incremental_fields else None)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py
index a211f8b77c3f..d575f76cb324 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py
@@ -25,7 +25,7 @@ DATED_PAGE_SIZE = 50
class QuoEndpointConfig:
name: str
path: str
- primary_key: str = "id"
+ primary_keys: tuple[str, ...] = ("id",)
# None means the endpoint returns the full collection in one unpaginated response.
page_size: int | None = None
incremental_fields: list[IncrementalField] = field(default_factory=list)
@@ -40,6 +40,9 @@ class QuoEndpointConfig:
# /v1/calls serves one-to-one conversations only (`participants` caps at one number);
# /v1/messages accepts the full participants array of a group conversation.
supports_group_conversations: bool = True
+ # Contact notes exist only under 2026-03-30 and list one contact at a time, so the endpoint
+ # fans out over the dated contacts list under every pinned version.
+ fan_out_over_contacts: bool = False
QUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {
@@ -63,7 +66,7 @@ QUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {
"contact_custom_fields": QuoEndpointConfig(
name="contact_custom_fields",
path="/v1/contact-custom-fields",
- primary_key="key",
+ primary_keys=("key",),
),
"conversations": QuoEndpointConfig(
name="conversations",
@@ -92,6 +95,15 @@ QUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {
partition_key="createdAt",
fan_out_over_conversations=True,
),
+ "contact_notes": QuoEndpointConfig(
+ name="contact_notes",
+ path="/contacts/{contactId}/notes",
+ page_size=DATED_PAGE_SIZE,
+ # Notes carry no contact reference, and Quo documents no global uniqueness for note IDs.
+ primary_keys=("contactId", "id"),
+ partition_key="createdAt",
+ fan_out_over_contacts=True,
+ ),
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py
index 725d9d304197..59619426b853 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py
@@ -261,6 +261,80 @@ class TestDatedVersion:
assert result.requests == []
+def _notes_state(contacts_cursor: str, contact_id: str, notes_cursor: str | None) -> QuoResumeConfig:
+ return QuoResumeConfig(
+ page_token=contacts_cursor, api_version="2026-03-30", contact_id=contact_id, notes_cursor=notes_cursor
+ )
+
+
+class TestContactNotes:
+ @pytest.mark.parametrize("api_version", [QUO_API_VERSION_V1, QUO_API_VERSION_2026_03_30])
+ def test_fans_out_over_contacts_on_the_dated_wire(self, api_version):
+ result = _source(
+ "contact_notes",
+ [
+ _dated_page([{"id": "CT1"}, {"id": "CT2"}], next_cursor="c2"),
+ _dated_page([{"id": "N1"}], next_cursor="n2"),
+ _dated_page([{"id": "N2"}]),
+ _dated_page([]),
+ _dated_page([{"id": "CT3"}]),
+ # CT3 was deleted after the contacts page was read.
+ ScriptedResponse(status=404, json={"message": "Not Found"}),
+ ],
+ api_version=api_version,
+ )
+
+ assert result.raised is None
+ assert [(row["contactId"], row["id"]) for row in result.rows] == [("CT1", "N1"), ("CT1", "N2")]
+ assert result.paths == [
+ "/contacts",
+ "/contacts/CT1/notes",
+ "/contacts/CT1/notes",
+ "/contacts/CT2/notes",
+ "/contacts",
+ "/contacts/CT3/notes",
+ ]
+ assert result.params("after") == [None, None, "n2", None, "c2", None]
+ assert {request.headers["quo-api-version"] for request in result.requests} == {"2026-03-30"}
+ assert result.saved_states == [_notes_state("", "CT1", "n2"), _notes_state("", "CT1", None)]
+
+ @pytest.mark.parametrize(
+ "resume_state, expected_paths, expected_after",
+ [
+ (
+ _notes_state("c5", "CT2", "n3"),
+ ["/contacts", "/contacts/CT2/notes", "/contacts/CT3/notes"],
+ ["c5", "n3", None],
+ ),
+ (
+ _notes_state("c5", "CT1", None),
+ ["/contacts", "/contacts/CT2/notes", "/contacts/CT3/notes"],
+ ["c5", None, None],
+ ),
+ (
+ _notes_state("c5", "CT0", None),
+ ["/contacts", "/contacts/CT1/notes", "/contacts/CT2/notes", "/contacts/CT3/notes"],
+ ["c5", None, None, None],
+ ),
+ (
+ QuoResumeConfig(page_token="tok5"),
+ ["/contacts", "/contacts/CT1/notes", "/contacts/CT2/notes", "/contacts/CT3/notes"],
+ [None, None, None, None],
+ ),
+ ],
+ )
+ def test_resumes_after_the_last_written_notes_page(self, resume_state, expected_paths, expected_after):
+ result = _source(
+ "contact_notes",
+ [_dated_page([{"id": "CT1"}, {"id": "CT2"}, {"id": "CT3"}]), *[_dated_page([]) for _ in range(3)]],
+ resume_state=resume_state,
+ )
+
+ assert result.raised is None
+ assert result.paths == expected_paths
+ assert result.params("after") == expected_after
+
+
class TestQuoSourceResponse:
def test_unknown_endpoint_raises_unknown_resource(self):
result = _source("not_a_table", [])