Fill forms from your application or AI agent

Access and credits

First API-key activation consumes 1 credit from your existing balance, after explicit account approval. It does not add a credit. Replacement and revocation are free. Each completed form consumes 1 further credit. Status checks, edits and repeat downloads of the same job and target are included, within processing limits. Included account credits can be used for activation.

USD prepaid credit pricing: $1 through the first 100 paid uses, then $0.20 each. No subscription. A new account has two included credits total, inclusive of any prior guest use. Read the current balance and quote before starting or exporting. A key never authorizes owner reporting.

Connect an agent

1. POST /api/v1/form-filler/authorizations with {"name":"My assistant","intent":"form_completion"}. Keep the returned secret private.
2. Show the returned authorizationUrl to the customer. They sign in or verify a new account, review the integration's access, and explicitly authorize the one-credit activation. If needed, they purchase credits on My account and return to the authorization page. Unapproved requests expire after 15 minutes. An approved request can be renewed using its secret for up to 24 hours; starting checkout preserves that window. After that, start a new request: confirmed funds stay on the same account.
3. POST /authorizations/{id}/token with {"secret":"..."} every five seconds. authorization_pending means the customer is still acting. credits_required means account authorization was approved but the requested task needs funding. Read funding.suggestedTopUpCents: a new zero-balance customer needs two credits for activation plus one form, available in one $2 checkout. POST /authorizations/{id}/checkout with secret, cents and requestKey to obtain a customer-approved payment link. POST /authorizations/{id}/payments/{orderId} with secret checks its ledger status. Continue polling token; after verified funding, the explicitly approved activation consumes one credit and authorized includes the key, delivered once. Never put either secret in a URL, logs, frontend code or source control.
4. If delivery is lost, the customer can revoke the issued key and authorize a replacement at no additional activation charge. The API cannot replace human email verification or payment approval.

Developers can instead sign in and create a key directly. Name it and select full workflow or read-only access. Up to five active keys per account; revoke obsolete keys before rotating.

Make the first request

Base URL: https://aideify.com/api/v1/form-filler. Server-to-server HTTPS, bearer authentication, no cross-origin browser client or third-party request proxy.

export AIDEIFY_API_KEY='your-key'
curl https://aideify.com/api/v1/form-filler/balance \
  -H "Authorization: Bearer $AIDEIFY_API_KEY"

curl https://aideify.com/api/v1/form-filler/jobs \
  -H "Authorization: Bearer $AIDEIFY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a-unique-application-id' \
  -d '{}'

Creation returns 201 with a job ID, revisions and links. Reuse the same creation idempotency key to recover that job; do not create another job to retry a completion. A job ID or hosted-review URL never grants access by itself.

From documents to PDF

1. POST /jobs/{id}/uploads as multipart: revision, packageRevision, one target PDF or JPEG/PNG/WebP image, and repeated sources file parts. Set allowRemote=false for server-local processing. Extraction may happen during upload; keep the returned revisions. Uploads are not billed separately.
2. POST /jobs/{id}/process with both revisions and allowRemote. HTTP 202 means accepted, not complete. Poll /jobs/{id} or /progress every two seconds until state review or failed. Jobs continue without an open browser.
3. Inspect fields, including labels, values, confidence, evidence and placement. PATCH /jobs/{id}/review with current revisions, fieldId, action edit and a string value. Other actions include approve, omit, acknowledge, keep, suggestion and placement; see the reference. Every successful change returns updated revisions. Flat/scanned fields need confirmed placement before approval. Resolve pending source changes and conflicts explicitly. Manage individual source removals and exclusions in the app workspace.
4. Approve the answers you want included. Missing/unapproved fields may remain blank. Alternatively direct the customer to the returned hosted-review link; they must sign in to the owning account. No key is placed in that link.
5. POST /jobs/{id}/exports with both revisions, the latest completionPriceCents as expectedCents, and allowPartial=true if leaving fields blank. This creates the PDF and consumes 1 credit once. Failures release reservations; an unchanged job/target does not consume another credit on retry.
6. GET /jobs/{id}/output?revision=... with your bearer key. The response is PDF bytes. DELETE /jobs/{id} when the customer requests deletion.

To try the sample workflow, POST /jobs/{id}/sample with {} instead of uploading. Sample completion is not charged. Create a new job to use real documents afterward.

Download the Python workflow client. It supports the authorization handoff, upload, polling, reviewed completion and download; it uses only public HTTP access. If more credits are needed after activation, it offers a payment link and waits for confirmation before continuing. Use --job with the printed ID to resume an existing application without uploading or creating it again.

Payment and continuation

GET /balance returns remaining/used credits and the next credit price. GET /usage returns up to 50 recent completed credit uses, including API activation, channel (unknown for legacy jobs), cost in cents and creation timestamps (Unix milliseconds); repeat downloads are not separate uses. POST /checkout with cents (100, 200, 500, 1000 or 2000) and a unique requestKey. Ask the customer to approve payment at the returned Stripe URL. GET /payments/{orderId} checks the owned order; use the returned orderId to confirm the purchase. Only a verified paid ledger state grants balance. Returning from checkout alone is not payment. Resume the same job after confirmation.

