> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://reference.flatfile.com/api-reference/jobs/create/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://reference.flatfile.com/_mcp/server. # Create a job POST https://api.x.flatfile.com/v1/jobs Content-Type: application/json Reference: https://reference.flatfile.com/api-reference/jobs/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a JobConfig. - `type` (enum, required) — The type of job - Allowed values: `file`, `workbook`, `sheet`, `space`, `document`, `app`, `agent`, `autobuild`, `onboarding` - `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, optional) — The id of the workbook where extracted file data will be sent - `config` (JobUpdateConfig, optional) - `trigger` (enum, optional) — the type of trigger to use for this job - Allowed values: `manual`, `immediate` - `status` (enum, optional) — the status of the job - Allowed values: `created`, `planning`, `scheduled`, `ready`, `executing`, `complete`, `failed`, `canceled`, `waiting` - `progress` (integer, optional) — the progress of the job. Whole number between 0 and 100 - `fileId` (string, optional) — File ID - `mode` (enum, optional) — the mode of the job - Allowed values: `foreground`, `background`, `toolbarBlocking`, `hidden` - `input` (map from string to any, optional) — Input parameters for this job type. - `subject` (JobSubject, optional) — Subject parameters for this job type. - `outcome` (map from string to any, optional) — Outcome summary of job. - `result` (map from string to any, optional) — Information computed during job execution can be stored here - `info` (string, optional) — Current status of job in text - `managed` (boolean, optional) — Indicates if Flatfile is managing the control flow of this job or if it is being manually tracked. - `environmentId` (string, optional) — The id of the environment this job belongs to - `part` (integer, optional) — The part number of this job - `partData` (map from string to any, optional) — The data for this part of the job - `partExecution` (enum, optional) — The execution mode for this part of the job - Allowed values: `sequential`, `parallel` - `parentId` (string, optional) — The id of the parent job - `predecessorIds` (list of string, optional) — The ids of the jobs that must complete before this job can start - `metadata` (map from string to any, optional) — Additional metadata for the job ## Response ### 200 - `data` (Job, required) — A single unit of work that will execute asynchronously ## Types ### JobUpdateConfig ### JobSubject Subject parameters for this job type - `type`: `resource` - `id` (string, required) - `type`: `collection` - `resource` (string, required) - `params` (map from string to any, optional) - `query` (map from string to any, optional) ### Job A single unit of work that will execute asynchronously - `createdAt` (datetime, required) — Date the item was created - `createdBy` (string, required) — The user, guest, or agent who created the job - `id` (string, required) — Pipeline Job ID - `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 - `type` (enum, required) — The type of job - Allowed values: `file`, `workbook`, `sheet`, `space`, `document`, `app`, `agent`, `autobuild`, `onboarding` - `updatedAt` (datetime, required) — Date the item was last updated - `config` (JobUpdateConfig, optional) - `destination` (string, optional) — The id of the workbook where extracted file data will be sent - `environmentId` (string, optional) — The id of the environment this job belongs to - `fileId` (string, optional) — File ID - `finishedAt` (datetime, optional) — the time that the job finished at - `info` (string, optional) — Current status of job in text - `input` (map from string to any, optional) — Input parameters for this job type. - `managed` (boolean, optional) — Indicates if Flatfile is managing the control flow of this job or if it is being manually tracked. - `metadata` (map from string to any, optional) — Additional metadata for the job - `mode` (enum, optional) — the mode of the job - Allowed values: `foreground`, `background`, `toolbarBlocking`, `hidden` - `outcome` (map from string to any, optional) — Outcome summary of job. - `outcomeAcknowledgedAt` (datetime, optional) — the time that the job's outcome has been acknowledged by a user - `parentId` (string, optional) — The id of the parent job - `part` (integer, optional) — The part number of this job - `partData` (map from string to any, optional) — The data for this part of the job - `partExecution` (enum, optional) — The execution mode for this part of the job - Allowed values: `sequential`, `parallel` - `predecessorIds` (list of string, optional) — The ids of the jobs that must complete before this job can start - `progress` (integer, optional) — the progress of the job. Whole number between 0 and 100 - `result` (map from string to any, optional) — Information computed during job execution can be stored here - `spaceId` (string, optional) — The id of the space this job belongs to - `startedAt` (datetime, optional) — the time that the job started at - `status` (enum, optional) — the status of the job - Allowed values: `created`, `planning`, `scheduled`, `ready`, `executing`, `complete`, `failed`, `canceled`, `waiting` - `subject` (JobSubject, optional) — Subject parameters for this job type. - `trigger` (enum, optional) — the type of trigger to use for this job - Allowed values: `manual`, `immediate` ### DeleteRecordsJobConfig The configuration for a delete job - `sheet` (string, required) — Sheet ID - `filter` (enum, optional) — Options to filter records (default=none) - Allowed values: `valid`, `error`, `all`, `none` - `filterField` (string, optional) — Use this to narrow the valid/error filter results to a specific field (Requires filter to be set) - `searchValue` (string, optional) — 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, optional) — Use this to narrow the searchValue results to a specific field - `q` (string, optional) — FFQL query to filter records - `exceptions` (list of string, optional) — List of record ids to exclude from deletion - `snapshotLabel` (string, optional) — If specified, a snapshot will be generated with this label ### FileJobConfig - `driver` (enum, required) — The driver to use for extracting data from the file - Allowed values: `csv` - `options` (map from string to any, optional) — The options to use for extracting data from the file - `detectedHeaderRow` (integer, optional) — The row number of the header row detected at extraction time ### PipelineJobConfig - `sourceSheetId` (string, required) — Sheet ID - `destinationSheetId` (string, required) — Sheet ID - `runbookId` (string, optional) — Runbook ID ### ExportJobConfig - `options` (ExportOptions, required) ### MutateJobConfig - `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, optional) — If the mutation was generated through some sort of id-ed process, this links this job and that process. - `snapshotLabel` (string, optional) — If specified, a snapshot will be generated with this label - `snapshotId` (string, optional) — The generated snapshotId will be stored here - `filter` (enum, optional) — Options to filter records - Allowed values: `valid`, `error`, `all`, `none` - `filterField` (string, optional) — Use this to narrow the valid/error filter results to a specific field - `searchValue` (string, optional) — 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, optional) — Use this to narrow the searchValue results to a specific field - `q` (string, optional) - `ids` (list of string, optional) — 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 ### FindAndReplaceJobConfig - `fieldKey` (string, required) — A unique key used to identify a field in a sheet - `filter` (enum, optional) — The filter to apply to the records - Allowed values: `valid`, `error`, `all`, `none` - `filterField` (string, optional) — The field to filter on - `searchValue` (string, optional) — The value to search for - `searchField` (string, optional) — The field to search for the search value in - `q` (string, optional) — The FFQL query to filter records - `ids` (list of string, optional) — 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` (CellValueUnion, optional) — A value to find for a given field in a sheet. Wrap the value in "" for exact match - `replace` (CellValueUnion, optional) — The value to replace found values with - `snapshotLabel` (string, optional) — If specified, a snapshot will be generated with this label ### MappingProgramJobConfig - `sourceSheetId` (string, required) — Sheet ID - `destinationSheetId` (string, required) — Sheet ID - `mappingRules` (list of map from string to any, required) - `canRecompute` (boolean, optional) ### AiGenerateBlueprintJobConfig - `spaceId` (string, required) — Space ID - `appId` (string, required) — App ID ### AiGenerateSampleDataJobConfig - `spaceId` (string, required) — Space ID - `appId` (string, required) — App ID ### AiGenerateBlueprintConstraintsJobConfig - `spaceId` (string, required) — Space ID - `workbookId` (string, required) — Workbook ID ### AiGenerateConstraintJobConfig - `spaceId` (string, required) — Space ID - `constraints` (list of StoredConstraint, required) - `description` (string, optional) — A description of what the constraint to be generated should do ### AiRuleCreationJobConfig Configuration for AI-powered rule creation jobs that generate or replace field constraints - `prompt` (string, required) — The natural language description of the rule to be created - `sheetId` (string, required) — The ID of the sheet containing the field to create/update the rule for - `fieldKey` (string, required) — The key of the field to create/update the rule for - `label` (string, optional) — Display name for the rule to be created - `index` (integer, optional) — To edit an existing rule, provide the index of the constraint in the constraints array for the field and that constraint will be replaced. ### CaptureRoutineJobConfig - `sourceJobId` (string, required) — Pipeline Job ID - `runbookId` (string, required) — Runbook ID ### RunRunbookJobConfig - `sourceSheetId` (string, required) — Sheet ID - `runbookId` (string, required) — Runbook ID ### MappingFromPreprocessingJobConfig - `proposal` (any, required) - `mappingJobId` (string, required) — Pipeline Job ID ### EmptyObject ### AddRecordsToDataClipJobConfig The configuration for an add records to DataClip job - `dataClipId` (string, required) — Data Clip ID - `sheetId` (string, required) — Sheet ID ### UpdateDataClipResolutionsJobConfig Configuration for a data clip resolution job - `clipId` (string, required) — The ID of the data clip to resolve - `clippedSheetId` (string, required) — The ID of the sheet that contains the data clip - `resolveTo` (enum, required) - Allowed values: `clip`, `main`, `snapshot` - `removedFromMainResolution` (enum, required) - Allowed values: `ignore`, `restore` - `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. ### AgentExportJobConfig The configuration for an agent export job - `exportType` (enum, required) — The different export type formats available. - Allowed values: `AUTOBUILD_INLINED`, `SYSTEM_COMBINED`, `SOURCE` ### AgentPromotionJobConfig The configuration for an agent promotion job - `targetEnvironmentId` (string, required) — The environment ID where the agent should be promoted - `spaceId` (string, required) — The space ID where the agent is being promoted from ### CompanyResearchJobConfig The configuration for a company research job - `onboardingId` (string, required) — The onboarding id - `url` (string, optional) — The url of the company to research - `companyName` (string, optional) — The name of the company to research ### ConfigureDemoJobConfig The configuration for an onboarding job - `companyName` (string, required) — The name of the company ### BulkMutateFlagsJobConfig The configuration for a bulk flag mutation job - `workbookId` (string, required) — The workbook to perform flag mutations on - `mutation` (FlagMutationConfig, required) — The flag mutation configuration - `exceptions` (list of string, optional) — Record IDs to exclude from the operation - `query` (string, optional) — Query string to filter records - `filter` (any, optional) — Filter object to apply to records - `filterField` (string, optional) — Field to filter on - `searchValue` (string, optional) — Value to search for - `searchField` (string, optional) — Field to search in - `q` (string, optional) — General search query - `ids` (list of string, optional) — Specific record IDs to target - `snapshotLabel` (string, optional) — Label for snapshot before mutation ### ExportOptions - `versionId` (string, optional) — Deprecated, use `commitId` instead - `commitId` (string, optional) — If provided, the snapshot version of the workbook will be used for the export - `sortField` (string, optional) — The field to sort the records on - `sortDirection` (enum, optional) — The direction to sort the records - Allowed values: `asc`, `desc` - `filter` (enum, optional) — The filter to apply to the records - Allowed values: `valid`, `error`, `all`, `none` - `filterField` (string, optional) — The field to filter on - `searchValue` (string, optional) — The value to search for - `searchField` (string, optional) — The field to search for the search value in - `q` (string, optional) — The FFQL query to filter records - `ids` (list of string, optional) — 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 ### CellValueUnion ### StoredConstraint - `validator` (string, required) — Must match the constraint validator name. - `version` (integer, optional) — The version of the stored constraint to use. (Defaults to version 1.) - `description` (string, optional) — A full description of what this constraint configuration does - `label` (string, optional) — A short description of what this constraint constraint should do, example - values between 1 and 100 - `config` (any, optional) ### FlagMutationConfig Configuration for flag mutation operations - `type` ("flag", required) — The type of mutation (always "flag") - `operation` (enum, required) — The operation to perform - Allowed values: `apply`, `update`, `delete`, `replace` - `flag` (FlagMutationConfigData, required) — The flag data for the operation - `flags` (list of string, optional) — Array of flag slugs for delete operation ### FlagMutationConfigData Flag data for mutation operations - `slug` (string, required) — The flag slug - `label` (string, optional) — The flag label - `colorHex` (string, optional) — The flag color in hex format ## Examples **Request** ```json { "type": "workbook", "operation": "submitAction", "source": "us_wb_YOUR_ID" } ``` **Response** ```json { "data": { "createdAt": "2023-10-30T20:04:28.556Z", "createdBy": "us_usr_YOUR_ID", "id": "us_jb_YOUR_ID", "operation": "submitAction", "source": "us_wb_YOUR_ID", "type": "workbook", "updatedAt": "2023-10-30T20:04:32.075Z", "config": {}, "destination": "us_wb_YOUR_ID", "environmentId": "us_env_YOUR_ID", "fileId": "us_fl_YOUR_ID", "finishedAt": "2023-10-30T20:04:32.074Z", "info": "Starting job to submit action to webhook.site", "input": {}, "managed": true, "mode": "foreground", "outcome": { "message": "Data was successfully submitted to Webhook.site. Go check it out at https://example.site/example." }, "progress": 100, "spaceId": "us_sp_YOUR_ID", "startedAt": "2023-10-30T20:04:29.453Z", "status": "complete", "subject": { "type": "resource", "id": "us_wb_YOUR_ID" }, "trigger": "immediate" } } ``` **SDK Code** ```python Example0 import requests url = "https://api.x.flatfile.com/v1/jobs" payload = { "type": "workbook", "operation": "submitAction", "source": "us_wb_YOUR_ID" } headers = { "X-Disable-Hooks": "true", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript Example0 import { FlatfileClient } from "@flatfile/api"; const client = new FlatfileClient({ token: "YOUR_TOKEN" }); await client.jobs.create({ type: "workbook", operation: "submitAction", source: "us_wb_YOUR_ID" }); ``` ```go Example0 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.x.flatfile.com/v1/jobs" payload := strings.NewReader("{\n \"type\": \"workbook\",\n \"operation\": \"submitAction\",\n \"source\": \"us_wb_YOUR_ID\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Disable-Hooks", "true") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example0 require 'uri' require 'net/http' url = URI("https://api.x.flatfile.com/v1/jobs") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Disable-Hooks"] = 'true' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"type\": \"workbook\",\n \"operation\": \"submitAction\",\n \"source\": \"us_wb_YOUR_ID\"\n}" response = http.request(request) puts response.read_body ``` ```java Example0 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.x.flatfile.com/v1/jobs") .header("X-Disable-Hooks", "true") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"type\": \"workbook\",\n \"operation\": \"submitAction\",\n \"source\": \"us_wb_YOUR_ID\"\n}") .asString(); ``` ```php Example0 request('POST', 'https://api.x.flatfile.com/v1/jobs', [ 'body' => '{ "type": "workbook", "operation": "submitAction", "source": "us_wb_YOUR_ID" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'X-Disable-Hooks' => 'true', ], ]); echo $response->getBody(); ``` ```csharp Example0 using RestSharp; var client = new RestClient("https://api.x.flatfile.com/v1/jobs"); var request = new RestRequest(Method.POST); request.AddHeader("X-Disable-Hooks", "true"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"type\": \"workbook\",\n \"operation\": \"submitAction\",\n \"source\": \"us_wb_YOUR_ID\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example0 import Foundation let headers = [ "X-Disable-Hooks": "true", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "type": "workbook", "operation": "submitAction", "source": "us_wb_YOUR_ID" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.x.flatfile.com/v1/jobs")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```