: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(warehouse_sources): support persona API version 2026-09-29 (#119209)
Tom Owers82ba75184084
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/api_inventory.md b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/api_inventory.mdindex 86ef71e67274..ed1d8ae9bde9 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/api_inventory.md+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/api_inventory.md@@ -11,6 +11,13 @@ Reference: <https://docs.withpersona.com/reference> · Base URL: `https://api.wi`created-at`. No `updated-at` filter exists, so only `created_at` is advertised as an incremental cursor(updates to existing records are captured on full refresh, not incrementally).- **Rate limit:** 300 req/min; `429` with reset headers on excess (handled by retry + backoff).+- **Versions:** dated, selected per request with a `Persona-Version` header; without it the API key's+ dashboard-configured version applies ([versioning](https://docs.withpersona.com/versioning)). The legacy+ `v1` label sends no header, so those pins keep following the key's version. `2026-09-29` (the default+ for new sources) sends `Persona-Version: 2026-09-29`. Its only breaking change this source reads is in+ `verifications`: `immigration-status` on UK share code verifications now carries the Home Office status+ text verbatim instead of a mapped value+ ([changelog](https://docs.withpersona.com/api-reference/versioning/api-changelog)).## Endpoints synceddiff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.py b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.pyindex 01b8c0b2bda2..39c0c23fe071 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.py@@ -10,6 +10,7 @@ from structlog.types import FilteringBoundLoggerfrom tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential_jitterfrom products.warehouse_sources.backend.temporal.data_imports.pipelines.core.batcher import Batcher+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import UNVERSIONED_API_VERSIONfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.http import make_tracked_sessionfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManagerfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponse@@ -22,6 +23,15 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.persona.sePERSONA_BASE_URL = "https://api.withpersona.com/api/v1"+PERSONA_API_VERSION_2026_09_29 = "2026-09-29"++# `Persona-Version` header per supported label. The legacy label sends none, so its requests keep+# resolving to the API key's dashboard-configured version exactly as before versioning existed.+PERSONA_VERSION_HEADERS: dict[str, str | None] = {+ UNVERSIONED_API_VERSION: None,+ PERSONA_API_VERSION_2026_09_29: PERSONA_API_VERSION_2026_09_29,+}+# Persona's default rate limit is 300 req/min; it returns 429 with a reset header on excess.PAGE_SIZE = 100 # Persona caps page[size] at 100 (default 10).@@ -50,15 +60,17 @@ class PersonaResumeConfig:after: str | None = None-def _get_headers(api_key: str) -> dict[str, str]:- # No `Persona-Version` header is sent: omitting it applies the account's dashboard-configured- # default API version, which is always valid. Pinning a version we can't test risks a 400 if the- # value predates a field or is rejected. The attributes we read (`created-at`, `id`) are stable- # across versions.- return {+def _get_headers(api_key: str, api_version: str) -> dict[str, str]:+ if api_version not in PERSONA_VERSION_HEADERS:+ raise ValueError(f"Unsupported Persona API version: {api_version}")+ headers = {"Authorization": f"Bearer {api_key}","Accept": "application/json",}+ persona_version = PERSONA_VERSION_HEADERS[api_version]+ if persona_version is not None:+ headers["Persona-Version"] = persona_version+ return headersdef _build_url(base_url: str, params: dict[str, Any]) -> str:@@ -117,7 +129,7 @@ def _flatten_item(item: dict[str, Any]) -> dict[str, Any]:return item-def validate_credentials(api_key: str) -> int:+def validate_credentials(api_key: str, api_version: str) -> int:"""Probe the cheapest core list endpoint and return the HTTP status (0 on network error).Callers map the status: 200 = valid, 401 = bad key, 403 = valid key missing a scope.@@ -129,7 +141,7 @@ def validate_credentials(api_key: str) -> int:# capture, following the same pattern as gusto and workday. Redirects are refused so the key# is only ever sent to the API host.response = make_tracked_session(capture=False, allow_redirects=False).get(- url, headers=_get_headers(api_key), timeout=10+ url, headers=_get_headers(api_key, api_version), timeout=10)return response.status_codeexcept Exception:@@ -254,13 +266,14 @@ def _build_params(config: PersonaEndpointConfig, watermark: Optional[datetime],def get_rows(api_key: str,endpoint: str,+ api_version: str,logger: FilteringBoundLogger,resumable_source_manager: ResumableSourceManager[PersonaResumeConfig],should_use_incremental_field: bool = False,db_incremental_field_last_value: Any = None,) -> Iterator[Any]:config = PERSONA_ENDPOINTS[endpoint]- headers = _get_headers(api_key)+ headers = _get_headers(api_key, api_version)batcher = Batcher(logger=logger, chunk_size=2000, chunk_size_bytes=100 * 1024 * 1024)# One session reused across every page so urllib3 keeps the connection alive. Inquiry and# verification bodies carry KYC PII the name-based scrubber can't reliably strip, so keep them@@ -339,6 +352,7 @@ def get_rows(def persona_source(api_key: str,endpoint: str,+ api_version: str,logger: FilteringBoundLogger,resumable_source_manager: ResumableSourceManager[PersonaResumeConfig],should_use_incremental_field: bool = False,@@ -351,6 +365,7 @@ def persona_source(items=lambda: get_rows(api_key=api_key,endpoint=endpoint,+ api_version=api_version,logger=logger,resumable_source_manager=resumable_source_manager,should_use_incremental_field=should_use_incremental_field,diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/source.pyindex 75d82fe778c6..863c6f27a8f0 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/source.py@@ -8,7 +8,11 @@ from products.warehouse_sources.backend.facade.source_config import (SourceFieldInputConfig,SourceFieldInputConfigType,)-from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import FieldType, ResumableSource+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import (+ UNVERSIONED_API_VERSION,+ FieldType,+ ResumableSource,+)from products.warehouse_sources.backend.temporal.data_imports.sources.common.canonical_descriptions import (CanonicalDescriptions,)@@ -20,6 +24,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_PersonaSourceConfig,)from products.warehouse_sources.backend.temporal.data_imports.sources.persona.persona import (+ PERSONA_API_VERSION_2026_09_29,PersonaResumeConfig,persona_source,validate_credentials as validate_persona_credentials,@@ -54,6 +59,8 @@ class PersonaSource(ResumableSource[PersonaSourceConfig, PersonaResumeConfig]):lists_tables_without_credentials = True # static endpoint catalog — safe for public docsapi_docs_url = "https://docs.withpersona.com/reference"+ supported_versions = (UNVERSIONED_API_VERSION, PERSONA_API_VERSION_2026_09_29)+ default_version = PERSONA_API_VERSION_2026_09_29@propertydef source_type(self) -> ExternalDataSourceType:@@ -114,6 +121,8 @@ Sandbox and production environments use separate API keys — use the one for thforce_refresh: bool = False,api_version: str | None = None,) -> list[SourceSchema]:+ # The endpoint catalog is static and identical across Persona API versions, so discovery+ # ignores the pin; it is consumed at the request layer.def _build_schema(endpoint: str) -> SourceSchema:endpoint_config = PERSONA_ENDPOINTS[endpoint]has_incremental = endpoint_config.supports_incremental and bool(INCREMENTAL_FIELDS.get(endpoint))@@ -139,7 +148,7 @@ Sandbox and production environments use separate API keys — use the one for thschema_name: Optional[str] = None,api_version: str | None = None,) -> tuple[bool, str | None]:- status = validate_persona_credentials(config.api_key)+ status = validate_persona_credentials(config.api_key, self.resolve_api_version(api_version))if status == 200:return True, Noneif status == 401:@@ -167,6 +176,7 @@ Sandbox and production environments use separate API keys — use the one for threturn persona_source(api_key=config.api_key,endpoint=inputs.schema_name,+ api_version=self.resolve_api_version(inputs.api_version),logger=inputs.logger,resumable_source_manager=resumable_source_manager,should_use_incremental_field=inputs.should_use_incremental_field,diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona.py b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona.pyindex d784d388d29b..1220f14102e5 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona.py@@ -8,8 +8,10 @@ import requestsimport requests_mockfrom parameterized import parameterized+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import UNVERSIONED_API_VERSIONfrom products.warehouse_sources.backend.temporal.data_imports.sources.persona import personafrom products.warehouse_sources.backend.temporal.data_imports.sources.persona.persona import (+ PERSONA_API_VERSION_2026_09_29,PERSONA_BASE_URL,PersonaRedirectError,PersonaResumeConfig,@@ -112,6 +114,7 @@ class TestRedirectsRefused:list(get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint="inquiries",logger=MagicMock(),resumable_source_manager=_FakeResumableManager(), # type: ignore[arg-type]@@ -126,10 +129,54 @@ class TestRedirectsRefused:m.get(self.API_URL, status_code=302, headers={"Location": self.TARGET_URL})m.get(self.TARGET_URL, status_code=403)- assert persona.validate_credentials("persona_test") == 302+ assert persona.validate_credentials("persona_test", UNVERSIONED_API_VERSION) == 302assert [r.hostname for r in m.request_history] == ["api.withpersona.com"]+class TestPersonaVersionHeader:+ API_URL = f"{PERSONA_BASE_URL}/inquiries"++ @parameterized.expand(+ [+ # The legacy label sends no header, so the API key's dashboard version applies as before.+ ("legacy", UNVERSIONED_API_VERSION, None),+ ("2026_09_29", PERSONA_API_VERSION_2026_09_29, "2026-09-29"),+ ]+ )+ def test_sync_and_validation_send_the_pinned_version(+ self, _name: str, api_version: str, expected_header: str | None+ ) -> None:+ with requests_mock.Mocker() as m:+ m.get(self.API_URL, json={"data": [], "links": {"next": None}})++ list(+ get_rows(+ api_key="persona_test",+ endpoint="inquiries",+ api_version=api_version,+ logger=MagicMock(),+ resumable_source_manager=_FakeResumableManager(), # type: ignore[arg-type]+ )+ )+ assert persona.validate_credentials("persona_test", api_version) == 200++ assert len(m.request_history) == 2+ for request in m.request_history:+ assert request.headers.get("Persona-Version") == expected_header++ def test_unknown_version_is_rejected_instead_of_sending_no_header(self) -> None:+ with pytest.raises(ValueError, match="Unsupported Persona API version"):+ list(+ get_rows(+ api_key="persona_test",+ endpoint="inquiries",+ api_version="2025-12-08",+ logger=MagicMock(),+ resumable_source_manager=_FakeResumableManager(), # type: ignore[arg-type]+ )+ )++def _collect(manager: _FakeResumableManager,monkeypatch: Any,@@ -150,6 +197,7 @@ def _collect(rows: list[dict] = []for table in get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint=endpoint,logger=MagicMock(),resumable_source_manager=manager, # type: ignore[arg-type]@@ -220,6 +268,7 @@ class TestResume:with pytest.raises(PersonaRetryableError):for _ in get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint="inquiries",logger=MagicMock(),resumable_source_manager=manager, # type: ignore[arg-type]@@ -318,6 +367,7 @@ class TestVerificationsFanout:rows: list[dict] = []for table in get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint="verifications",logger=MagicMock(),resumable_source_manager=manager, # type: ignore[arg-type]@@ -351,6 +401,7 @@ class TestVerificationsFanout:list(get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint="verifications",logger=MagicMock(),resumable_source_manager=manager, # type: ignore[arg-type]@@ -411,6 +462,7 @@ class TestInquiryTemplateVersionsFanout:with patch.object(persona, "_fetch_page", fake_fetch):rows_iter = get_rows(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint="inquiry_template_versions",logger=MagicMock(),resumable_source_manager=manager, # type: ignore[arg-type]@@ -431,6 +483,7 @@ class TestPersonaSourceResponse:def test_incremental_endpoint_partitions_on_created_at_desc(self, endpoint: str, partition_key: str) -> None:response = persona_source(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint=endpoint,logger=MagicMock(),resumable_source_manager=MagicMock(),@@ -447,6 +500,7 @@ class TestPersonaSourceResponse:def test_full_refresh_endpoint_has_no_partitioning(self, endpoint: str) -> None:response = persona_source(api_key="persona_test",+ api_version=UNVERSIONED_API_VERSION,endpoint=endpoint,logger=MagicMock(),resumable_source_manager=MagicMock(),diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona_source.pyindex 95b1e76cec22..ef6426b730de 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona_source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/tests/test_persona_source.py@@ -2,11 +2,17 @@ from unittest.mock import MagicMock, patchfrom parameterized import parameterized+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import UNVERSIONED_API_VERSIONfrom products.warehouse_sources.backend.temporal.data_imports.sources.generated_configs.persona import (PersonaSourceConfig,)+from products.warehouse_sources.backend.temporal.data_imports.sources.persona.persona import (+ PERSONA_API_VERSION_2026_09_29,+)from products.warehouse_sources.backend.temporal.data_imports.sources.persona.source import PersonaSource+SOURCE_MODULE = "products.warehouse_sources.backend.temporal.data_imports.sources.persona.source"+class TestPersonaGetSchemas:@parameterized.expand(@@ -56,3 +62,30 @@ class TestPersonaValidateCredentials:PersonaSourceConfig(api_key="persona_test"), team_id=1, schema_name=schema_name)assert ok is expected_ok+++class TestPersonaVersionDispatch:+ def test_new_sources_default_to_2026_09_29(self) -> None:+ assert PersonaSource.default_version == PERSONA_API_VERSION_2026_09_29+ assert UNVERSIONED_API_VERSION in PersonaSource.supported_versions++ @parameterized.expand(+ [+ ("legacy_pin", UNVERSIONED_API_VERSION, UNVERSIONED_API_VERSION),+ ("2026_09_29_pin", PERSONA_API_VERSION_2026_09_29, PERSONA_API_VERSION_2026_09_29),+ ("no_pin", None, PERSONA_API_VERSION_2026_09_29),+ ]+ )+ def test_pin_reaches_sync_and_validation(self, _name: str, pin: str | None, expected: str) -> None:+ inputs = MagicMock(api_version=pin, schema_name="inquiries", should_use_incremental_field=False)+ with (+ patch(f"{SOURCE_MODULE}.persona_source") as persona_source,+ patch(f"{SOURCE_MODULE}.validate_persona_credentials", return_value=200) as validate,+ ):+ PersonaSource().source_for_pipeline(PersonaSourceConfig(api_key="persona_test"), MagicMock(), inputs)+ PersonaSource().validate_credentials(+ PersonaSourceConfig(api_key="persona_test"), team_id=1, api_version=pin+ )++ assert persona_source.call_args.kwargs["api_version"] == expected+ validate.assert_called_once_with("persona_test", expected)