// documentation

Read your first
document in 60s.

One POST turns an identity card, a licence or an invoice into validated JSON. No SDK to install, no request to sign, no queue to poll.

Quickstart

Create an extractor in the app and describe the fields you want. Copy its key from the extractor page. Post a document to it. That is the whole setup.

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "image=@nic.jpg"

Authentication

Send the extractor key as a bearer token. Nothing to sign, no handshake. We keep only a SHA-256 hash of the key, so it cannot be read back out of our database, and a leaked key is fixed by regenerating it on the extractor page. The old one dies the moment you do.

Authorization: Bearer ov_live_9f2c…a71b

The key used to go in the URL path. That form is removed and now answers 410 with code key_in_url_removed. A URL is written down by every access log, proxy and browser history it passes through, and a header is not, so a credential in a path is a credential already copied somewhere you do not control. Your key has not changed and does not need regenerating, it moves, and the change is one line.

cURL

# REMOVED. Returns 410, code "key_in_url_removed".
curl -X POST "https://vision.olee.cc/api/v1/extract/YOUR_KEY" -F "image=@nic.jpg"

# Your key has not changed and does not need regenerating.
# It moves into a header:
curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "image=@nic.jpg"

Lock the key to your server. Each extractor can hold a list of IP addresses, on its page in the app. Leave it empty and any address with a valid key works. Put your server's address in it and every other address is refused with 403 before a read is spent, which is what makes a copied key worthless. Only do this if the calling server has a fixed address: most serverless hosts do not, and will lock themselves out.

Either way, one alert runs on every extractor and needs no setup. A day whose read count is far above its normal emails the owner. It blocks nothing. It exists so a key that leaked is noticed in a day rather than at the end of the month.

Call it from your server. A key in browser code is a key anyone can read and spend, in a header or in a URL. This endpoint answers no cross-origin browser call and there is no CORS switch, because there was no version of that which was safe. To scan from a browser, use the capture widget: your server trades the key for a token worth one scan, on one site, for fifteen minutes.

The request

POSThttps://vision.olee.cc/api/v1/extract

Send the bytes as multipart, or send a URL we fetch. Both take the same key.

cURL

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.lk/nic.jpg" }'

FieldTypeDescription

imagefileMultipart file, 4.45 MB or under. JPEG, PNG, WebP, TIFF, AVIF, GIF or HEIC. Rotated by EXIF and resized for you.

image_urlstringAn http or https URL we fetch, 4.45 MB or under. It must be publicly reachable: private and loopback addresses are refused, we do not follow redirects, and we give up after 20 seconds.

consentobjectOptional attestation, kept against the read. Required when the extractor is set to require it, and then a call without it is refused before we spend anything.

Consent goes in as a JSON object, or as flat form fields when you are already sending multipart.

cURL

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -F "image=@nic.jpg" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "consent_obtained=true" \
  -F "consent_reference=ticket-4471" \
  -F "consent_method=signed_form"

The response

The keys are the ones your extractor defines, in snake_case, and a field we could not find comes back null rather than a guess. A character nobody could read is a missing value, not an invented one. If your prompt asks for confidence per field, or for a name in three scripts, you get that shape instead. The envelope stays the same.

200 OK · 1.41s

{
  "success": true,
  "data": {
    "nic_number":    "200000112345",
    "full_name":     "DILSHAN ABEYGUNAWARDANA",
    "date_of_birth": "2000-01-01",
    "issue_date":    null
  }
}

A refusal carries a machine-readable code alongside the sentence.

JSON

{
  "error": "Read allowance exhausted. Buy extra reads or upgrade your plan.",
  "code": "quota_exhausted",
  "included": 1500,
  "used": 1500
}

Status codes

200SuccessThe document was read. Fields are in data.

400Nothing to readNo image field, no image_url, or the URL could not be fetched. No read spent.

401No key, or an invalid oneNo Authorization header, or the key in it matches no live extractor. A deleted extractor answers this too, even if its status still says approved.

410Key in the URLYou posted to /api/v1/extract/YOUR_KEY. That form is removed. Your key is fine and must not be regenerated, move it into an Authorization: Bearer header and post to /api/v1/extract. Code: key_in_url_removed.

403IP not allowedThis extractor has an IP allowlist and your address is not on it. The address we saw is in the response as caller_ip, so add that one on the extractor page, or clear the list to accept any address. Nothing is spent. Code: ip_not_allowed.

402Nothing left to spendAllowance used up, subscription lapsed, or the trial ended. The code field says which: quota_exhausted, subscription_lapsed, trial_exhausted, trial_expired.

403Not usableThe extractor is not live, or the account is not active.

