Skip to main content

Targeting API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.targeting.changeCampaignStatus(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/targeting'

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

Operations​

Campaign

Campaign Delivery

Target

Campaign Recipient

Schemas

changeCampaignStatus​

Change the status of a campaign

POST /v1/campaign/{campaign_id}/status

const { data } = await client.changeCampaignStatus({
  campaign_id: 'example',
})
Response
{
  "campaign": {
    "_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
    "_org": "string",
    "_owners": [
      {
        "org_id": "123",
        "user_id": "123"
      }
    ],
    "_schema": "string",
    "_title": "string",
    "_tags": ["string"],
    "_created_at": "1970-01-01T00:00:00.000Z",
    "_updated_at": "1970-01-01T00:00:00.000Z",
    "_acl": {
      "view": ["org:456"],
      "edit": ["org:456"],
      "delete": ["org:456"]
    },
    "name": "string",
    "goal": "string",
    "status": "draft",
    "start_date": "string",
    "end_date": "string",
    "flow_id": "string",
    "job_id": "string",
    "target": {
      "$relation": [
        {
          "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
          "_tags": ["string"]
        }
      ]
    }
  }
}

getCampaignJobStatus​

Get the status of a campaign's automation job

GET /v1/campaign/{campaign_id}/job

const { data } = await client.getCampaignJobStatus({
  campaign_id: 'example',
})
Response
{
  "status": "queued",
  "execution_summary": [
    {
      "execution_id": "string",
      "execution_status": "string"
    }
  ]
}

getCampaignPortals​

Get portals usage info for a campaign

GET /v1/campaign/{campaign_id}/portals

const { data } = await client.getCampaignPortals({
  campaign_id: 'example',
})
Response
[
  {
    "portal": {
      "origin": "string",
      "domain": "string",
      "name": "string"
    },
    "widgets": [
      {
        "id": "string",
        "headline": {
          "en": "string",
          "de": "string"
        }
      }
    ]
  }
]

retriggerCampaignAutomations​

Retrigger automations for campaign recipients

POST /v1/campaign/{campaign_id}/automations:retrigger

const { data } = await client.retriggerCampaignAutomations(
  {
    campaign_id: 'example',
  },
  {
    recipient_ids: ['3fa85f64-5717-4562-b3fc-2c963f66afa6']
  },
)
Response
{
  "message": "string",
  "results": [
    {
      "recipient_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "result": "success",
      "execution_id": "string",
      "error": "string"
    }
  ]
}

matchCampaigns​

Match campaigns

POST /v1/campaign:match

const { data } = await client.matchCampaigns(
  null,
  {
    entity_refs: [
      {
        entity_id: 'b8c01433-5556-4e2b-aad4-6f5348d1df84',
        entity_schema: 'string'
      }
    ],
    campaign_ids: ['b8c01433-5556-4e2b-aad4-6f5348d1df84']
  },
)
Response
{
  "hits": 0,
  "results": [
    {
      "campaign": {
        "_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
        "_org": "string",
        "_owners": [
          {
            "org_id": "123",
            "user_id": "123"
          }
        ],
        "_schema": "string",
        "_title": "string",
        "_tags": ["string"],
        "_created_at": "1970-01-01T00:00:00.000Z",
        "_updated_at": "1970-01-01T00:00:00.000Z",
        "_acl": {
          "view": ["org:456"],
          "edit": ["org:456"],
          "delete": ["org:456"]
        },
        "name": "string",
        "goal": "string",
        "status": "draft",
        "start_date": "string",
        "end_date": "string",
        "flow_id": "string",
        "job_id": "string",
        "target": {
          "$relation": [
            {
              "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
              "_tags": ["string"]
            }
          ]
        }
      }
    }
  ]
}

matchTargets​

Match targets

POST /v1/target:match

const { data } = await client.matchTargets(
  null,
  {
    entity_refs: [
      {
        entity_id: 'b8c01433-5556-4e2b-aad4-6f5348d1df84',
        entity_schema: 'string'
      }
    ],
    target_ids: ['b8c01433-5556-4e2b-aad4-6f5348d1df84']
  },
)
Response
{
  "hits": 0,
  "results": [
    {
      "target": {
        "_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
        "_org": "string",
        "_owners": [
          {
            "org_id": "123",
            "user_id": "123"
          }
        ],
        "_schema": "string",
        "_title": "string",
        "_tags": ["string"],
        "_created_at": "1970-01-01T00:00:00.000Z",
        "_updated_at": "1970-01-01T00:00:00.000Z",
        "_acl": {
          "view": ["org:456"],
          "edit": ["org:456"],
          "delete": ["org:456"]
        },
        "name": "string",
        "description": "string",
        "entity_schema": "string",
        "entity_filters": {}
      }
    }
  ]
}

getTargetQueries​

Get target queries

POST /v1/target/queries

const { data } = await client.getTargetQueries(
  null,
  {
    target_ids: ['b8c01433-5556-4e2b-aad4-6f5348d1df84']
  },
)
Response
{
  "results": [
    {
      "target_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
      "query": "string",
      "error": "string"
    }
  ]
}

createRecipient​

Create a recipient associated with a campaign

POST /v1/campaign/{campaign_id}/recipient

const { data } = await client.createRecipient(
  {
    campaign_id: 'example',
  },
  {
    entity_id: 'b8c01433-5556-4e2b-aad4-6f5348d1df84',
    entity_schema: 'string',
    automation_status: 'pending',
    automation_execution_id: 'string'
  },
)
Response
{
  "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
  "entity_schema": "string",
  "title": "string",
  "automation_status": "pending",
  "automation_execution_id": "string",
  "portal_status": "sent",
  "portal_status_updated_at": "1970-01-01T00:00:00.000Z",
  "portal_state": {},
  "updated_at": "1970-01-01T00:00:00.000Z"
}

updateRecipient​

Update a recipient

PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}

