Developers - Zaptic

Before you integrate: get a license

API access requires a Zaptic license tied to your credit balance. You can start with a free license or purchase a credit pack on our store—after signup or checkout you receive a license key to send in every request body.

View plans (including free license)

How the Process API works

Get a license

Claim a free license or buy a credit pack on the pricing page.
Extract locally

Parse the PDF/DOC on your side. Zaptic does not accept file uploads—only the text/content inside.
POST /process

Send license, origin, requested_fields, and extracted_content as JSON.
Use the response

Map extracted values to forms, ATS, or your database. Scores appear when scoring_criteria is sent.

Credits: Each request costs 1 credit. Adding scoring_criteria costs 1 extra credit. Identical repeated requests are served from cache and do not consume credits again.

Endpoint

Method: POST
URL: https://api.zaptic.io/json-api/zaptic/v1/process
Headers: Content-Type: application/json

Request body

Field	Required	Description
license	Yes	License key from your purchased pack.
origin	Yes	Caller identifier, e.g. ats_connector or your product slug.
requested_fields	Yes	Schema of fields to extract. Each entry has label, type (text, number, array, or list), and subfields when type is array or list. See Field schemas.
extracted_content	Yes	Plain text taken from inside the PDF/DOC—not the binary file.
domain	No	Host or site domain associated with the integration.
lang	No	Locale hint, e.g. en_US or es_ES.
scoring_criteria	No	Optional criteria (requirement + weight 1–10) so Gemini can score the document against your rules (+1 credit).

Request example

Sample CV extraction with nested list fields and optional scoring. Values below are fictional—replace YOUR_LICENSE_KEY and use your own content.

{
    "license": "YOUR_LICENSE_KEY",
    "domain": "app.example-hr.io",
    "origin": "ats_connector",
    "lang": "en_US",
    "scoring_criteria": {
        "techstack": {
            "requirement": "Hands-on experience with Node.js, TypeScript, and REST API design. Cloud deployment experience preferred.",
            "weight": 10
        },
        "seniority": {
            "requirement": "Minimum 4 years in backend or full-stack roles with ownership of production services.",
            "weight": 8
        },
        "location": {
            "requirement": "Eligible to work in the EU or within CET business hours.",
            "weight": 6
        }
    },
    "requested_fields": {
        "name": {
            "label": "Full name",
            "type": "text"
        },
        "job_title": {
            "label": "Job title / role",
            "type": "text"
        },
        "professional_summary": {
            "label": "Professional summary",
            "type": "text"
        },
        "profile_type": {
            "label": "Profile type",
            "type": "text"
        },
        "age": {
            "label": "Age",
            "type": "text"
        },
        "date_of_birth": {
            "label": "Date of birth",
            "type": "text"
        },
        "projects": {
            "label": "Projects",
            "type": "array",
            "subfields": {
                "name": {
                    "label": "Name",
                    "type": "text"
                },
                "description": {
                    "label": "Description",
                    "type": "text"
                }
            }
        },
        "work_experience": {
            "label": "Work experience",
            "type": "array",
            "subfields": {
                "company": {
                    "label": "Company",
                    "type": "text"
                },
                "years": {
                    "label": "Years",
                    "type": "text"
                },
                "tasks": {
                    "label": "Tasks",
                    "type": "array",
                    "subfields": {
                        "task": {
                            "label": "Task",
                            "type": "text"
                        }
                    }
                }
            }
        },
        "skills": {
            "label": "Skills",
            "type": "list",
            "subfields": {
                "item": {
                    "label": "Skill",
                    "type": "text"
                }
            }
        },
        "education": {
            "label": "Education",
            "type": "text"
        }
    },
    "extracted_content": "Jordan Ellis\r\nSenior Backend Engineer | API Platforms & Integrations\r\nBerlin, Germany | jordan.ellis@example-hr.io | https://github.com/jellis-dev\r\n\r\nProfessional summary\r\nBackend engineer with 6+ years building SaaS APIs, workflow automation, and document pipelines. Comfortable with Node.js, PostgreSQL, and event-driven architectures.\r\n\r\nFeatured projects\r\nAtlas Forms — No-code intake builder for enterprise HR teams.\r\nLedger Lite — Lightweight billing microservice for subscription products.\r\nDevCast Brief — Internal podcast summarizing platform release notes.\r\n\r\nExperience\r\nNorthwind Labs — Senior Backend Engineer (2023 – Present)\r\nDesigned REST and webhook APIs consumed by partner ATS tools. Led migration to structured logging and idempotent job queues.\r\n\r\nCloudSphere Inc — Software Engineer (2020 – 2023)\r\nBuilt document ingestion services and PDF text extraction workers. Integrated third-party OCR providers.\r\n\r\nSkills: Node.js, TypeScript, PostgreSQL, REST, webhooks, Docker, Redis, GitHub Actions, AWS, PDF parsing, API design, event-driven architecture.\r\n\r\nEducation\r\nB.Sc. Computer Science — Rhine Valley University of Applied Sciences"
}

