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): 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.md
index 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 synced
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.py b/products/warehouse_sources/backend/temporal/data_imports/sources/persona/persona.py
index 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 FilteringBoundLogger
from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential_jitter
from 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_VERSION
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.resumable import ResumableSourceManager
from 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.se
PERSONA_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 headers
def _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_code
except 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.py
index 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 docs
api_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
@property
def source_type(self) -> ExternalDataSourceType:
@@ -114,6 +121,8 @@ Sandbox and production environments use separate API keys — use the one for th
force_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 th
schema_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, None
if status == 401:
@@ -167,6 +176,7 @@ Sandbox and production environments use separate API keys — use the one for th
return 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.py
index 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 requests
import requests_mock
from parameterized import parameterized
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import UNVERSIONED_API_VERSION
from products.warehouse_sources.backend.temporal.data_imports.sources.persona import persona
from 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) == 302
assert [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.py
index 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, patch
from parameterized import parameterized
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.base import UNVERSIONED_API_VERSION
from 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)