401 means invalid/revoked credentials; 402 means insufficient credits; 409 means revisions changed, a job is busy, or credentials were already delivered; 422 means invalid input; 429 means a limit was reached. Responses include an error message, code and requestId. Retry transient failures with backoff; refresh the job after a 409. Report requestId to support, never your key.

Current limits and retention

Three upload and three analysis attempts per job (failed attempts count toward processing limits, but do not consume completion credits); eight upload/analysis attempts per five minutes and twenty per rolling day across the account; two concurrently processing jobs per account; 120 authenticated requests/minute/key and 240/account. Five active keys/account. Job creation requires Idempotency-Key. Upload limits are 20 MB/file, a 50 MB expanded source package, and 20 multipart file parts. Sources: PDF, TXT, JSON, CSV, TSV, MD, DOCX, EML, JPEG, PNG and WebP. Static image sources are limited to 12 megapixels and 10,000 pixels per side; EXIF orientation is applied before OCR. Animated images, HEIC and TIFF are not supported. Target: one PDF or static JPEG/PNG/WebP image. Image forms are normalized into PDF pages; completion output is always PDF. For OCR, use clear, upright documents with printed English text. See the formats guide for file preparation.

Documents and results stay until deletion. Revoking a key does not delete jobs or credits. Cloud processing follows external-provider retention terms. Aideify keeps application data until you delete the job. Use the API for the complete upload, analysis, review and PDF-download workflow.

Contract and compatibility

Version 0.2.0: selected form-workflow endpoints and account authorization. The machine-readable contract comes from the enabled operation registry; the interactive reference reads that same contract. Owner reporting uses its separate API and credential. Changes to charges, ownership, supported operations or schemas require a documented compatibility decision.

Run a complete fictional example

Target application PDF and source resume PDF. These fictional files run through the ordinary upload path and use the normal completion credit. The hosted sample endpoint is free.

python form-filler-client.py --target job-application.pdf --source alex-morgan-resume.pdf --output filled.pdf

The client prints the authorization link immediately, waits for account approval and verified payment if needed, then uploads and analyzes the files. Open the review link, make corrections, and explicitly confirm in the terminal. The PDF contains approved answers; unknown or omitted fields stay blank. Without AIDEIFY_API_KEY, its temporary task key is revoked when it finishes. With an existing key, it leaves that key intact. Use --job ID to resume; missing uploads can be supplied on the same command.

HTTP sequence

GET /funding?credits=1
POST /jobs  { }  # Idempotency-Key header required
POST /jobs/ID/uploads  # multipart target, sources, revision, packageRevision
POST /jobs/ID/process  {"revision":R,"packageRevision":P,"allowRemote":false}
GET /jobs/ID  # wait for state=review; retain current revisions
PATCH /jobs/ID/review  {"revision":R,"packageRevision":P,"fieldId":"field-0","action":"approve"}
POST /jobs/ID/exports  {"revision":R,"packageRevision":P,"expectedCents":QUOTE,"allowPartial":true}
GET /jobs/ID/output?revision=R

Prefix each path with the base URL and authenticate every request with your bearer key. Replace R, P and QUOTE with the latest job response values; every edit changes the revision. The interactive reference provides executable multipart and JSON requests.

Troubleshooting and service policy

Blank answers: review the proposals and explicitly approve those to include; missing information does not prevent a partial PDF. A 409 after editing means refresh the job and use its new revisions. For an interrupted upload, fetch the job first: hasTarget and documents show what arrived. Keep the same job ID; do not create a new billable form to retry a download.

Payment pending: keep the order ID and check its ledger status. Do not pay twice. Expired or canceled orders can be replaced using a new requestKey. To abandon an unpaid checkout, POST /payments/ID/cancel with {} (or the authorization payment cancellation route with its secret). A completed payment cannot be canceled this way; contact support about refunds. Checkout return alone never grants credits. GET /funding?credits=1 quotes the next task, including the current pricing tier.

Failed exports release their credit reservation. Partial output is permitted and uses one completion credit when successfully created. Corrections and re-downloads of the same job and target are included within processing limits. Credits have no monthly reset or subscription. Contact support for billing, refund and unusable-output concerns; include the requestId or order ID, never documents or secrets. Provider retention is described in Data & privacy.

Changelog

November 4, 2026 - v0.2.0: full-task funding quote, $2 purchase option, checkout continuation/cancellation, approved authorization renewal, output-readiness metadata and typed onboarding responses. Python client flushes handoffs, approves answers after confirmation, resumes missing uploads, and cleans up temporary keys. Existing v1 routes and one-credit completion accounting remain supported.

November 2, 2026 - v0.1.0: customer account activation, scoped keys and reviewed form-to-PDF workflow. Responses may gain optional fields. Removals or changes to charging, ownership and required request fields require a documented compatibility decision.

Optional answer drafting

Set allowDrafting: true on upload or analysis to draft unanswered written responses, such as a bio or professional summary, from the job's source information. It defaults off for new jobs; later requests retain the saved choice unless explicitly changed. Cloud AI must be enabled. Factual gaps stay blank, human edits are preserved, and drafts require explicit approval before export. Set allowDrafting: false and reanalyse to remove unapproved automatic drafts.