422Consent missing, or no text foundMissing consent costs nothing, we stop before paying anyone. No text found spends the read, because we already did the work.

413File too bigOver 4.45 MB, or more than 24 megapixels. Nothing is spent. Save it as a JPEG or scan at a lower DPI, we shrink everything to 2000px anyway.

415Not an imageA PDF, or a file type we do not read. Nothing is spent. Send JPEG, PNG, WebP, TIFF, AVIF, GIF or HEIC.

429Too many at onceYour account is limited to one document every 2 seconds. Requests arriving faster are queued, not rejected; this only comes back when the queue is already deep. Retry-After tells you how long to wait. No read spent.

500We failedSomething on our side threw. The read is handed back to your allowance automatically.

503Could not reserve a readOur metering did not answer. Nothing was spent. Retry.

Webhooks

Turn one on for an extractor and every finished read is POSTed to your URL as well as returned in the response. The body carries the extractor id, the request id, the status, the same data and a timestamp.

HeaderMeaning

X-OleeVision-SignatureHMAC-SHA256 of the raw body, keyed with your webhook secret, hex encoded. Recompute it and compare before you trust the body.

X-OleeVision-Eventscan.completed

RetriesUp to three attempts, 10 second timeout each, half a second then two seconds apart. Every attempt is logged.

Limits and metering

LimitWhat it means

One readOne document answered. Playground tests count, because they are real extractions.

Our failuresRefunded. If we reserve a read and then fall over, it goes straight back to your allowance.

Blank documentsCharged. A page with nothing readable on it still costs us the read we did.

ThroughputOne document every 2 seconds per account, across the API and the Playground together. Send faster and the extras queue rather than fail. Only a queue deeper than about 10 seconds gets a 429, with a Retry-After header. Ask us if you need a higher rate.

File size4.45 MB and 24 megapixels, whichever you hit first. A document only needs about 1 MB to read perfectly, and a lossless PNG is the usual reason for going over, save as JPEG.

Image sizeResized so the longest side is 2000px before we read it. Send the original, we handle the rest.

Keeping imagesOff, all, or a percentage. Set it to 5 and about 5 scans in every 100 are kept at random, which is enough to spot-check your reads while we hold far fewer identity documents. Per extractor, under Data retention, and it applies from the next call.

PDFsNot accepted. Export the page as an image and send that. A PDF is billed by the page, so a long one would cost many times a single read while counting as one, and it also skips the checks every image gets.

Ready to build?

Grab a key and send your first document.

Get your key →

// documentation

Read your first
document in 60s.

One POST turns an identity card, a licence or an invoice into validated JSON. No SDK to install, no request to sign, no queue to poll.

Quickstart

Create an extractor in the app and describe the fields you want. Copy its key from the extractor page. Post a document to it. That is the whole setup.

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "image=@nic.jpg"

Authentication

Authorization: Bearer ov_live_9f2c…a71b

cURL

# REMOVED. Returns 410, code "key_in_url_removed".
curl -X POST "https://vision.olee.cc/api/v1/extract/YOUR_KEY" -F "image=@nic.jpg"

# Your key has not changed and does not need regenerating.
# It moves into a header:
curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "image=@nic.jpg"

The request

POSThttps://vision.olee.cc/api/v1/extract

Send the bytes as multipart, or send a URL we fetch. Both take the same key.

cURL

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.lk/nic.jpg" }'

FieldTypeDescription

imagefileMultipart file, 4.45 MB or under. JPEG, PNG, WebP, TIFF, AVIF, GIF or HEIC. Rotated by EXIF and resized for you.

image_urlstringAn http or https URL we fetch, 4.45 MB or under. It must be publicly reachable: private and loopback addresses are refused, we do not follow redirects, and we give up after 20 seconds.

consentobjectOptional attestation, kept against the read. Required when the extractor is set to require it, and then a call without it is refused before we spend anything.

Consent goes in as a JSON object, or as flat form fields when you are already sending multipart.

cURL

curl -X POST "https://vision.olee.cc/api/v1/extract" \
  -F "image=@nic.jpg" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "consent_obtained=true" \
  -F "consent_reference=ticket-4471" \
  -F "consent_method=signed_form"

The response

200 OK · 1.41s

{
  "success": true,
  "data": {
    "nic_number":    "200000112345",
    "full_name":     "DILSHAN ABEYGUNAWARDANA",
    "date_of_birth": "2000-01-01",
    "issue_date":    null
  }
}

A refusal carries a machine-readable code alongside the sentence.

JSON

{
  "error": "Read allowance exhausted. Buy extra reads or upgrade your plan.",
  "code": "quota_exhausted",
  "included": 1500,
  "used": 1500
}