Custom Definitions

A custom definition lets you describe an integration that JupiterOne doesn't ship out of the box and run it against your own data — a SaaS provider with no managed integration, an on-premise application, or a proprietary internal tool. You define the metadata once, then create one or more instances that execute on a schedule or push data on demand.

Definition, instance, and job

These three terms appear throughout the rest of this section. They describe the same integration at three different layers:

Definition — the template. Holds metadata describing the integration: name, type, class, the configuration fields a user must fill in (configFields), the authentication fields (authSections), the ingestion sources it produces, and the platform features it relies on. A definition is created once and reused.
Instance — a configured deployment of a definition. An instance binds a definition to specific credentials, a polling interval, an account name, and (optionally) a Collector. One definition can have many instances.
Job — a single execution of an instance. Each scheduled run, or each manual trigger, is a job. Jobs produce the entities and relationships you see in JupiterOne.

When to use a custom definition

Reach for a custom definition when:

The provider has no JupiterOne managed integration and you need recurring data ingestion.
The system is on-premise or behind a firewall and the runner must live inside your network.
You're integrating a proprietary or internally-built tool whose API only your team can access.

Ingestion options

A custom definition supports two ingestion paths. You pick one when you create the definition; you can change later without re-authoring.

Option	Use when	Continue with
Custom File Transfer (CFT)	Your data is already exported to CSV. Upload files directly; no runner, no API calls.	Custom File Transfer
Custom instance	You'll write code that pushes data to JupiterOne via the Sync API, using the instance's API key. Run that code wherever you want — CI, cron, event handler, on-prem host.	Custom integration: Code + Sync API

Author a custom definition

To create a custom definition in the JupiterOne app:

Navigate to Custom Definitions.
Click New Custom Definition.
Fill in the form:
- Icon — pick or upload an icon shown in the integrations list.
- Integration Name — display name for this custom integration.
- Integration Type — autofills from the Integration Name with your account alias appended as a suffix (for example my-integration-acme). This is the type string queries and downstream tools see.
- Documentation URL (optional) — link to your team's docs or the upstream vendor's docs for the data source.
- Description (optional).
- Category (optional) — choose from the dropdown.
- Type of custom definition — pick one:
  - CFT — the definition is set up for Custom File Transfer. Follow the CFT upload flow after creating.
  - Custom instance — JupiterOne creates a new instance and a new API key. Use the API key + instance ID from your code to push data via the Sync API. See Custom integration: Code + Sync API.
Click Create.