The Flatfile platform encompasses a comprehensive suite of tools. Firstly, it offers a REST API, which can be accessed through the , empowering users to effortlessly manipulate resources. Additionally, an Event bus is available for seamless subscription to resource-related notifications.

To simplify the process of utilizing the Flatfile API, the Flatfile PubSub Client serves as a lightweight wrapper. It enables developers to seamlessly trigger API calls upon receiving Events from any PubSub driver, thus ensuring a smooth and streamlined integration process.

The anatomy of an Event

Flatfile Events adhere to a standardized structure, and Event listeners have the flexibility to handle Events within Flatfile using any of the following syntaxes.

See API Reference

Using Events

Once an Event is received, it is routed to any awaiting listeners which are added with addEventListener() or its alias on().

An Event context is passed to an EventFilter

export type EventFilter = Record<string, Arrayable<string>>;

// example event context
{
  context: {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "actorId": "us_ag_1234"
  }
}

Building with events

By leveraging the robust capabilities of our @flatfile/listener library, we can seamlessly intercept any Event and execute a callback function based on the values encapsulated within the Event itself.

listener.on(
  "job:ready",
  { job: "space:configure" },
  async (event: FlatfileEvent) => {
    //do something here
  }
);

Event Topics

Utilize the reference provided by the response of each Event topic to determine the desired outcome or plan subsequent actions accordingly.

Workbook

workbook:created

workbook:created
readonly

Called when a new workbook is created.

{
  "domain": "workbook",
  "topic": "workbook:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  }
}

workbook:updated

workbook:updated
readonly

Called when workbook metadata is updated. For example, updating the name of a workbook. Adding data to a workbook does not emit this Event.

{
  "domain": "workbook",
  "topic": "workbook:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_ag_1234"
  }
}

workbook:deleted

workbook:deleted
readonly

Called when a workbook is deleted.

{
  "domain": "workbook",
  "topic": "workbook:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_ag_1234"
  }
}

workbook:expired

workbook:expired
readonly

Called when a workbook is expired.

{
  "domain": "workbook",
  "topic": "workbook:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234"
  }
}

Document

document:created

document:created
readonly

Called when a document is created on a workbook.

{
  "domain": "document",
  "topic": "document:created",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}

document:updated

document:updated
readonly

Called when a document is updated on a workbook.

{
  "domain": "document",
  "topic": "document:updated",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}

document:deleted

document:deleted
readonly

Called when a document is deleted on a workbook.

{
  "domain": "document",
  "topic": "document:deleted",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}

Sheet

sheet:updated

sheet:updated
readonly

Called when a sheet is updated. For example, running sheet level validations. Adding data to a sheet does not emit this event.

{
  "domain": "sheet",
  "topic": "sheet:updated",
  "context": {
    "slugs": { "sheet": "contacts" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "contacts",
    "actorId": "us_ag_XRGmuGfL"
  }
}

sheet:deleted

sheet:deleted
readonly

Called when a sheet is deleted.

{
  "domain": "sheet",
  "topic": "sheet:deleted",
  "context": {
    "slugs": { "sheet": "contacts" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "contacts",
    "actorId": "us_ag_XRGmuGfL"
  }
}

Snapshot

snapshot:created

snapshot:created
readonly

Called when a snapshot is created of the sheet. This can be triggered by the API endpoint or when AI Assist is used to modify a sheet.

{
  "domain": "sheet",
  "topic": "snapshot:created",
  "context": {
    "appId": "us_app_1234",
    "accountId": "us_acc_1234",
    "snapshotId": "us_ss_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "actorId": "us_ag_XRGmuGfL"
  }
}

Record

commit:created

commit:created
readonly

Commits are created when a cell in a Record (which is in a Sheet) is created or updated.

{
  "domain": "workbook",
  "topic": "commit:created",
  "context": {
    "slugs": { "sheet": "MasterWorkbook/Data" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "MasterWorkbook/Data",
    "versionId": "us_vr_1234",
    "actorId": "us_usr_1234"
  }
}

commit:completed

commit:completed
readonly

This only runs when trackChanges is enabled on the workbook. This event fires when a commit has completed and any record changes have finished.

{
  "domain": "workbook",
  "topic": "commit:completed",
  "context": {
    "appId": "us_app_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "versionId": "us_vr_1234",
    "actorId": "us_usr_1234",
    "commitId": "us_vr_1234"
  }
}

layer:created

layer:created
readonly

Called when a new layer is created within a commit. A layer is a programmatically generated artifact of a commit. For example, when a data hook or formatting rule applies formatting or validation automatically. Layers cannot be updated or deleted, but you can ignore them to see the original source data.

File Upload

file:created

file:created
readonly

Called when a file upload begins or a new file is created.

{
  "domain": "file",
  "topic": "file:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_usr_1234"
  }
}

file:updated

file:updated
readonly

Called when a file is updated. For example, when a file has been extracted into a workbook.

{
  "domain": "file",
  "topic": "file:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_acc_1234"
  },
  "payload": {
    "status": "complete",
    "workbookId": "us_wb_1234"
  }
}

file:deleted

file:deleted
readonly

Called when a file is deleted.

{
  "domain": "file",
  "topic": "file:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_usr_1234"
  }
}

