Developers

Antes de integrar: obtén una licencia

Cómo funciona la API de Procesamiento

1. 1

   Obtener una licencia

   Solicita una licencia gratuita o compra un paquete de créditos en la página de precios.

2. 2

   Extraer localmente

   Analiza el PDF/DOC por tu cuenta. Zaptic no acepta cargas de archivos, solo el texto/contenido dentro de ellos.

3. 3

   POST /process

   Envía la licencia, origen, requested_fields y extracted_content como JSON.

4. 4

   Usar la respuesta

   Asigna los valores extraídos a formularios, ATS o a tu base de datos. Las puntuaciones aparecen cuando se envía scoring_criteria.

Endpoint

Método

POST

URL

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

Cabeceras (Headers)

Content-Type: application/json

Cuerpo de la solicitud (Request body)

Ejemplo de solicitud

Ejemplo de extracción de CV con campos de lista anidados y puntuación opcional. Los valores a continuación son ficticios: reemplaza YOUR_LICENSE_KEY y usa tu propio contenido.

{
    "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"
}

Ejemplo de respuesta

Las claves bajo data.extracted_fields reflejan tus requested_fields. Cuando se envió scoring_criteria, data.internal_analysis incluye total_score y el resumen.

{
    "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."
        }
    }
}

Ejemplos de código

La licencia y la carga útil (payload) viajan en el cuerpo JSON.

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;

Esquemas de campo

Define qué debe extraer Zaptic de extracted_content. Tanto la extracción de campos como la puntuación opcional se realizan a través de Google Gemini: tú envías el esquema y Gemini asigna el texto a tu estructura.

requested_fields

Un objeto cuyas claves son los nombres de tus campos. Cada campo debe incluir una etiqueta (label) y un tipo (type). Hay tres tipos:

text

Valores escalares: nombres, correos electrónicos, resúmenes, fechas, etc.

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

array

Bloques estructurados repetitivos. Debes proporcionar subcampos con al menos un campo hijo. Cada subcampo puede ser texto, matriz o lista, por lo que puedes anidar matrices o listas dentro de otra matriz (o lista) sin límites.

"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" }
      }
    }
  }
}

Ejemplo de respuesta (array → objetos):

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

list

Una lista simple de valores del documento (habilidades, etiquetas, viñetas). Todavía se requiere subfields; normalmente un hijo de tipo texto (por ejemplo, item) cuyos valores se aplanan en una matriz de cadenas en la respuesta.

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

Ejemplo de respuesta (list → matriz de cadenas):

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

Dentro de los subcampos puedes encadenar más nodos de tipo matriz o lista a cualquier profundidad (por ejemplo, matriz de empresas, cada una con una matriz de tareas, cada una con listas anidadas).