---
title: "Create a job"
method: POST
path: "/jobs"
tags: ["jobs"]
---

# Create a job

`POST /jobs`

## Headers

- `Authorization` string, required
- `X-Disable-Hooks` 'true', required

## Request body

- TypeJobsJobConfig — A single unit of work that a pipeline will execute
  - `type` 'file' | 'workbook' | 'sheet' | 'space' | 'document' | 'app' | 'agent' | 'autobuild' | 'onboarding', required — The type of job
  - `operation` string, required — the type of operation to perform on the data. For example, "export".
  - `source` string, required — The id of a file, workbook, sheet, or app
  - `destination` string — Workbook ID
  - `config` union
    - TypeJobsDeleteRecordsJobConfig — The configuration for a delete job
      - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
      - `filterField` string — Use this to narrow the valid/error filter results to a specific field
      - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
      - `searchField` string — Use this to narrow the searchValue results to a specific field
      - `q` string — FFQL query to filter records
      - `sheet` string, required — Sheet ID
      - `exceptions` TypeCommonsRecordId[] — List of record ids to exclude from deletion
      - `snapshotLabel` string — If specified, a snapshot will be generated with this label
    - TypeJobsFileJobConfig
      - `driver` 'csv', required — The driver to use for extracting data from the file
      - `options` object — The options to use for extracting data from the file
      - `detectedHeaderRow` integer — The row number of the header row detected at extraction time
    - TypeJobsPipelineJobConfig
      - `sourceSheetId` string, required — Sheet ID
      - `destinationSheetId` string, required — Sheet ID
      - `runbookId` string — Runbook ID
    - TypeJobsExportJobConfig
      - `options` TypeJobsExportOptions, required
        - `versionId` string — Version ID
        - `commitId` string — Commit ID
        - `sortField` string — Name of field by which to sort records
        - `sortDirection` 'asc' | 'desc' — Sort direction - asc (ascending) or desc (descending)
        - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
        - `filterField` string — Use this to narrow the valid/error filter results to a specific field
        - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
        - `searchField` string — Use this to narrow the searchValue results to a specific field
        - `q` string — The FFQL query to filter records
        - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
    - TypeJobsMutateJobConfig
      - `sheetId` string, required — Sheet ID
      - `mutateRecord` string, required — A JavaScript function that will be run on each record in the sheet, it should return a mutated record.
      - `mutationId` string — If the mutation was generated through some sort of id-ed process, this links this job and that process.
      - `snapshotLabel` string — If specified, a snapshot will be generated with this label
      - `snapshotId` string — The generated snapshotId will be stored here
      - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
      - `filterField` string — Use this to narrow the valid/error filter results to a specific field
      - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
      - `searchField` string — Use this to narrow the searchValue results to a specific field
      - `q` string
      - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
    - TypeJobsFindAndReplaceJobConfig
      - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
      - `filterField` string — Use this to narrow the valid/error filter results to a specific field
      - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
      - `searchField` string — Use this to narrow the searchValue results to a specific field
      - `q` string — The FFQL query to filter records
      - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
      - `find` union
        - string
        - integer
        - integer
        - number, double
        - boolean
        - string, date
        - string, date-time
        - string[]
      - `replace` union
        - string
        - integer
        - integer
        - number, double
        - boolean
        - string, date
        - string, date-time
        - string[]
      - `fieldKey` string, required — A unique key used to identify a field in a sheet
      - `snapshotLabel` string — If specified, a snapshot will be generated with this label
    - TypeJobsMappingProgramJobConfig
      - `sourceSheetId` string, required — Sheet ID
      - `destinationSheetId` string, required — Sheet ID
      - `mappingRules` object[], required
      - `canRecompute` boolean
    - TypeJobsAiGenerateBlueprintJobConfig
      - `spaceId` string, required — Space ID
      - `appId` string, required — App ID
    - TypeJobsAiGenerateSampleDataJobConfig
      - `spaceId` string, required — Space ID
      - `appId` string, required — App ID
    - TypeJobsAiGenerateBlueprintConstraintsJobConfig
      - `spaceId` string, required — Space ID
      - `workbookId` string, required — Workbook ID
    - TypeJobsAiGenerateConstraintJobConfig
      - `spaceId` string, required — Space ID
      - `constraints` TypePropertyStoredConstraint[], required
        - `validator` string, required — Must match the constraint validator name.
        - `version` integer — The version of the stored constraint to use. (Defaults to version 1.)
        - `description` string — A full description of what this constraint configuration does
        - `label` string — A short description of what this constraint constraint should do, example - values between 1 and 100
        - `config` unknown
      - `description` string — A description of what the constraint to be generated should do
    - TypeJobsAiRuleCreationJobConfig — Configuration for AI-powered rule creation jobs that generate or replace field constraints
      - `label` string — Display name for the rule to be created
      - `prompt` string, required — The natural language description of the rule to be created
      - `sheetId` string, required — Sheet ID
      - `fieldKey` string, required — The key of the field to create/update the rule for
      - `index` integer — To edit an existing rule, provide the index of the constraint in the constraints array for the field and that constraint will be replaced.
    - TypeJobsCaptureRoutineJobConfig
      - `sourceJobId` string, required — Pipeline Job ID
      - `runbookId` string, required — Runbook ID
    - TypeJobsRunRunbookJobConfig
      - `sourceSheetId` string, required — Sheet ID
      - `runbookId` string, required — Runbook ID
    - TypeJobsMappingFromPreprocessingJobConfig
      - `proposal` unknown, required
      - `mappingJobId` string, required — Pipeline Job ID
    - TypeJobsEmptyObject
    - TypeJobsAddRecordsToDataClipJobConfig — The configuration for an add records to DataClip job
      - `dataClipId` string, required — Data Clip ID
      - `sheetId` string, required — Sheet ID
    - TypeJobsUpdateDataClipResolutionsJobConfig — Configuration for a data clip resolution job
      - `clipId` string, required — Data Clip ID
      - `clippedSheetId` string, required — Sheet ID
      - `resolveTo` 'clip' | 'main' | 'snapshot', required
      - `removedFromMainResolution` 'ignore' | 'restore', required
      - `columnField` string, required — Optional. If provided, only this column will be resolved.
      - `columnValue` string, required — Optional. If provided, this value in the column will be replaced with the resolution target.
    - TypeJobsAgentExportJobConfig — The configuration for an agent export job
      - `exportType` 'AUTOBUILD_INLINED' | 'SYSTEM_COMBINED' | 'SOURCE', required — The different export type formats available.
    - TypeJobsAgentPromotionJobConfig — The configuration for an agent promotion job
      - `targetEnvironmentId` string, required — Environment ID
      - `spaceId` string, required — Space ID
    - TypeJobsCompanyResearchJobConfig — The configuration for a company research job
      - `onboardingId` string, required — The onboarding id
      - `url` string — The url of the company to research
      - `companyName` string — The name of the company to research
    - TypeJobsConfigureDemoJobConfig — The configuration for an onboarding job
      - `companyName` string, required — The name of the company
    - TypeJobsBulkMutateFlagsJobConfig — The configuration for a bulk flag mutation job
      - `workbookId` string, required — Workbook ID
      - `exceptions` string[] — Record IDs to exclude from the operation
      - `query` string — Query string to filter records
      - `filter` unknown
      - `filterField` string — Field to filter on
      - `searchValue` string — Value to search for
      - `searchField` string — Field to search in
      - `q` string — General search query
      - `ids` string[] — Specific record IDs to target
      - `snapshotLabel` string — Label for snapshot before mutation
      - `mutation` TypeJobsFlagMutationConfig, required — Configuration for flag mutation operations
        - `type` 'flag', required — The type of mutation (always "flag")
        - `operation` 'apply' | 'update' | 'delete' | 'replace', required — The type of flag operation to perform
        - `flag` TypeJobsFlagMutationConfigData, required — Flag data for mutation operations
          - `slug` string, required — The flag slug
          - `label` string — The flag label
          - `colorHex` string — The flag color in hex format
        - `flags` string[] — Array of flag slugs for delete operation
  - `trigger` 'manual' | 'immediate' — The type of trigger to use for this job
  - `status` 'created' | 'planning' | 'scheduled' | 'ready' | 'executing' | 'complete' | 'failed' | 'canceled' | 'waiting' — the status of the job
  - `progress` integer — the progress of the job. Whole number between 0 and 100
  - `fileId` string — File ID
  - `mode` 'foreground' | 'background' | 'toolbarBlocking' | 'hidden' — the mode of the job
  - `input` object — Input parameters for this job type.
  - `subject` union — Subject parameters for this job type
    - object
      - `type` 'resource', required — Discriminator value: resource
      - `id` string, required
    - object
      - `type` 'collection', required — Discriminator value: collection
      - `resource` string, required
      - `params` object
      - `query` object
  - `outcome` object — Outcome summary of job.
  - `result` object — Information computed during job execution can be stored here
  - `info` string — Current status of job in text
  - `managed` boolean — Indicates if Flatfile is managing the control flow of this job or if it is being manually tracked.
  - `environmentId` string — Environment ID
  - `part` integer — The part number of this job
  - `partData` object — The data for this part of the job
  - `partExecution` 'sequential' | 'parallel'
  - `parentId` string — Pipeline Job ID
  - `predecessorIds` TypeCommonsJobId[] — The ids of the jobs that must complete before this job can start
  - `metadata` object — Additional metadata for the job

