Tools and configJson
Every tool you can run over the API, and the reliable way to find the exact configJson each one needs: capture it from the app, then run it at scale.
By Operelio team · Updated October 30, 2026
On this page8
How tools work on the API
Every job names a toolType, telling the API which tool to run, and a configJson, holding that tool's settings. The toolType is a short slug that matches the tool's page in the app: /app/tools/deduplicate runs toolType "deduplicate". The configJson is different for every tool, because every tool has different options.
You don't have to reverse-engineer configJson. Because the API runs exactly what the app runs, the safest way to get a working configJson is to set the tool up once in the app and copy what it sends. The discovery loop below shows how.
The tools you can run
Every toolType, the name it has in the app, whether it takes one file or several, and whether it can run in a batch:
| toolType | Name in the app | Files | Batch |
|---|---|---|---|
| excel_to_csv | Excel to CSV | One | Yes |
| csv_to_excel | CSV to Excel | One | Yes |
| clean_headers | Clean Headers | One | Yes |
| health_check | Data Health Check | One | Yes |
| deduplicate | Deduplicate | One | Yes |
| transpose | Transpose / Unpivot | One | Yes |
| find_replace | Find & Replace | One | No |
| filter_extract | Filter & Extract | One | No |
| column_manager | Column Manager | One | No |
| apply_fixes | Data Health Check (apply fixes) | One | No |
| crm_formatter | CRM Formatter | One | No |
| split | Split File | One | No |
| vlookup | Match & Pull Columns | Two | No |
| compare_files | Compare Files | Two | No |
| merge | Merge Files | Two or more | No |
| workflow | Workflow Builder | One | No |
| email_validate | Email Verifier & Finder | One | No |
Single-file tools take one inputFileId. Two-file tools (Match & Pull Columns, Compare) and Merge take a primary inputFileId plus the other file ids inside configJson. Workflow runs a chain you describe in configJson. Batch (the six "Yes" tools) is Agency only, and Excel to CSV needs an Excel file while CSV to Excel needs a CSV.
Find a tool's configJson from the app
This is the reliable way to get a correct configJson for any tool: run it once in the app with the browser's network inspector open, and copy the request it sends.
Open browser DevTools
In the app, open DevTools (Cmd+Option+I on a Mac, F12 on Windows) and go to the Network tab. Check "Preserve log" so the request stays visible after the page moves.
Set the tool up the way you want it
Open the tool, e.g. Deduplicate at /app/tools/deduplicate, and choose the exact options you'd use in production: match columns, rules, modes, whatever the tool offers.
Run the tool and find the request
In the Network tab, find the POST request to /api/jobs (or /api/jobs/batch for a batch tool). Open its Payload or Request tab. The body is JSON with inputFileId, toolType, and configJson.
Copy the configJson into your script
Lift the configJson value into your code. It is stable across runs, so the same configJson on a different file produces the same kind of output.
Run a tool once, capture its configJson, and you have a working recipe for it. The app is where you discover the shape; the API is where you run it at scale.
Worked example: deduplicate a file
Here is the deduplicate configJson from the quickstart on its own. Only the toolType and configJson change from tool to tool; the upload, poll, and download around them stay the same.
curl -X POST https://operelio.com/api/v1/jobs \
-H "Authorization: Bearer op_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"inputFileId": "8f3b7a10-2c4d-4e6a-9b1f-0d5c8e2a7f34",
"toolType": "deduplicate",
"configJson": {
"columns": ["email"],
"keepStrategy": "first",
"caseInsensitive": true,
"trimWhitespace": true
}
}'This configJson is what the Deduplicate page sends for "match on email, keep the first occurrence, ignore case and spacing". To see the exact shape for any other tool, capture it with the discovery loop above.
Common request shapes
A few patterns you'll reach for often:
| What you want | How to do it |
|---|---|
| Run one tool on one file | POST /uploads, then POST /jobs with inputFileId + toolType + configJson. |
| Run one tool on many files | POST /uploads for each file, then POST /jobs/batch with fileIds (array) + toolType + configJson. Agency only. |
| Run a two-file tool (Match & Pull Columns, Compare, Merge) | POST /uploads for each file, then POST /jobs with the primary inputFileId; pass the other file ids inside configJson. Capture the exact field names from the app. |
| Run a workflow chain | POST /jobs with toolType "workflow" and configJson: { "workflow": { "steps": [...], "outputFormat": "csv" } }. Build the workflow in the app first and capture the step shape. |
| Feed a file to a trail | POST /uploads with a folderId. No job to create: the trail watching that folder runs on the file, and you can follow it in Files, the trail's history, or Activity on Home, where the upload shows with your key's name. |
| Send a single lead to a trail | POST one JSON object to the folder's webhook address. It isn't under /api/v1, and it takes the folder's own secret, not an API key. The trail runs the lead on its own, and the call doesn't count toward your API calls. |
| Apply fixes from a Data Health Check | POST /jobs with toolType "apply_fixes" and the Data Health Check job's id in configJson.sourceJobId. Capped at 3 apply_fixes per Data Health Check. |
The Email Verifier by API
toolType "email_validate" runs the Email Verifier & Finder. Set configJson.runMode to "quick_clean" for the free screen: it uses no verify credits and runs on every plan. "full", which is what you get when you leave runMode out, verifies every address. To run the Finder again on a finished Email Verifier job, send configJson.mode "refine" with that job's id as baseJobId, and its output file as inputFileId.
Full verification and refine use the workspace's verify credits. They are held and charged to the person who made the key, so a member's credit limit counts them as theirs. Every mode uses one of the month's jobs, and POST /jobs counts as one API call.
Full verification and refine need a key made by someone who is still a member of the workspace. A key with no maker on record, or whose maker has left, gets 400 with code key_creator_required, and can run Quick clean only.
One rule for CRM Formatter
CRM Formatter (toolType "crm_formatter") can't be a step inside a workflow on the API. In the app, a workflow that ends in CRM Formatter opens its output in the CRM Formatter's mapping screen when it finishes; the workflow is one job, and formatting the file there is a second. An API call has no way to reach that screen. To format for a CRM from the API, run your workflow first, then send its output to a separate crm_formatter job. A workflow whose last step is crm_formatter is rejected with that guidance. Formatting for a custom, in-house CRM has its own guide.
Frequently asked questions
How do I figure out what configJson a tool needs?
Run the tool once in the app with the Network tab of DevTools open. When you run the tool (on Deduplicate, the button says Remove N duplicate rows, or Remove duplicates until the preview has a count), the app POSTs to /api/jobs; the request body's configJson is exactly what you send via the API. The discovery loop above walks through it.
Can I run several files through one tool in a single request?
Yes, for the six batchable tools (Excel to CSV, CSV to Excel, Clean Headers, Data Health Check, Deduplicate, Transpose), using POST /jobs/batch. Batch is on Agency, up to 50 files and 500,000 rows total. One batch is one API call, not one per file.
Do plan limits still apply when I call via the API?
Yes, exactly as in the app. A Find & Replace job via the API costs one job, and any feature that needs a higher plan in the app needs it via the API too.
Connect Operelio to your code or your assistant
Start free and add Operelio to Claude or ChatGPT today. The API and webhooks come with Pro.