Response example

Keys under data.extracted_fields mirror your requested_fields. When scoring_criteria was sent, data.internal_analysis includes total_score and summary.

Property	Description
status	success or error.
version	API response schema version.
data.extracted_fields	Structured values for every requested field.
data.internal_analysis	Present when scoring_criteria was sent: total_score and summary.

{
    "status": "success",
    "version": "1.0",
    "data": {
        "extracted_fields": {
            "name": "Jordan Ellis",
            "country": "Germany",
            "email": "jordan.ellis@example-hr.io",
            "github": "https://github.com/jellis-dev",
            "projects": [
                {
                    "name": "Atlas Forms",
                    "description": "No-code intake builder for enterprise HR teams"
                },
                {
                    "name": "Ledger Lite",
                    "description": "Lightweight billing microservice for subscription products"
                },
                {
                    "name": "DevCast Brief",
                    "description": "Internal podcast summarizing platform release notes"
                }
            ],
            "work_experience": [
                {
                    "company": "Northwind Labs",
                    "years": "2023 – Present",
                    "tasks": [
                        {
                            "task": "Designed REST and webhook APIs for partner ATS integrations."
                        },
                        {
                            "task": "Led migration to structured logging and idempotent background jobs."
                        },
                        {
                            "task": "Owned PostgreSQL schema changes and performance reviews."
                        }
                    ]
                },
                {
                    "company": "CloudSphere Inc",
                    "years": "2020 – 2023",
                    "tasks": [
                        {
                            "task": "Built document ingestion services and PDF text extraction workers."
                        },
                        {
                            "task": "Integrated third-party OCR providers behind a unified adapter layer."
                        }
                    ]
                }
            ],
            "skills": [
                "Node.js",
                "TypeScript",
                "PostgreSQL",
                "REST",
                "webhooks",
                "Docker",
                "Redis",
                "GitHub Actions",
                "AWS",
                "PDF parsing",
                "API design",
                "event-driven architecture"
            ]
        },
        "internal_analysis": {
            "total_score": 84,
            "summary": "Jordan is a strong backend candidate with relevant API and document-pipeline experience. Tech stack and seniority align well with the role; location fit is acceptable for CET collaboration."
        }
    }
}

Code examples

License and payload travel in the JSON body.

cURL

curl -X POST "https://api.zaptic.io/json-api/zaptic/v1/process" \
  -H "Content-Type: application/json" \
  -d @payload.json

JavaScript (fetch)

const processUrl = "https://api.zaptic.io/json-api/zaptic/v1/process";

const payload = {
  license: process.env.ZAPTIC_LICENSE,
  domain: "app.example-hr.io",
  origin: "ats_connector",
  lang: "en_US",
  requested_fields: {
    name: { label: "Full name", type: "text" },
    email: { label: "Email", type: "text" },
  },
  extracted_content: documentTextFromYourParser,
};

