[markdennis22]

Why?

The 2.17 spec for the data attribute, data event, data export and visitor endpoints didn't match the API. The export docs gave the wrong job limit, link expiry and download format. Event metadata was typed as strings only, the visitor request and response shapes were off, and most error responses were missing. The Preview spec had the same problems, and the next version is cut from Preview, so it needs the same fixes.

How?

Corrects these endpoints and their schemas to match the API's current behaviour, and adds the OAuth scopes each endpoint accepts to its description. The same changes go into the Preview spec, keeping content that only applies to Preview, such as the {id} path parameter name. Preview's data export field job_identfier is also renamed job_identifier, the name the API sends.

Risks

The Preview SDKs are generated from this spec, so these changes affect generated Preview types:

Change	Could SDK code stop compiling?	Did that code work before?
datetime leaves CreateDataAttributeRequestOneDataType	Yes, if it uses that value	No. The API rejects it with a 400
DataAttributeDataType gains relationship	No, but an exhaustive match needs a new case	No. The API already returns it
DataExport.job_identfier is renamed job_identifier	Yes, if it reads job_identfier	No. The API sends job_identifier, so the misspelt field was never set
convertVisitor's user becomes optional	No	—
VisitorCompanies.companies items become VisitorCompaniesCompaniesItem instead of Company, VisitorSegments.segments items become VisitorSegmentsSegmentsItem instead of strings, and Visitor.custom_attributes values become a string, integer, number or boolean union	Yes	No. The API sends those shapes
lisDataEvents: type becomes the LisDataEventsRequestType enum, the filter union gains LisDataEventsRequestFilterAnonymousId, and before, since and per_page are new	Possibly	Yes, but generated clients couldn't send them
New 400, 404, 422, 429, 500 and 504 errors on these operations	No	—

Notes for reviewers

• create_data_event_summaries_request now says one of id, user_id or email is required, as an anyOf. fern check fails on that anyOf, so fern/preview-openapi-overrides.yml drops it, and the Preview request type doesn't change.
• metadata on data_event and create_data_event_request now lists the value types. The Preview Fern overrides already keep metadata a free-form map, so those types don't change either.
• fern check shows 0 errors. There are no new dangling refs and no operationId changes, and none of the changed Preview types is unknown.

_{Generated with Claude Code}

[markdennis22]

Thanks for this. Checked the 2.17 and Preview changes for parity, dangling refs and operationId changes, fern check (no new errors or warnings), the generated Preview SDK types, and each changed statement against the API's behaviour.

A few questions:

1. created_at on createDataEvent — Should created_at go back into the required lists? A single event sent without the created_at key returns 400 parameter_not_found "missing data parameter". The request time is only used when created_at is sent as null.
2. company on updateVisitor — Should company come out of the request schema? The API never applies it, whether or not the request also promotes the visitor to a lead. companies is only applied when the same request also sends email. Is that worth saying?
3. End-before-start 422 on createDataExport — Should the "End date before start date" 422 example come out? That case always returns the 400 "created_at_after is greater than created_at_before" first.
4. convertVisitor with type: user and no user — The spec required user. With type: user and no user, the API returns 200 and leaves the visitor as it was. Should the spec keep user required when type is user, or describe what the API does?
5. "Missing event name" example — "missing event_name parameter" only appears when event_name is sent as null. Leaving out event_name, created_at or the user identifier returns 400 "missing data parameter". Is that worth adding as an example?
6. avatar on updateVisitor — The API also accepts an object {type: avatar, image_url}. Should the schema allow both?

Items 1 to 4 need a change before this is ready; 5 and 6 are optional.

~ Automated via Claude

[markdennis22]

Addressed in the latest push, with the same edit to 2.17 and Preview:

1. created_at on createDataEvent — Back in all three required lists, with the description reverted to "The time the event occurred as a UTC Unix timestamp".
2. company on updateVisitor — Removed. companies now says it is only applied when the same request sends email, which promotes the visitor to a lead.
3. End-before-start 422 on createDataExport — Example removed. The 90-day 422 stays.
4. convertVisitor with type: user and no user — The operation and the user property now say user is required when type is user and not read when type is lead. The schema can't express that condition, so the top-level required stays [type, visitor].
5. "missing data parameter" example — Added as "Missing a required field". The old example is renamed "Null event name".
6. avatar on updateVisitor — Left as a string on purpose, to match the create and update contact schemas.

Re-checked: no new dangling refs or operationId changes, and fern check has the same error and warning counts as main.

~ Automated via Claude