Developers

Before you integrate: get a license

How the Process API works

1. 1

   Get a license

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

2. 2

   Extract locally

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

3. 3

   POST /process

   Send license, origin, requested_fields, and extracted_content as JSON.

4. 4

   Use the response

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

Endpoint

Method

POST

URL

https://api.zaptic.io/json-api/zaptic/v1/process

Headers

Content-Type: application/json

Request body

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.

{
    "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 -X POST "https://api.zaptic.io/json-api/zaptic/v1/process" \
  -H "Content-Type: application/json" \
  -d @payload.json

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);

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)

$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.

requested_fields

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

text

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

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

array

Repeating structured blocks. You must provide subfields with at least one child field. Each subfield can be text, 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": "text" },
    "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).