## Response `200`

Response with status 200

- TypeJobsJobResponse
  - `data` TypeJobsJob, required — A single unit of work that will execute asynchronously
    - `type` 'file' | 'workbook' | 'sheet' | 'space' | 'document' | 'app' | 'agent' | 'autobuild' | 'onboarding', required — The type of job
    - `operation` string, required — the type of operation to perform on the data. For example, "export".
    - `source` string, required — The id of a file, workbook, sheet, or app
    - `destination` string — Workbook ID
    - `config` union
      - TypeJobsDeleteRecordsJobConfig — The configuration for a delete job
        - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
        - `filterField` string — Use this to narrow the valid/error filter results to a specific field
        - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
        - `searchField` string — Use this to narrow the searchValue results to a specific field
        - `q` string — FFQL query to filter records
        - `sheet` string, required — Sheet ID
        - `exceptions` TypeCommonsRecordId[] — List of record ids to exclude from deletion
        - `snapshotLabel` string — If specified, a snapshot will be generated with this label
      - TypeJobsFileJobConfig
        - `driver` 'csv', required — The driver to use for extracting data from the file
        - `options` object — The options to use for extracting data from the file
        - `detectedHeaderRow` integer — The row number of the header row detected at extraction time
      - TypeJobsPipelineJobConfig
        - `sourceSheetId` string, required — Sheet ID
        - `destinationSheetId` string, required — Sheet ID
        - `runbookId` string — Runbook ID
      - TypeJobsExportJobConfig
        - `options` TypeJobsExportOptions, required
          - `versionId` string — Version ID
          - `commitId` string — Commit ID
          - `sortField` string — Name of field by which to sort records
          - `sortDirection` 'asc' | 'desc' — Sort direction - asc (ascending) or desc (descending)
          - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
          - `filterField` string — Use this to narrow the valid/error filter results to a specific field
          - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
          - `searchField` string — Use this to narrow the searchValue results to a specific field
          - `q` string — The FFQL query to filter records
          - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
      - TypeJobsMutateJobConfig
        - `sheetId` string, required — Sheet ID
        - `mutateRecord` string, required — A JavaScript function that will be run on each record in the sheet, it should return a mutated record.
        - `mutationId` string — If the mutation was generated through some sort of id-ed process, this links this job and that process.
        - `snapshotLabel` string — If specified, a snapshot will be generated with this label
        - `snapshotId` string — The generated snapshotId will be stored here
        - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
        - `filterField` string — Use this to narrow the valid/error filter results to a specific field
        - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
        - `searchField` string — Use this to narrow the searchValue results to a specific field
        - `q` string
        - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
      - TypeJobsFindAndReplaceJobConfig
        - `filter` 'valid' | 'error' | 'all' | 'none' — Options to filter records
        - `filterField` string — Use this to narrow the valid/error filter results to a specific field
        - `searchValue` string — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
        - `searchField` string — Use this to narrow the searchValue results to a specific field
        - `q` string — The FFQL query to filter records
        - `ids` TypeCommonsRecordId[] — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
        - `find` union
          - string
          - integer
          - integer
          - number, double
          - boolean
          - string, date
          - string, date-time
          - string[]
        - `replace` union
          - string
          - integer
          - integer
          - number, double
          - boolean
          - string, date
          - string, date-time
          - string[]
        - `fieldKey` string, required — A unique key used to identify a field in a sheet
        - `snapshotLabel` string — If specified, a snapshot will be generated with this label
      - TypeJobsMappingProgramJobConfig
        - `sourceSheetId` string, required — Sheet ID
        - `destinationSheetId` string, required — Sheet ID
        - `mappingRules` object[], required
        - `canRecompute` boolean
      - TypeJobsAiGenerateBlueprintJobConfig
        - `spaceId` string, required — Space ID
        - `appId` string, required — App ID
      - TypeJobsAiGenerateSampleDataJobConfig
        - `spaceId` string, required — Space ID
        - `appId` string, required — App ID
      - TypeJobsAiGenerateBlueprintConstraintsJobConfig
        - `spaceId` string, required — Space ID
        - `workbookId` string, required — Workbook ID
      - TypeJobsAiGenerateConstraintJobConfig
        - `spaceId` string, required — Space ID
        - `constraints` TypePropertyStoredConstraint[], required
          - `validator` string, required — Must match the constraint validator name.
          - `version` integer — The version of the stored constraint to use. (Defaults to version 1.)
          - `description` string — A full description of what this constraint configuration does
          - `label` string — A short description of what this constraint constraint should do, example - values between 1 and 100
          - `config` unknown
        - `description` string — A description of what the constraint to be generated should do
      - TypeJobsAiRuleCreationJobConfig — Configuration for AI-powered rule creation jobs that generate or replace field constraints
        - `label` string — Display name for the rule to be created
        - `prompt` string, required — The natural language description of the rule to be created
        - `sheetId` string, required — Sheet ID
        - `fieldKey` string, required — The key of the field to create/update the rule for
        - `index` integer — To edit an existing rule, provide the index of the constraint in the constraints array for the field and that constraint will be replaced.
      - TypeJobsCaptureRoutineJobConfig
        - `sourceJobId` string, required — Pipeline Job ID
        - `runbookId` string, required — Runbook ID
      - TypeJobsRunRunbookJobConfig
        - `sourceSheetId` string, required — Sheet ID
        - `runbookId` string, required — Runbook ID
      - TypeJobsMappingFromPreprocessingJobConfig
        - `proposal` unknown, required
        - `mappingJobId` string, required — Pipeline Job ID
      - TypeJobsEmptyObject
      - TypeJobsAddRecordsToDataClipJobConfig — The configuration for an add records to DataClip job
        - `dataClipId` string, required — Data Clip ID
        - `sheetId` string, required — Sheet ID
      - TypeJobsUpdateDataClipResolutionsJobConfig — Configuration for a data clip resolution job
        - `clipId` string, required — Data Clip ID
        - `clippedSheetId` string, required — Sheet ID
        - `resolveTo` 'clip' | 'main' | 'snapshot', required
        - `removedFromMainResolution` 'ignore' | 'restore', required
        - `columnField` string, required — Optional. If provided, only this column will be resolved.
        - `columnValue` string, required — Optional. If provided, this value in the column will be replaced with the resolution target.
      - TypeJobsAgentExportJobConfig — The configuration for an agent export job
        - `exportType` 'AUTOBUILD_INLINED' | 'SYSTEM_COMBINED' | 'SOURCE', required — The different export type formats available.
      - TypeJobsAgentPromotionJobConfig — The configuration for an agent promotion job
        - `targetEnvironmentId` string, required — Environment ID
        - `spaceId` string, required — Space ID
      - TypeJobsCompanyResearchJobConfig — The configuration for a company research job
        - `onboardingId` string, required — The onboarding id
        - `url` string — The url of the company to research
        - `companyName` string — The name of the company to research
      - TypeJobsConfigureDemoJobConfig — The configuration for an onboarding job
        - `companyName` string, required — The name of the company
      - TypeJobsBulkMutateFlagsJobConfig — The configuration for a bulk flag mutation job
        - `workbookId` string, required — Workbook ID
        - `exceptions` string[] — Record IDs to exclude from the operation
        - `query` string — Query string to filter records
        - `filter` unknown
        - `filterField` string — Field to filter on
        - `searchValue` string — Value to search for
        - `searchField` string — Field to search in
        - `q` string — General search query
        - `ids` string[] — Specific record IDs to target
        - `snapshotLabel` string — Label for snapshot before mutation
        - `mutation` TypeJobsFlagMutationConfig, required — Configuration for flag mutation operations
          - `type` 'flag', required — The type of mutation (always "flag")
          - `operation` 'apply' | 'update' | 'delete' | 'replace', required — The type of flag operation to perform
          - `flag` TypeJobsFlagMutationConfigData, required — Flag data for mutation operations
            - `slug` string, required — The flag slug
            - `label` string — The flag label
            - `colorHex` string — The flag color in hex format
          - `flags` string[] — Array of flag slugs for delete operation
    - `trigger` 'manual' | 'immediate' — The type of trigger to use for this job
    - `status` 'created' | 'planning' | 'scheduled' | 'ready' | 'executing' | 'complete' | 'failed' | 'canceled' | 'waiting' — the status of the job
    - `progress` integer — the progress of the job. Whole number between 0 and 100
    - `fileId` string — File ID
    - `mode` 'foreground' | 'background' | 'toolbarBlocking' | 'hidden' — the mode of the job
    - `input` object — Input parameters for this job type.
    - `subject` union — Subject parameters for this job type
      - object
        - `type` 'resource', required — Discriminator value: resource
        - `id` string, required
      - object
        - `type` 'collection', required — Discriminator value: collection
        - `resource` string, required
        - `params` object
        - `query` object
    - `outcome` object — Outcome summary of job.
    - `result` object — Information computed during job execution can be stored here
    - `info` string — Current status of job in text
    - `managed` boolean — Indicates if Flatfile is managing the control flow of this job or if it is being manually tracked.
    - `environmentId` string — Environment ID
    - `part` integer — The part number of this job
    - `partData` object — The data for this part of the job
    - `partExecution` 'sequential' | 'parallel'
    - `parentId` string — Pipeline Job ID
    - `predecessorIds` TypeCommonsJobId[] — The ids of the jobs that must complete before this job can start
    - `metadata` object — Additional metadata for the job
    - `id` string, required — Pipeline Job ID
    - `createdBy` string, required — Actor ID
    - `createdAt` string, date-time, required — Date the item was created
    - `updatedAt` string, date-time, required — Date the item was last updated
    - `startedAt` string, date-time — the time that the job started at
    - `finishedAt` string, date-time — the time that the job finished at
    - `outcomeAcknowledgedAt` string, date-time — the time that the job's outcome has been acknowledged by a user
    - `spaceId` string — Space ID

---

[API](https://skmtc.net/flatfile/apis/api-reference.md) · [All operations](https://skmtc.net/flatfile/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flatfile/api-reference/revisions/9d3a9979cd96/schema)