canonical: https://jentic.com/apis/journy.io/journy-io

# journy.io API

journy.io is a product-led growth platform that captures user and account behaviour to surface signals for sales, success, and marketing teams. The REST API lets backend systems upsert users and accounts, track events, link web activity, and read user and account properties and segments computed by journy.io. It is the right tool when a B2B SaaS product needs to keep its journy.io workspace in sync with its database without relying solely on the JavaScript snippet.

## For AI agents

Upsert journy.io users and accounts, track product events, link web activity, and read computed properties and segments so agents can keep the PLG workspace in sync with backend systems.

## Scope

Does not handle email or push notification delivery, billing or invoicing, or marketing automation execution - use for tracking, identification, and reading computed PLG signals only.

## Capabilities

- Upsert a user record with stable user ID and properties such as plan or registered_at
- Upsert an account record and add or remove users within that account
- Track product events with metadata for downstream segmentation and signals
- Link a journy.io web visitor to an authenticated user record
- Read computed user and account properties to enrich downstream tools
- Pull user and account segments computed by journy.io for routing and targeting
- Validate an API key and inspect available website tracking snippets

## Use cases

### Backend event tracking from the application server

B2B SaaS apps that want clean event data without relying on the JavaScript snippet can call POST /track from the application server when meaningful actions occur - invoice created, plan upgraded, integration connected. The API accepts a user or account ID with a free-form metadata object, and journy.io uses these events to compute signals for sales and success teams. This is the recommended path for events that don't have a natural front-end origin.

Example prompt: Call POST /track with name='created_invoice', accountId='30', metadata={amount: 100, plan: 'Pro'} after the invoice is persisted in the database

### Sync user and account state nightly

Product teams typically run a nightly job that upserts every user and account into journy.io to keep computed properties fresh. POST `/users/upsert` and POST `/accounts/upsert` accept stable IDs and a properties bag, and the calls are idempotent - re-upserting with the same ID updates the record. This keeps things like plan, MRR, and registration date current even when no behavioural events fire that day.

Example prompt: Iterate every account in the database, call POST `/accounts/upsert` with accountId and properties, then POST `/users/upsert` for each user on the account

### Read segments to drive in-product targeting

Once journy.io has computed user and account segments (e.g., 'high-intent trials', 'churn risk'), the application can read them via GET `/segments/users` and GET `/segments/accounts` to drive in-product behaviour - show a different upsell, route to a different success rep, or trigger a specific email. This avoids duplicating segmentation logic in the app.

Example prompt: Call GET `/segments/accounts` to fetch the 'high-intent trials' segment, then route those accounts to the assigned customer success rep

### GDPR delete-on-request

When a user invokes their right to be forgotten, the application server can issue DELETE /users with the user ID to remove the record from journy.io. DELETE /accounts performs the equivalent for an organisation. These endpoints fit neatly into a fan-out delete workflow alongside other vendor APIs, ensuring journy.io does not retain orphaned profiles after a request.

Example prompt: Call DELETE /users with userId='20' as part of a GDPR delete fan-out across journy.io and other vendor systems

### Agent-driven PLG sync via Jentic

An assistant connected to a CRM or operations tool can keep journy.io in sync without storing the X-API-Key directly. The agent expresses intent, Jentic resolves to the right operation (POST `/users/upsert`, POST /track, etc.), injects the API key from the vault, and returns the response. This is useful when the agent orchestrates updates across multiple PLG tools and shouldn't hold any of their long-lived keys.

Example prompt: Use Jentic to search 'upsert journy.io user', load POST `/users/upsert`, and execute it with the user's stable ID and updated plan property

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users/upsert` | Create or update a user |
| POST | `/accounts/upsert` | Create or update an account |
| POST | `/track` | Track an event |
| POST | `/accounts/users/add` | Add users to an account |
| POST | `/accounts/users/remove` | Remove a user from an account |
| DELETE | `/users` | Delete a user |
| GET | `/segments/users` | Get user segments |
| POST | `/link` | Link web activity to a user |

## Key resources

- **Users** — Upsert, delete, and read computed properties for users
- **Accounts** — Upsert and delete accounts and manage their user membership
- **Events** — Track and read events with metadata
- **Segments** — Read computed user and account segments
- **Tracking** — Validate API keys and retrieve website tracking snippets

## Why Jentic

- **Setup:** Wiring the journy.io API by hand means learning its API-key request header, shaping upsert and track payloads correctly, and reading computed PLG segments yourself. Through Jentic you install once, import the journy.io API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** journy.io identifies users and accounts in the request body rather than in the URL path, so you limit the agent to the operations it needs, such as upserting a user or tracking an event. Destructive operations like deleting users are left out unless you include them.
- **Credential handling:** Your journy.io API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upsert a journy.io user' or 'track a product event', and Jentic returns the matching journy.io operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Amplitude API** — Larger product analytics platform with deeper funnels and retention surfaces
- **Mixpanel API** — Product analytics with rich event tracking and reporting endpoints
- **Segment API** — Customer data pipeline that can route the same events into journy.io and other tools
- **HubSpot API** — Push journy.io segments into HubSpot to power CRM workflows on PLG signals

## FAQ

### What authentication does the journy.io API use?

The journy.io API expects an X-API-Key header on every request. Keys are managed in the journy.io connections screen and can be scoped by permission. Jentic stores the key encrypted and injects the X-API-Key header at call time, keeping it out of the agent's prompt context.

### Can I track events server-side instead of via the JavaScript snippet?

Yes. POST /track accepts an event name, an associated user or account ID, and a metadata object. journy.io recommends server-side tracking for events that don't have a natural front-end origin, which gives cleaner data than relying on the snippet alone.

### What are the rate limits for the journy.io API?

journy.io's published rate limit is 1800 requests per minute per API key. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers - watch these and back off as remaining approaches zero. Contact journy.io for higher throughput if needed.

### How do I upsert a user through Jentic?

Search Jentic for 'upsert a journy.io user', load POST `/users/upsert`, and execute with the user's stable ID and properties. Jentic injects the X-API-Key header. Get started with Jentic One, the self-hosted execution layer.

### How do I remove a user from an account?

Call POST `/accounts/users/remove` with the account ID and the user ID to revoke account membership without deleting the user record. To wipe the user entirely, call DELETE /users - the difference matters for GDPR vs. seat-management workflows.

### Can I read journy.io segments from the API?

Yes. GET `/segments/users` and GET `/segments/accounts` return the segments computed by journy.io. Use this to drive in-product targeting or routing without duplicating segmentation logic in your application.

### Can I limit what my agent is allowed to do with the journy.io API?

Yes. Because you run Jentic One yourself, your own rules decide which journy.io operations and credentials your agent may use. journy.io identifies users and accounts in the request body rather than the URL path, so you can allow only the operations the agent needs, such as POST `/users/upsert` or POST /track, and leave destructive calls like DELETE /users and DELETE /accounts out of its reach. The agent can invoke only the operations you grant, and your API key is injected at call time rather than exposed to it.