Journy

Developer documentation

Welcome Implementing a new tool can be daunting, but it doesn't have to. You can implement journy.io in a few different ways to ensure it fits with the rest…

Other#openapi#customer-relation

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Welcome

Implementing a new tool can be daunting, but it doesn't have to. You can implement journy.io in a few different ways to ensure it fits with the rest of your tech stack seamlessly.

We welcome your feedback, ideas and suggestions. We really want to make your life easier, so if we’re falling short or should be doing something different, we want to hear about it. Send us an email at [hi@journy.io](mailto:hi@journy.io) or reach out via the chat on our website or on our platform.

There are multiple ways you can send us data about users and accounts. We have both frontend and backend APIs, which can be used together at the same time.

If you already use Segment, you can get up and running with journy.io in seconds.

Concepts

Users

The most basic entity is a user, a specific individual that completed an interaction with your product.

We support multiple types of users, often differentiated by it's external ID prefix. E.g. In the case you are building an ordering app, there could easily be an administrator (who updates products and checks for orders) and the end-customers who place orders. One could have a typical ADM-XXXXXXXX ID, while the other would be referenced by USR-XXXXXXXXX.

Accounts

In B2B SaaS, users can be part of multiple accounts. E.g. Imagine you're building a content scheduling app where an agency can manage the social media posts of their clients. Each client of the agency has its own account in the product.

If your app doesn't have the concept of a team or group of users, you can ignore accounts.

Events

An event is a data point that represents an interaction between a user and/or an account; and your product. Events can represents any range of interactions. E.g. Every time a customer creates an invoice in an invoicing app. Actions like creating an invoice can be tracked as an event in journy.io.

It's critical to track events properly. You'll need to provide either an account ID, or a user ID, or both; when tracking an event. E.g. If a user updates his personal settings, you can omit the account ID as the event would not be related to any account. In a same logic, an account could get a 'suspend account' event (with account ID) from an internal process, whereas no user would be associated. In most cases, events will be associated to both 1 user and 1 account.

You can optionally pass extra details as metadata (e.g. amount of the invoice). This gets particarly powerfull when creating computed properties on those event metadata. E.g. Our above ordering app could send journy.io 'Place Order' events with metadata 'price', on which journy.io very easily would compute a total order value (for each account) for the last 30 days.

💡 Metadata does not update the properties of a user or account.

Frontend vs backend

The best implementations we see employ a hybrid approach to maximize data quality while maintaining the flexibility to easily collect the data they need.

We recommend using our JavaScript snippet to track screen views and our backend API to sync users, sync accounts and track events.

When evaluating how to track a particular event, we suggest starting with server-side and only use frontend if it's not possible to collect purely server-side. This can be the case if you need to track interactions with your product that don't result in any natural server requests (such as a button click that opens a modal).

Frontend

Setup

💡 You can find the JavaScript snippet in the website settings in the connections view.

Copy the JavaScript snippet and place it in the head or body of your application.

The snippet automatically calls journy("init", { ... }) and journy("pageview").

Identify user

💡 A user ID should be a robust, static, unique identifier that you recognize a user by in your own systems. Because these IDs are consistent across a customer’s lifetime, you should include a user ID in identify calls as often as you can. Ideally, the user ID should be a database ID.

💡 journy.io does not recommend using simple email addresses or usernames as user ID, as these can change over time. journy.io recommends that you use static IDs instead, so the IDs never change. When you use a static ID, you can still recognize the user in your analytics tools, even if the user changes their email address.

💡 The properties full_name, first_name, last_name, phone and registered_at will be used for creating contacts in destinations like Intercom, HubSpot, Salesforce, ...

journy("identify") allows you to identify the user that is currently using your product.

journy("identify", {
  // Email or user ID is required
  email: "john.doe@acme.com",
  // Unique identifier for the user in your database
  userId: "20",

  // Optional
  // Hash of the user ID using a backend secret
  // You can find the secret in the website settings
  // Recommended to prevent spoofing
 …

Endpoints 16

Users

  • POSTLink web activity to user/link💡 You don't need to use this endpoint if you use our JavaScript snippet in your application. This endpoint is used to link web activity to a user in your…
  • DELETEDelete user/usersEndpoint to delete a user.
  • POSTCreate or update user/users/upsertEndpoint to create or update a user.

Accounts

  • DELETEDelete account/accountsEndpoint used to delete an account.
  • POSTCreate or update account/accounts/upsertEndpoint used to create or update an account.
  • POSTAdd users to an account/accounts/users/addYou can add up to 100 users to an account.
  • POSTRemove user from account/accounts/users/removeYou can remove up to 100 users from an account. When removing a user, the user will still be stored in journy.io, but marked as "removed".

Track

  • POSTTrack event/trackEndpoint used to track an event for a user or an account.

Properties

  • GETGet account properties/properties/accountsEndpoint to list account properties.
  • GETGet user properties/properties/usersEndpoint to list user properties.

Events

  • GETGet events/eventsEndpoint to list events.
  • POSTTrack event/eventsDeprecated. Endpoint used to track an event for a user or an account. This endpoint is moved to Track.

Segments

  • GETGet account segments/segments/accountsEndpoint to list account segments.
  • GETGet user segments/segments/usersEndpoint to list user segments.

Websites

  • GETGet snippet for a website/tracking/snippet?domain=stringEndpoint used to get a snippet for a website.

Validation

  • GETValidate API key/validateEndpoint used to test the validity and some basic information about a specific API Key.

API details

Base URL
https://api.journy.io
Authentication
None declared in the description
Operations
16 operations on 15 pathsGET 7POST 7DELETE 2
1 marked deprecated
Main resources
Accounts 4Users 3Events 2Properties 2Segments 2Track 1Validation 1Websites 1
Response formats
application/json
Description format
OpenAPI 3.0.3, API version 1.0.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Developer documentation in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Developer documentation collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Link web activity to user” (POST /link), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Developer documentation?

Welcome Implementing a new tool can be daunting, but it doesn't have to. You can implement journy.io in a few different ways to ensure it fits with the rest… It is listed under Other and has 16 endpoints.

Who publishes the Developer documentation?

It is listed from Journy's public API description (an OpenAPI document), not published by Journy on Swastik Codes. Anyone who controls journy.io can claim the profile by adding a DNS TXT record.

What is the base URL of the Developer documentation?

Requests go to https://api.journy.io. Endpoint paths are added to this base URL.

How do I authenticate with the Developer documentation?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the Developer documentation have?

16 operations on 15 paths (7 GET, 7 POST, 2 DELETE). The largest groups are Accounts, Users, Events, Properties.

Is forking the Developer documentation free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.