file:expired

file:expired
readonly

Called when a file is expired.

{
  "domain": "file",
  "topic": "file:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234"
  }
}

Jobs

job:created

job:created
readonly

Called when a new job is first created. Some jobs will enter an optional planning state at this time. A job with ‘immediate’ set to true will skip the planning step and transition directly to ‘ready.’

{
  "domain": "job", //job domain
  "topic": "job:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "created",
    "operation": "configure"
  }
}

job:ready

job:ready
readonly

Called when a new job is ready to execute. Either the job has a complete plan of work or the job is configured to not need a plan. This is the only event most job implementations will care about. Once a ready job is acknowledged by a listener, it transitions into an executing state.

{
  "domain": "job", //job domain
  "topic": "job:ready",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "ready",
    "operation": "configure"
  }
}

job:updated

job:updated
readonly

Called when a job is updated. For example, when a listener updates the state or progress of the job. The event will emit many times as the listener incrementally completes work and updates the job.

{
  "domain": "job", //job domain
  "topic": "job:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "ready",
    "operation": "configure"
  }
}

job:completed

job:completed
readonly

Called when a job has completed.

{
  "domain": "job", //job domain
  "topic": "job:completed",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": "Configuring space...",
    "domain": "space", //event domain
    "status": "complete",
    "operation": "configure"
  }
}

job:outcome-acknowledged

job:outcome-acknowledged
readonly

Called to trigger workflow actions after the user has acknowledged that the job has completed or failed. Background jobs will skip this step.

{
  "domain": "job", //job domain
  "topic": "job:outcome-acknowledged",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "sheet:buildSheet", //this is domain:operation
    "info": null,
    "domain": "sheet", //event domain
    "status": "failed",
    "operation": "buildSheet"
  }
}

job:failed

job:failed
readonly

Called when a job fails.

{
  "domain": "job", //job domain
  "topic": "job:failed",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "sheet:buildSheet", //this is domain:operation
    "info": null,
    "domain": "sheet", //event domain
    "status": "failed",
    "operation": "buildSheet"
  }
}

job:deleted

job:deleted
readonly

Called when a job is deleted.

{
  "domain": "job",
  "topic": "job:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_ag_1234"
  }
}

Agents

agent:created

agent:created
readonly

Called when a new agent is deployed.

{
  "domain": "space",
  "topic": "agent:created",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234"
  }
}

agent:updated

agent:updated
readonly

Called when an agent is updated.

{
  "domain": "space",
  "topic": "agent:updated",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "agentId": "us_ag_1234"
  }
}

agent:deleted

agent:deleted
readonly

Called when an agent is deleted.

{
  "domain": "space",
  "topic": "agent:deleted",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234"
    "agentId": "us_ag_1234"
  }
}

Space

space:created

space:created
readonly

Called when a new space is created.

{
  "domain": "space",
  "topic": "space:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}

space:updated

space:updated
readonly

Called when a space is updated.

{
  "domain": "space",
  "topic": "space:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}

space:deleted

space:deleted
readonly

Called when a space is deleted.

{
  "domain": "space",
  "topic": "space:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_usr_1234"
  }
}

space:expired

space:expired
readonly

Called when a space is expired.

{
  "domain": "space",
  "topic": "space:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234"
  }
}

space:archived

space:archived
readonly

Called when a space is archived.

{
  "domain": "space",
  "topic": "space:archived",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}

space:guestAdded

space:guestAdded
readonly

Called when a guest is added.

{
  "domain": "space",
  "topic": "space:guestAdded",
  "context": {
    "actorId": "us_usr_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}

space:guestRemoved

space:guestRemoved
readonly

Called when a guest’s access is revoked from a space.

{
  "domain": "space",
  "topic": "space:guestRemoved",
  "context": {
    "actorId": "us_usr_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}

Secret

secret:created

secret:created
readonly

Called when a new secret is created.

{
  "domain": "secret",
  "topic": "secret:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}

secret:updated

secret:updated
readonly

Called when a secret is updated.

{
  "domain": "secret",
  "topic": "secret:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}

secret:deleted

secret:deleted
readonly

Called when a secret is deleted.

{
  "domain": "secret",
  "topic": "secret:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}