Skip to main content

Data Management API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.dataManagement.queryEntities(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/data-management'

const dataManagementClient = getClient()
authorize(dataManagementClient, () => '<token>')
const { data } = await dataManagementClient.queryEntities(...)

Operations​

Data Management

Schemas

queryEntities​

Query entities using a saved view with additional data filters

POST /data-management/v1/{entity_schema}/query

const { data } = await client.queryEntities(
  {
    entity_schema: 'example',
  },
  {
    saved_view_id: 'string',
    include_deleted: 'true',
    filters: [
      {
        type: 'entity_workflows_only_in_closed_or_cancelled_status',
        related_entity_schemas: ['string'],
        lookback_period_days: 0
      }
    ],
    from: 0,
    size: 0,
    hydrate: true,
    fields: ['string']
  },
)
Response
{
  "hits": 0,
  "results": [
    {}
  ]
}

createJob​

Create a new job run

POST /data-management/v1/{entity_schema}/jobs

const { data } = await client.createJob(
  {
    entity_schema: 'example',
  },
  {
    type: 'deletion',
    config_id: 'string',
    scheduled_for: 'string',
    status: 'in_progress',
    started_at: '1970-01-01T00:00:00.000Z'
  },
)
Response
{
  "id": "string",
  "type": "deletion",
  "config_id": "string",
  "entity_schema": "string",
  "scheduled_for": "string",
  "status": "in_progress",
  "details": {},
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z",
  "error": "string",
  "report": {
    "bucket": "string",
    "key": "string",
    "format": "csv"
  },
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "trigger": "schedule",
  "triggered_by": "string"
}

updateJob​

Update an existing job run

PATCH /data-management/v1/{entity_schema}/jobs/{job_id}

const { data } = await client.updateJob(
  {
    entity_schema: 'example',
    job_id: 'example',
  },
  {
    status: 'in_progress',
    details: {},
    completed_at: '1970-01-01T00:00:00.000Z',
    error: 'string',
    report: {
      bucket: 'string',
      key: 'string',
      format: 'csv'
    }
  },
)
Response
{
  "id": "string",
  "type": "deletion",
  "config_id": "string",
  "entity_schema": "string",
  "scheduled_for": "string",
  "status": "in_progress",
  "details": {},
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z",
  "error": "string",
  "report": {
    "bucket": "string",
    "key": "string",
    "format": "csv"
  },
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "trigger": "schedule",
  "triggered_by": "string"
}

getJob​

Get a job by id

GET /data-management/v1/jobs/{job_id}

const { data } = await client.getJob({
  job_id: 'example',
})
Response
{
  "id": "string",
  "type": "deletion",
  "config_id": "string",
  "entity_schema": "string",
  "scheduled_for": "string",
  "status": "in_progress",
  "details": {},
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z",
  "error": "string",
  "report": {
    "bucket": "string",
    "key": "string",
    "format": "csv"
  },
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "trigger": "schedule",
  "triggered_by": "string"
}

getJobReportUrl​

Get report download URL for a job

GET /data-management/v1/jobs/{job_id}/report-url

const { data } = await client.getJobReportUrl({
  job_id: 'example',
})
Response
{
  "url": "string",
  "expires_in": 0
}

getConfig​

Get a config by id

GET /data-management/v1/configs/{config_id}

const { data } = await client.getConfig({
  config_id: 'example',
})
Response
{
  "id": "string",
  "type": "deletion",
  "entity_schema": "string",
  "query": {
    "saved_view_id": "string",
    "include_deleted": "true",
    "filters": [
      {
        "type": "entity_workflows_only_in_closed_or_cancelled_status",
        "related_entity_schemas": ["string"],
        "lookback_period_days": 0
      }
    ]
  },
  "schedule": {
    "frequency": "interval",
    "interval_days": 1,
    "start_date": "string",
    "end_date": "string"
  },
  "enabled": true,
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "next_run_at": "string",
  "relations_for_deletion": ["contact"],
  "last_run_at": "1970-01-01T00:00:00.000Z"
}

createJobForConfig​

Trigger a manual job run for a config

POST /data-management/v1/configs/{config_id}/jobs

const { data } = await client.createJobForConfig({
  config_id: 'example',
})
Response
{
  "id": "string",
  "type": "deletion",
  "config_id": "string",
  "entity_schema": "string",
  "scheduled_for": "string",
  "status": "in_progress",
  "details": {},
  "started_at": "1970-01-01T00:00:00.000Z",
  "completed_at": "1970-01-01T00:00:00.000Z",
  "error": "string",
  "report": {
    "bucket": "string",
    "key": "string",
    "format": "csv"
  },
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "trigger": "schedule",
  "triggered_by": "string"
}

upsertConfig​

Upsert config

POST /data-management/v1/{entity_schema}/configs

const { data } = await client.upsertConfig(
  {
    entity_schema: 'example',
  },
  {
    type: 'deletion',
    query: {
      saved_view_id: 'string',
      include_deleted: 'true',
      filters: [
        {
          type: 'entity_workflows_only_in_closed_or_cancelled_status',
          related_entity_schemas: ['string'],
          lookback_period_days: 0
        }
      ]
    },
    schedule: {
      frequency: 'interval',
      interval_days: 1,
      start_date: 'string',
      end_date: 'string'
    },
    relations_for_deletion: ['contact'],
    enabled: true
  },
)
Response
{
  "id": "string",
  "type": "deletion",
  "entity_schema": "string",
  "query": {
    "saved_view_id": "string",
    "include_deleted": "true",
    "filters": [
      {
        "type": "entity_workflows_only_in_closed_or_cancelled_status",
        "related_entity_schemas": ["string"],
        "lookback_period_days": 0
      }
    ]
  },
  "schedule": {
    "frequency": "interval",
    "interval_days": 1,
    "start_date": "string",
    "end_date": "string"
  },
  "enabled": true,
  "created_at": "1970-01-01T00:00:00.000Z",
  "last_updated_at": "1970-01-01T00:00:00.000Z",
  "next_run_at": "string",
  "relations_for_deletion": ["contact"],
  "last_run_at": "1970-01-01T00:00:00.000Z"
}

listConfigs​

List configs

GET /data-management/v1/configs

const { data } = await client.listConfigs({
  limit: 1,
  cursor: 'example',
  entity_schema: 'example',
  type: 'example',
  next_run_at: 'example',
  enabled: true,
})
Response
{
  "configs": [
    {
      "id": "string",
      "type": "deletion",
      "entity_schema": "string",
      "query": {
        "saved_view_id": "string",
        "include_deleted": "true",
        "filters": [
          {
            "type": "entity_workflows_only_in_closed_or_cancelled_status",
            "related_entity_schemas": ["string"],
            "lookback_period_days": 0
          }
        ]
      },
      "schedule": {
        "frequency": "interval",
        "interval_days": 1,
        "start_date": "string",
        "end_date": "string"
      },
      "enabled": true,
      "created_at": "1970-01-01T00:00:00.000Z",
      "last_updated_at": "1970-01-01T00:00:00.000Z",
      "next_run_at": "string",
      "relations_for_deletion": ["contact"],
      "last_run_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "cursor": "string"
}

listJobs​

List jobs

GET /data-management/v1/jobs

const { data } = await client.listJobs({
  limit: 1,
  cursor: 'example',
  entity_schema: 'example',
  type: 'example',
  status: 'example',
  config_id: 'example',
})
Response
{
  "jobs": [
    {
      "id": "string",
      "type": "deletion",
      "config_id": "string",
      "entity_schema": "string",
      "scheduled_for": "string",
      "status": "in_progress",
      "details": {},
      "started_at": "1970-01-01T00:00:00.000Z",
      "completed_at": "1970-01-01T00:00:00.000Z",
      "error": "string",
      "report": {
        "bucket": "string",
        "key": "string",
        "format": "csv"
      },
      "created_at": "1970-01-01T00:00:00.000Z",
      "last_updated_at": "1970-01-01T00:00:00.000Z",
      "trigger": "schedule",
      "triggered_by": "string"
    }
  ],
  "cursor": "string"
}

Schemas​

ConfigType​

Type of configuration (e.g. deletion)

type ConfigType = "deletion"

JobStatus​

type JobStatus = "in_progress" | "success" | "failed"

JobTrigger​

type JobTrigger = "schedule" | "manual"

JobReportFormat​

type JobReportFormat = "csv"

JobReport​

type JobReport = {
  bucket?: string
  key?: string
  format?: "csv"
}

CreateJobRequest​

type CreateJobRequest = {
  type: "deletion"
  config_id: string
  scheduled_for: string // date
  status?: "in_progress" | "success" | "failed"
  started_at?: string // date-time
}

JobDetails​

Generic, type-specific job details payload (e.g. matched count, deleted count, failed count, etc.).

type JobDetails = Record<string, unknown>

UpdateJobRequest​

type UpdateJobRequest = {
  status?: "in_progress" | "success" | "failed"
  details?: Record<string, unknown>
  completed_at?: string // date-time
  error?: string
  report?: {
    bucket?: string
    key?: string
    format?: "csv"
  }
}

Job​

type Job = {
  id: string
  type: "deletion"
  config_id: string
  entity_schema: string
  scheduled_for: string // date
  status: "in_progress" | "success" | "failed"
  details?: Record<string, unknown>
  started_at?: string // date-time
  completed_at?: string // date-time
  error?: string
  report?: {
    bucket?: string
    key?: string
    format?: "csv"
  }
  created_at: string // date-time
  last_updated_at: string // date-time
  trigger?: "schedule" | "manual"
  triggered_by?: string
}

ListJobsResponse​

type ListJobsResponse = {
  jobs?: Array<{
    id: string
    type: "deletion"
    config_id: string
    entity_schema: string
    scheduled_for: string // date
    status: "in_progress" | "success" | "failed"
    details?: Record<string, unknown>
    started_at?: string // date-time
    completed_at?: string // date-time
    error?: string
    report?: {
      bucket?: { ... }
      key?: { ... }
      format?: { ... }
    }
    created_at: string // date-time
    last_updated_at: string // date-time
    trigger?: "schedule" | "manual"
    triggered_by?: string
  }>
  cursor?: string
}

JobReportUrlResponse​

type JobReportUrlResponse = {
  url?: string
  expires_in?: number
}

QueryFilterType​

type QueryFilterType = "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"

QueryFilter​

type QueryFilter = {
  type: "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"
  related_entity_schemas?: string[]
  lookback_period_days?: number
}

QueryConfig​

type QueryConfig = {
  saved_view_id: string
  include_deleted?: "true" | "false" | "only"
  filters?: Array<{
    type: "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"
    related_entity_schemas?: string[]
    lookback_period_days?: number
  }>
}

QueryEntitiesRequest​

type QueryEntitiesRequest = {
  saved_view_id: string
  include_deleted?: "true" | "false" | "only"
  filters?: Array<{
    type: "entity_workflows_only_in_closed_or_cancelled_status" | "no_related_entities" | "related_entities_all_in_closed_or_cancelled_status" | "related_entities_workflows_only_in_closed_or_cancelled_status" | "no_email_communication_since"
    related_entity_schemas?: string[]
    lookback_period_days?: number
  }>
  from?: number
  size?: number
  hydrate?: boolean
  fields?: string[]
}

QueryEntitiesResult​

type QueryEntitiesResult = {
  hits?: number
  results?: Record<string, unknown>[]
}

ConfigSchedule​

type ConfigSchedule = {
  frequency: "interval"
  interval_days: number
  start_date?: string // date
  end_date?: string // date
}

IntervalConfigSchedule​

type IntervalConfigSchedule = {
  frequency: "interval"
  interval_days: number
  start_date?: string // date
  end_date?: string // date
}

UpsertConfigRequest​

type UpsertConfigRequest = {
  type: "deletion"
  query: {
    saved_view_id: string
    include_deleted?: "true" | "false" | "only"
    filters?: Array<{
      type: { ... }
      related_entity_schemas?: { ... }
      lookback_period_days?: { ... }
    }>
  }
  schedule: {
    frequency: "interval"
    interval_days: number
    start_date?: string // date
    end_date?: string // date
  }
  relations_for_deletion?: "contact" | "file" | "opportunity" | "order" | "meter" | "ticket" | "message" | "account" | "submission" | "contract"[]
  enabled?: boolean
}

Config​

type Config = {
  id: string
  type: "deletion"
  entity_schema: string
  query: {
    saved_view_id: string
    include_deleted?: "true" | "false" | "only"
    filters?: Array<{
      type: { ... }
      related_entity_schemas?: { ... }
      lookback_period_days?: { ... }
    }>
  }
  schedule?: {
    frequency: "interval"
    interval_days: number
    start_date?: string // date
    end_date?: string // date
  }
  enabled?: boolean
  created_at?: string // date-time
  last_updated_at?: string // date-time
  next_run_at?: string // date
  relations_for_deletion?: "contact" | "file" | "opportunity" | "order" | "meter" | "ticket" | "message" | "account" | "submission" | "contract"[]
  last_run_at?: string // date-time
}

DeletionRelationEntitySchema​

type DeletionRelationEntitySchema = "contact" | "file" | "opportunity" | "order" | "meter" | "ticket" | "message" | "account" | "submission" | "contract"

ListConfigsResponse​

type ListConfigsResponse = {
  configs?: Array<{
    id: string
    type: "deletion"
    entity_schema: string
    query: {
      saved_view_id: { ... }
      include_deleted?: { ... }
      filters?: { ... }
    }
    schedule?: {
      frequency: { ... }
      interval_days: { ... }
      start_date?: { ... }
      end_date?: { ... }
    }
    enabled?: boolean
    created_at?: string // date-time
    last_updated_at?: string // date-time
    next_run_at?: string // date
    relations_for_deletion?: "contact" | "file" | "opportunity" | "order" | "meter" | "ticket" | "message" | "account" | "submission" | "contract"[]
    last_run_at?: string // date-time
  }>
  cursor?: string
}