API quickstart
Make your first API call: upload a file, run a tool, and download the result. A short walkthrough of the Operelio API, on Team and Agency.
By Operelio team · Updated July 2026
On this page5
What the API is for
The Operelio API does the same work as the dashboard, from your own scripts instead of the screen. You upload a file, run any tool on it (clean headers, deduplicate, format for a CRM, and the rest), and download the result, all over HTTP. It is the way to put Operelio inside something that already runs on its own: a nightly cleanup, an import pipeline, a script that preps a list before it reaches your CRM.
You do not need to be a developer to follow what each step does, but you (or someone on your team) will write a short script to run the calls. Everything the API can do, you can also do in the dashboard, so if you are not sure a job will work, try it once by hand first.
The API is on the Team and Agency plans. Every call needs an API key, so start there.
The four steps, in plain terms
Almost everything you do with the API is the same four steps, in order:
| Step | What it means |
|---|---|
| 1. Upload | Send your file to Operelio. You get back an id that points to it. |
| 2. Run a tool | Ask Operelio to run one tool on that file. This starts a job and returns a job id. A job is one unit of work, like "deduplicate this file". |
| 3. Wait for it | Jobs run in the background, so you check back every couple of seconds until the job says it has finished. Checking back like this is called polling. |
| 4. Download | Once the job is done it gives you an output file id. Download that, and you have your finished file. |
Jobs are asynchronous: step 2 returns straight away with a job id, before the work is done. That is why step 3 exists. Most jobs finish in under 10 seconds.
Run it yourself
Here is the whole loop end to end: upload a CSV, remove duplicate email addresses, wait for it to finish, and download the clean file. Swap op_your_api_key_here for your real key and contacts.csv for your file. The long ids in the responses are examples; use the ones your own calls return.
# 1. Upload the file (multipart form; the file goes in a field named "file")
curl -X POST https://operelio.com/api/v1/uploads \
-H "Authorization: Bearer op_your_api_key_here" \
-F "file=@contacts.csv"
# Response: { "id": "8f3b7a10-2c4d-4e6a-9b1f-0d5c8e2a7f34", "originalName": "contacts.csv", "sizeBytes": 12345 }
# 2. Run the Deduplicate tool on that file, matching on the email column
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
}
}'
# Response: { "id": "3a9c1e57-6b8d-42f0-9a3e-7c1b5d0f2e88", "toolType": "deduplicate", "status": "queued", "createdAt": "..." }
# 3. Check the job every 2 seconds until status is "completed"
curl https://operelio.com/api/v1/jobs/3a9c1e57-6b8d-42f0-9a3e-7c1b5d0f2e88 \
-H "Authorization: Bearer op_your_api_key_here"
# Response: {
# "id": "3a9c1e57-6b8d-42f0-9a3e-7c1b5d0f2e88",
# "status": "completed",
# "outputFileId": "b2e60d94-1f7a-4c83-8d05-6a9e3b1c7f42",
# "outputFileName": "contacts_deduplicated.csv"
# }
# 4. Download the finished file (-O -J saves it under the name Operelio gives it)
curl -O -J https://operelio.com/api/v1/files/b2e60d94-1f7a-4c83-8d05-6a9e3b1c7f42/download \
-H "Authorization: Bearer op_your_api_key_here"The id from each step feeds the next: the upload's id becomes inputFileId in step 2, the job's id is what you poll in step 3, and the job's outputFileId is what you download in step 4.
Where to go next
That loop is the whole model. From here, four guides cover the detail:
| Guide | What it covers |
|---|---|
| Authentication | Generate an API key, use it, revoke it, and keep it safe. |
| Endpoints | The full reference for every endpoint: what to send, what comes back. |
| Tools and configJson | Every tool you can run, and how to find the exact configJson each one needs. |
| Rate limits and Error handling | How many calls you get, and how to handle every error cleanly. |
Frequently asked questions
Do I need to be a developer to use the API?
To read this and understand what the API does, no. To run it in production, you or someone on your team will write a short script in whatever language you use. The examples here use curl, a command-line tool, so you can try a call by pasting it into a terminal before writing any code.
Is the API any different from the dashboard?
No. It runs the same tools with the same plan limits and the same job quota. A key is not a power-up; it is a different way to reach the same product. If you can do something in the dashboard, you can do it via the API, and the other way round.
Which plan do I need?
The API is on Team and Agency. Team includes 1,000 API calls a month; Agency includes 5,000. Free and Pro do not have API access.
Are jobs instant?
No, they run in the background. Creating a job returns right away with a job id and a status of "queued". You poll the job until its status is "completed" or "failed". Most jobs finish in under 10 seconds, so checking every 2 seconds is plenty.
Ready to get started?
Upload a file and run your first transformation. Free, no credit card required.