const { data } = await client.updateRecipient(
  {
    campaign_id: 'example',
    recipient_id: 'example',
  },
  {
    automation_status: 'pending',
    automation_execution_id: 'string',
    portal_status: 'sent',
    portal_state: {}
  },
)
Response
{
  "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
  "entity_schema": "string",
  "title": "string",
  "automation_status": "pending",
  "automation_execution_id": "string",
  "portal_status": "sent",
  "portal_status_updated_at": "1970-01-01T00:00:00.000Z",
  "portal_state": {},
  "updated_at": "1970-01-01T00:00:00.000Z"
}

updateRecipientPortalStatus​

Update portal status for a campaign recipient

PATCH /v1/campaign/{campaign_id}/recipient/{recipient_id}/portal:status

const { data } = await client.updateRecipientPortalStatus(
  {
    campaign_id: 'example',
    recipient_id: 'example',
  },
  {
    status: 'sent'
  },
)
Response
{
  "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
  "entity_schema": "string",
  "title": "string",
  "automation_status": "pending",
  "automation_execution_id": "string",
  "portal_status": "sent",
  "portal_status_updated_at": "1970-01-01T00:00:00.000Z",
  "portal_state": {},
  "updated_at": "1970-01-01T00:00:00.000Z"
}

getRecipients​

Get campaign recipients

GET /v1/campaign/{campaign_id}/recipients

