Zendesk API

{
  "id": 1,
  "subject": "<Ticket subject>",
  "status": "<new, open, pending, hold, solved or closed>",
  "priority": "<low, normal, high or urgent; null by default>",
  "requester_id": 1,
  "assignee_id": 1
}

{
  "id": 1,
  "author_id": 1,
  "body": "<Plain-text body>",
  "public": false,
  "created_at": "<ISO 8601 timestamp>"
}

{
  "id": 1,
  "ticket_id": 1,
  "author_id": 1,
  "events": [],
  "created_at": "<ISO 8601 timestamp>"
}

{
  "id": 1,
  "name": "<Full name>",
  "email": "person@example.test",
  "role": "<end-user, agent or admin>",
  "organization_id": 1
}

{
  "id": 1,
  "name": "<Organization name>",
  "external_id": "<Id in your own system>",
  "domain_names": [],
  "tags": [],
  "group_id": 1
}

{
  "id": 1,
  "name": "<Group name>",
  "description": "<What the group handles>",
  "default": false
}

{
  "id": 1,
  "user_id": 1,
  "group_id": 1,
  "organization_id": 1,
  "default": false
}

{
  "results": [],
  "count": 1,
  "next_page": "<URL of the next page>",
  "previous_page": "<URL of the previous page>"
}

Native Zendesk records

The zendesk object contains version: 1, principal_id and arrays for users, groups, organizations, memberships, tickets, comments and audits. Start from the bundled zendesk-support-v1 example in the dashboard, or an offline import. To inspect the bundled JSON, use GET /admin/seeds/zendesk-support-v1 on your local server; see the Admin API.

Native IDs and references are positive safe integers. The principal must be an active, nonsuspended agent or admin. Directory membership, assignment, comments and audit history are validated together; copying ticket rows alone is not sufficient.

Native timestamp chronology uses the full accepted ISO instant, including fractional digits beyond milliseconds and equivalent timezone spellings. Supplied creation and update times must be at or before the epoch; update must not precede creation. Omitted creation defaults to the epoch and omitted update to creation. A comment and its owning audit must have equal instants. Original timestamp strings survive export and reload.

The native scope documents supported behavior. Source checkouts also include the complete native seed schema for contributors.

Logical closure and follow-up metadata

Optional zendesk.lifecycle.closure enables simulated closure:

Field	Accepted value
after_hours	Integer from 1 to 672
sweep_phase_seconds	Integer from 0 to 3599
author_id	Existing native agent or admin

Omitting closure adds no defaults. Tickets may declare solved_at (ISO instant or null) and via_followup_source_id (native ticket ID). Audits may declare via_channel as api or rule.

For closure-enabled solved tickets, created_at <= solved_at <= updated_at <= epoch. Ticket, comment and audit history must not extend beyond the derived closure boundary. Active unsolved tickets require absent or null solved_at; closed tickets may retain the solve episode.

A follow-up source must exist, be closed and be no newer than its child. Equal creation times are valid; self-references and ancestry cycles are rejected.

These fields survive export and reload. Read closure timing and limits before using them to model a workflow.

An ordinary native seed also requires the shared seed file fields: name, version, epoch and data. Use empty data collections for a standalone native world and supply the complete top-level zendesk profile. The alternative offline wrapper is described below.

Relationships in a native snapshot

• principal_id selects an active agent or admin from users.
• Group and organization memberships connect users to the corresponding directory records.
• Ticket requester, submitter, assignee, group and organization references must resolve within the snapshot and satisfy assignment rules.
• Comments belong to tickets and authors; their owning audits and Comment events must agree. Include the complete history required by those references.

This is an illustrative user record, not an importable seed. A complete native seed also supplies the profile, principal and referenced collections:

{ "id": 1, "name": "Alex Support", "email": "alex@example.test", "role": "agent", "active": true, "suspended": false }

Offline native Zendesk import

worlds seed import --from-zendesk --input support-export.json --name my-support

This CLI accepts a complete native seed or the explicit worlds-zendesk-native-export format below. It does not fetch a live Zendesk account or accept arbitrary vendor exports. The dashboard offers guided data preparation, including supported offline Zendesk Full JSON conversion.

The import remaps identities, replaces supported identifying text and preserves valid relationships, privacy, timestamps and audit history. Attachments and unsupported fields are omitted and counted. Review the generated manifest.

Defaults are seeds/my-support.json and worlds/my-support.manifest.json. An optional --identity-map is private. See native import workflows for destination rules and composition with Stripe.

Accepted native input contracts

An ordinary native seed must have a top-level zendesk profile and empty Stripe/legacy data collections. Alternatively, the wrapper has:

• format: "worlds-zendesk-native-export"
• version: 1
• epoch
• zendesk containing the full native profile

Both forms require the principal, directory and membership records, tickets, comments and audits needed to satisfy all references. Optional lifecycle metadata must be coherent.

A populated composite seed is not an input to this importer. Import each source separately, then compose sanitized seeds with matching epochs. A native seed's clock configuration is preserved; the wrapper uses seed defaults.

Legacy ticket records

Native Zendesk records and legacy ticket records cannot coexist in one seed. Choose the profile for the workflow before importing records.

data.tickets[] serves the demo-grade, Zendesk-shaped desk. It is separate from native Zendesk. IDs are assigned in file order as "1", "2" and so on.

Legacy ticket fields

Field	Type or default
subject, body	Required nonempty strings
requester	Required {name, email}; nonempty name and valid email
status	new, open, pending, hold, solved or closed; default open
priority	low, normal, high or urgent; default normal
tags	String array; default []
external_id	Optional string or null
first_comment_public	Optional boolean; defaults in behavior to true
created_offset	Nonnegative seconds before the epoch; default 0

Billing references in ticket text are not foreign keys. Billing tasks compile into this profile, with one ticket per task and an answer key kept separately.

This legacy record fragment belongs in data.tickets[], not in the native zendesk.tickets collection:

{ "subject": "Billing question", "body": "Please check my invoice.", "requester": { "name": "Sam", "email": "sam@example.test" }, "status": "open", "priority": "normal" }

Referential integrity

Validation rejects unknown fields, duplicate IDs, missing references and inconsistent history. Errors name the JSON path to fix.

For native Zendesk, it checks directory relationships, principal authority, comment/audit links and lifecycle metadata.

Imported native IDs set allocator floors so runtime-created records cannot reuse them. Native wire IDs are numeric; admin state keys remain strings.

Validate the complete seed before use:

worlds seed validate my-seed.json

Save a world's current state as a seed

In the dashboard, choose Save as starting setup from an eligible world. From the CLI:

worlds world export w_abc123def456 --name my-fork

The admin equivalent is GET /admin/worlds/:id/export-seed?name=my-fork. Use the result to start another test from the state your agent produced.

The export uses the world's current logical clock as its epoch and validates as a seed. Its lossy report lists state the seed format cannot retain:

Not retained	What survives
Event log	Current supported records

Native Zendesk export keeps supported directory records, tickets, comments, full audit history and lifecycle metadata. Legacy record offsets remain relative to the new epoch. Combined billing worlds also follow the Stripe export limits.

Exporting and reloading represents settled state, not a replay of the run. Re-exporting that loaded world preserves the same data block.

Library seeds

Seed	Use
zendesk-support-v1	Explore native directory, ticket, comment and audit records
zendesk-outcomes-support-v1	Native support tasks; used by init --connector zendesk
zendesk-outcomes-billing-v1	Combined support and Stripe billing tasks; used by init --connector composite

Bundled seeds are synthetic fixtures. See the generated seed catalog for their builders and starter packs for ready-made tasks.