Operelio
Docs4 min read

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 Pro and Agency.

By Operelio team · Updated November 1, 2026

On this page5
  1. 1.What the API is for
  2. 2.The four steps, in plain terms
  3. 3.Run it yourself
  4. 4.Where to go next
  5. 5.Frequently asked questions

What the API is for

The Operelio API does the same work as the app, from your own scripts instead of the screen. You upload a file, run a tool on it (clean headers, deduplicate, format for a CRM, and most of the others) and download the result. You can also push to your CRM, read trails and leads, pause trails, keep your Do Not Contact list in step and ask Bridgeant, 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 app, so if you are not sure a job will work, try it once by hand first.

The API is on the Pro 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:

StepWhat it means
1. UploadSend your file to Operelio. You get back an id that points to it.
2. Run a toolAsk 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 itJobs 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. DownloadOnce 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. How long a job takes depends on the file and the queue.

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.

The full loop, start to finish
# 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 5 to 10 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.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.

Related

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 app?

Very little. It runs the same tools with the same plan limits and the same job quota, with two exceptions: Company Active Check is app only, and an API upload can be at most 4.5 MB per request. The Email Verifier's Full verification and refine also need a key made by someone who is still a member of the workspace. A key is not a power-up; it is a different way to reach the same product. Anything you can do through the API, you can also do in the app.

Which plan do I need?

The API is on Pro and Agency. Pro includes 1,000 API calls a month; Agency includes 5,000. Free and Starter do not have API access.

Do jobs finish right away?

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". Check every 5 to 10 seconds. A status check is a read, so it doesn't count toward your monthly API calls, but each key can make only 60 requests a minute.

NextAuthentication

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.

Start freeBrowse the developer docs