const { data } = await client.getRecipients({
  campaign_id: 'example',
  limit: 1,
  next: 'example',
  q: 'example',
  automation_status: 'example',
  portal_status: 'example',
})
Response
{
  "results": [
    {
      "entity_id": "b8c01433-5556-4e2b-aad4-6f5348d1df84",
      "entity_schema": "string",
      "title": "string",
      "automation_status": "pending",
      "automation_execution_id": "string",
      "portal_status": "sent",
      "portal_status_updated_at": "1970-01-01T00:00:00.000Z",
      "portal_state": {},
      "updated_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "next": "string",
  "total": 0
}

Schemas​

BaseError​

type BaseError = {
  status: number
  message: string
}

ServerError​

type ServerError = {
  status: number
  message: string
}

ClientError​

Describes the structure of a client error response, which can be one of several types:

  1. MessageError: Contains a 'message' field for general descriptive errors.
  2. CodeError: Contains a 'code' field for specific, machine-readable error codes.
  3. StatusedError: Contains 'error' and 'status' f
type ClientError = {
  message: string
} | {
  code: "CAMPAIGN_NOT_FOUND" | "CAMPAIGN_HAS_NO_TARGET" | "CAMPAIGN_HAS_NO_DELIVERY_METHOD" | "CAMPAIGN_HAS_JOB_IN_PROGRESS" | "CAMPAIGN_HAS_UNEXPECTED_STATUS" | "JOB_TOKEN_MISSING" | "TARGET_WITHOUT_FILTERS"
} | {
  error: string
  status: number
}

BaseUUID​

type BaseUUID = string // uuid

BaseNanoID​

type BaseNanoID = string

BaseTags​

type BaseTags = string[]

BaseRelation​

type BaseRelation = {
  $relation?: Array<{
    entity_id?: string // uuid
    _tags?: string[]
  }>
}

BaseSystemId​

type BaseSystemId = {
  _id: string // uuid
}

BaseEntityOwner​

The user / organization owning this entity.

Note: Owner implicitly has access to the entity regardless of ACLs.

type BaseEntityOwner = {
  org_id: string
  user_id?: string
}

BaseEntityAcl​

Access control list (ACL) for an entity. Defines sharing access to external orgs or users.

type BaseEntityAcl = {
  view?: string[]
  edit?: string[]
  delete?: string[]
}

BaseSystemFields​

type BaseSystemFields = {
  _id?: string // uuid
  _org?: string
  _owners?: Array<{
    org_id: string
    user_id?: string
  }>
  _schema?: string
  _title?: string
  _tags?: string[]
  _created_at?: string // date-time
  _updated_at?: string // date-time
  _acl?: {
    view?: string[]
    edit?: string[]
    delete?: string[]
  }
}

BaseSystemFieldsRequired​

type BaseSystemFieldsRequired = object

CampaignStatus​

type CampaignStatus = "draft" | "activating" | "active" | "inactive"

ExecutionSummaryItem​

type ExecutionSummaryItem = {
  execution_id?: string
  execution_status?: string
}

JobStatus​

type JobStatus = {
  status?: "queued" | "processing" | "finished" | "failed" | "cancelled" | "send_report"
  execution_summary?: Array<{
    execution_id?: string
    execution_status?: string
  }>
}

Campaign​

type Campaign = {
  _id?: string // uuid
  _org?: string
  _owners?: Array<{
    org_id: string
    user_id?: string
  }>
  _schema?: string
  _title?: string
  _tags?: string[]
  _created_at?: string // date-time
  _updated_at?: string // date-time
  _acl?: {
    view?: string[]
    edit?: string[]
    delete?: string[]
  }
  name?: string
  goal?: string
  status?: "draft" | "activating" | "active" | "inactive"
  start_date?: string // date
  end_date?: string // date
  flow_id?: string
  job_id?: string
  target?: {
    $relation?: Array<{
      entity_id?: { ... }
      _tags?: { ... }
    }>
  }
}

Target​

type Target = {
  _id?: string // uuid
  _org?: string
  _owners?: Array<{
    org_id: string
    user_id?: string
  }>
  _schema?: string
  _title?: string
  _tags?: string[]
  _created_at?: string // date-time
  _updated_at?: string // date-time
  _acl?: {
    view?: string[]
    edit?: string[]
    delete?: string[]
  }
  name?: string
  description?: string
  entity_schema?: string
  entity_filters?: Record<string, unknown>
}

MatchCampaignParams​

type MatchCampaignParams = {
  entity_refs: Array<{
    entity_id: string // uuid
    entity_schema: string
  }>
  campaign_ids: string // uuid[]
}

MatchTargetParams​

type MatchTargetParams = {
  entity_refs: Array<{
    entity_id: string // uuid
    entity_schema: string
  }>
  target_ids: string // uuid[]
}

GetTargetQueriesParams​

type GetTargetQueriesParams = {
  target_ids: string // uuid[]
}

TargetQueryResult​

type TargetQueryResult = {
  target_id: string // uuid
  query: string
  error?: string
}

AutomationStatus​

type AutomationStatus = "pending" | "in_progress" | "success" | "failed" | "cancelled"

PortalStatus​

type PortalStatus = "sent" | "seen" | "dismissed" | "clicked"

Recipient​

type Recipient = {
  entity_id?: string // uuid
  entity_schema?: string
  title?: string
  automation_status?: "pending" | "in_progress" | "success" | "failed" | "cancelled"
  automation_execution_id?: string
  portal_status?: "sent" | "seen" | "dismissed" | "clicked"
  portal_status_updated_at?: string // date-time
  portal_state?: Record<string, unknown>
  updated_at?: string // date-time
}

BaseRecipientPayload​

type BaseRecipientPayload = {
  entity_id: string // uuid
  entity_schema: string
}

AutomationRecipientPayload​

type AutomationRecipientPayload = {
  automation_status: "pending" | "in_progress" | "success" | "failed" | "cancelled"
  automation_execution_id: string
}

PortalRecipientPayload​

type PortalRecipientPayload = {
  portal_status: "sent" | "seen" | "dismissed" | "clicked"
  portal_state?: Record<string, unknown>
}

CreateRecipientPayload​

type CreateRecipientPayload = {
  entity_id: string // uuid
  entity_schema: string
  automation_status: "pending" | "in_progress" | "success" | "failed" | "cancelled"
  automation_execution_id: string
} | {
  entity_id: string // uuid
  entity_schema: string
  portal_status: "sent" | "seen" | "dismissed" | "clicked"
  portal_state?: Record<string, unknown>
} | {
  entity_id: string // uuid
  entity_schema: string
  automation_status: "pending" | "in_progress" | "success" | "failed" | "cancelled"
  automation_execution_id: string
  portal_status: "sent" | "seen" | "dismissed" | "clicked"
  portal_state?: Record<string, unknown>
}

UpdateRecipientPayload​

type UpdateRecipientPayload = {
  automation_status?: "pending" | "in_progress" | "success" | "failed" | "cancelled"
  automation_execution_id?: string
  portal_status?: "sent" | "seen" | "dismissed" | "clicked"
  portal_state?: Record<string, unknown>
}

RetriggerAutomationsRequest​

type RetriggerAutomationsRequest = {
  recipient_ids: string // uuid[]
}

RetriggerAutomationsResult​

type RetriggerAutomationsResult = {
  recipient_id: string // uuid
  result: "success" | "failure" | "not_found" | "invalid_status"
  execution_id?: string
  error?: string
}

UpdatePortalStatusRequest​

type UpdatePortalStatusRequest = {
  status: "sent" | "seen" | "dismissed" | "clicked"
}