const response = await fetch(processUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

const body = await response.json();
if (body.status !== "success") {
  throw new Error(body.message ?? "Zaptic process failed");
}

const fields = body.data.extracted_fields;
const analysis = body.data.internal_analysis;
console.log(fields.name, analysis?.total_score);

Python

import os
import requests

PROCESS_URL = "https://api.zaptic.io/json-api/zaptic/v1/process"

payload = {
    "license": os.environ["ZAPTIC_LICENSE"],
    "domain": "app.example-hr.io",
    "origin": "ats_connector",
    "lang": "en_US",
    "requested_fields": {
        "name": {"label": "Full name", "type": "text"},
        "email": {"label": "Email", "type": "text"},
    },
    "extracted_content": document_text_from_your_parser,
}

response = requests.post(
    PROCESS_URL,
    headers={"Content-Type": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
body = response.json()

if body.get("status") != "success":
    raise RuntimeError(body.get("message", "Zaptic process failed"))

fields = body["data"]["extracted_fields"]
analysis = body["data"].get("internal_analysis")
print(fields["name"], analysis.get("total_score") if analysis else None)

PHP

$processUrl = "https://api.zaptic.io/json-api/zaptic/v1/process";

$payload = [
    "license"           => getenv( "ZAPTIC_LICENSE" ) ?: "",
    "domain"            => "app.example-hr.io",
    "origin"            => "ats_connector",
    "lang"              => "en_US",
    "requested_fields"  => [
        "name" => [
            "label" => "Full name",
            "type"  => "text",
        ],
        "email" => [
            "label" => "Email",
            "type"  => "text",
        ],
    ],
    "extracted_content" => $documentTextFromYourParser,
];

$ch = curl_init( $processUrl );
curl_setopt_array( $ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [ "Content-Type: application/json" ],
    CURLOPT_POSTFIELDS     => json_encode( $payload ),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 120,
] );

$responseBody = curl_exec( $ch );
$httpCode = (int) curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );

if ( $responseBody === false || $httpCode >= 400 ) {
    throw new RuntimeException( "Zaptic process request failed (HTTP {$httpCode})" );
}

$body = json_decode( $responseBody, true );

if ( ( $body["status"] ?? "" ) !== "success" ) {
    throw new RuntimeException( $body["message"] ?? "Zaptic process failed" );
}

$extractedFields = $body["data"]["extracted_fields"] ?? [];
$internalAnalysis = $body["data"]["internal_analysis"] ?? null;

Field schemas

Define what Zaptic should pull from extracted_content. Field extraction and optional scoring both run through Google Gemini—you send the schema; Gemini maps the text to your structure.

Powered by Gemini: All interpretation of document text—structured extraction and scoring against your criteria—is performed by Google Gemini models on Zaptic infrastructure.

requested_fields

An object whose keys are your field names. Every field must include label and type. There are four types:

Type	subfields	Response shape
text	Not used	A single string value.
number	Not used	A single numeric value (JSON number).
array	Required	An array of objects—one object per repeated block, with keys matching subfields.
list	Required	A flat array of strings (simple list), not objects.

text

Scalar values: names, emails, summaries, dates, etc.

"name": {
  "label": "Full name",
  "type": "text"
}

number

Numeric values: amounts, counts, years of experience, percentages, etc. Returned as a JSON number, not a string.

"years_experience": {
  "label": "Years of experience",
  "type": "number"
}

Example response (number):

"years_experience": 8

array

Repeating structured blocks. You must provide subfields with at least one child field. Each subfield can be text, number, array, or list—so you can nest array or list inside array (or list) without limit.

"work_experience": {
  "label": "Work experience",
  "type": "array",
  "subfields": {
    "company": { "label": "Company", "type": "text" },
    "years": { "label": "Years", "type": "number" },
    "tasks": {
      "label": "Tasks",
      "type": "array",
      "subfields": {
        "task": { "label": "Task", "type": "text" }
      }
    }
  }
}

Example response (array → objects):

"tasks": [
  { "task": "Built document ingestion services and PDF text extraction workers." },
  { "task": "Integrated third-party OCR providers behind a unified adapter layer." }
]

list

A simple list of values from the document (skills, tags, bullet points). subfields is still required—typically one text child (e.g. item) whose values are flattened into a string array in the response.

"skills": {
  "label": "Skills",
  "type": "list",
  "subfields": {
    "item": { "label": "Skill", "type": "text" }
  }
}

Example response (list → string array):

"skills": [
  "Node.js",
  "TypeScript",
  "PostgreSQL",
  "REST",
  "webhooks"
]

Inside subfields you can chain more array or list nodes to any depth (e.g. array of companies, each with an array of tasks, each with nested lists).

scoring_criteria

Optional object of rules so Gemini can read the full extracted_content, evaluate how well it matches each rule, and return a score plus summary in data.internal_analysis. Ideal for hiring: compare CVs against role requirements, tech stack, seniority, or location.

Each criterion is a key (your slug) with:

requirement — Plain-language description of what you are looking for in the document.
weight — Integer from 1 to 10: how important this criterion is when computing the overall score (10 = highest).

Sending scoring_criteria costs one additional credit per request. The response includes total_score and a short summary explaining the match.

"scoring_criteria": {
  "techstack": {
    "requirement": "Hands-on experience with Node.js, TypeScript, and REST API design.",
    "weight": 10
  },
  "seniority": {
    "requirement": "Minimum 4 years in backend or full-stack roles.",
    "weight": 8
  },
  "location": {
    "requirement": "Eligible to work in the EU or within CET business hours.",
    "weight": 6
  }
}

"internal_analysis": {
  "total_score": 84,
  "summary": "Strong backend candidate; tech stack and seniority align well with the role."
}

Never commit your license key—use environment variables or secrets storage.
Cache hits on duplicate payloads do not deduct credits.
Need a license? Browse credit packs.