FOR DEVELOPERS
The scanmydocz API
The server-side tools are HTTP endpoints. Post a file, get a file or some JSON back. There is no SDK to install and nothing to configure.
Getting a key
Sign in, then create a key. It is shown once and stored only as a hash, so if you lose it you revoke it and make another. We cannot recover it and neither can anyone who steals our database.
curl -X POST https://ocr.scanmydocz.com/v1/extract \
-H "Authorization: Bearer smd_live_..." \
-F file=@invoice.pdfA key is optional on every endpoint. Without one you get the same anonymous allowance a browser gets, counted by address. With one, the allowance is your account's.
What you can call
| Endpoint | Takes | Returns |
|---|---|---|
POST /v1/extract | a PDF | JSON: text, tables and page sizes |
POST /v1/sanitise | a PDF | a PDF with scripts and embedded files removed |
POST /v1/redact | a PDF, patterns or terms | a PDF with the words gone, not covered |
POST /v1/convert | a document, a target | the converted file |
POST /v1/ocr | an image | JSON: the text on it |
POST /v1/assistant/ask | a PDF, a question | JSON: an answer and the pages it cites |
Allowances
Counted per key, per endpoint, per hour. Going over returns
429 with a Retry-After header saying how long.
| Plan | Calls an hour, per endpoint |
|---|---|
| Free | 25 |
| Pro | 500 |
| Business | 5,000 |
A key can be given a lower ceiling than its plan, so one handed to a contractor or committed to a repository by accident cannot spend the whole month.
What we do with your files
The same as through the website: the file is processed and deleted 24 hours later. We do not train on your documents and we do not keep a record of what was in them. Usage is counted as a number of calls per endpoint per hour, not as a log of requests: a row per call would be a record of which documents you processed and when, kept for ever, and it is not worth having.
Errors
Every failure is a status code and a sentence in detail. The
ones worth handling:
401: the key is wrong or revoked. A bad key is never quietly treated as anonymous, because that turns a typo into a week of wondering why the allowance never went up.413: the file is over 100 MB.415: not a file that endpoint can open.422: the file was opened and could not be used. Usually a scan, which has no text in it. The message says which.429: over the allowance.Retry-Aftertells you when.
Questions: help@deplyra.com.