Key-value pair extraction API

Automatically identify and extract key values without manual supervision or templates. Integrate a KVP API to extract specific data like credit cards, addresses, and emails from unstructured documents.

TRY FOR FREE

Template-free, ML-driven extraction

Identify key-value pairs from documents such as invoices, forms, and IDs without defining rules or templates. Our API adapts intelligently using machine learning.

Automate with Zapier

Automatically extract key-value pairs from images in Google Drive and save them as JSON using our Zapier integration. Automate your document workflows to save time and centralize data.

CONNECT WITH ZAPIER

Works with complex layouts

Extract information from documents with varying formats, irregular spacing, and inconsistent structure with high accuracy.

Try it out

This example will extract key-value pairs from an input file and return it as a JSON file.

Try it out in three steps

Add an image named invoice.webp to your project folder.
Run the code from the same folder.
Open result.json to see the output.

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer your_api_key_here" \
  -o result.json \
  --fail \
  -F invoice=@invoice.webp \
  -F instructions='{
      "parts": [
        {
          "file": "invoice"
        }
      ],
      "output": {
        "type": "json-content",
        "keyValuePairs": true
      }
    }'

curl -X POST https://api.nutrient.io/build ^
  -H "Authorization: Bearer your_api_key_here" ^
  -o result.json ^
  --fail ^
  -F invoice=@invoice.webp ^
  -F instructions="{\"parts\": [{\"file\": \"invoice\"}], \"output\": {\"type\": \"json-content\", \"keyValuePairs\": true}}"

package com.example.pspdfkit;

import java.io.File;
import java.io.IOException;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;

import org.json.JSONArray;
import org.json.JSONObject;

import okhttp3.MediaType;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public final class PspdfkitApiExample {
  public static void main(final String[] args) throws IOException {
    final RequestBody body = new MultipartBody.Builder()
      .setType(MultipartBody.FORM)
      .addFormDataPart(
        "invoice",
        "invoice.webp",
        RequestBody.create(
          MediaType.parse("application/octet-stream"),
          new File("invoice.webp")
        )
      )
      .addFormDataPart(
        "instructions",
        new JSONObject()
          .put("parts", new JSONArray()
            .put(new JSONObject()
              .put("file", "invoice")
            )
          )
          .put("output", new JSONObject()
            .put("type", "json-content")
            .put("keyValuePairs", true)
          ).toString()
      )
      .build();

    final Request request = new Request.Builder()
      .url("https://api.nutrient.io/build")
      .method("POST", body)
      .addHeader("Authorization", "Bearer your_api_key_here")
      .build();

    final OkHttpClient client = new OkHttpClient()
      .newBuilder()
      .build();

    final Response response = client.newCall(request).execute();

    if (response.isSuccessful()) {
      Files.copy(
        response.body().byteStream(),
        FileSystems.getDefault().getPath("result.json"),
        StandardCopyOption.REPLACE_EXISTING
      );
    } else {
      // Handle the error
      throw new IOException(response.body().string());
    }
  }
}

using System;
using System.IO;
using System.Net;
using RestSharp;

namespace PspdfkitApiDemo
{
  class Program
  {
    static void Main(string[] args)
    {
      var client = new RestClient("https://api.nutrient.io/build");

      var request = new RestRequest(Method.POST)
        .AddHeader("Authorization", "Bearer your_api_key_here")
        .AddFile("invoice", "invoice.webp")
        .AddParameter("instructions", new JsonObject
        {
          ["parts"] = new JsonArray
          {
            new JsonObject
            {
              ["file"] = "invoice"
            }
          },
          ["output"] = new JsonObject
          {
            ["type"] = "json-content",
            ["keyValuePairs"] = true
          }
        }.ToString());

      request.AdvancedResponseWriter = (responseStream, response) =>
      {
        if (response.StatusCode == HttpStatusCode.OK)
        {
          using (responseStream)
          {
            using var outputFileWriter = File.OpenWrite("result.json");
            responseStream.CopyTo(outputFileWriter);
          }
        }
        else
        {
          var responseStreamReader = new StreamReader(responseStream);
          Console.Write(responseStreamReader.ReadToEnd());
        }
      };

      client.Execute(request);
    }
  }
}

// This code requires Node.js. Do not run this code directly in a web browser.

const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')

const formData = new FormData()
formData.append('instructions', JSON.stringify({
  parts: [
    {
      file: "invoice"
    }
  ],
  output: {
    type: "json-content",
    keyValuePairs: true
  }
}))
formData.append('invoice', fs.createReadStream('invoice.webp'))

;(async () => {
  try {
    const response = await axios.post('https://api.nutrient.io/build', formData, {
      headers: formData.getHeaders({
        'Authorization': 'Bearer your_api_key_here'
      }),
      responseType: "stream"
    })

    response.data.pipe(fs.createWriteStream("result.json"))
  } catch (e) {
    const errorString = await streamToString(e.response.data)
    console.log(errorString)
  }
})()

function streamToString(stream) {
  const chunks = []
  return new Promise((resolve, reject) => {
    stream.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
    stream.on("error", (err) => reject(err))
    stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")))
  })
}

import requests
import json

response = requests.request(
  'POST',
  'https://api.nutrient.io/build',
  headers = {
    'Authorization': 'Bearer your_api_key_here'
  },
  files = {
    'invoice': open('invoice.webp', 'rb')
  },
  data = {
    'instructions': json.dumps({
      'parts': [
        {
          'file': 'invoice'
        }
      ],
      'output': {
        'type': 'json-content',
        'keyValuePairs': True
      }
    })
  },
  stream = True
)

if response.ok:
  with open('result.json', 'wb') as fd:
    for chunk in response.iter_content(chunk_size=8096):
      fd.write(chunk)
else:
  print(response.text)
  exit()

<?php

$FileHandle = fopen('result.json', 'w+');

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.nutrient.io/build',
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_POSTFIELDS => array(
    'instructions' => '{
      "parts": [
        {
          "file": "invoice"
        }
      ],
      "output": {
        "type": "json-content",
        "keyValuePairs": true
      }
    }',
    'invoice' => new CURLFILE('invoice.webp')
  ),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer your_api_key_here'
  ),
  CURLOPT_FILE => $FileHandle,
));

$response = curl_exec($curl);

curl_close($curl);

fclose($FileHandle);

POST https://api.nutrient.io/build HTTP/1.1
Content-Type: multipart/form-data; boundary=--customboundary
Authorization: Bearer your_api_key_here

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "invoice"
    }
  ],
  "output": {
    "type": "json-content",
    "keyValuePairs": true
  }
}
--customboundary
Content-Disposition: form-data; name="invoice"; filename="invoice.webp"
Content-Type: image/webp

(invoice data)
--customboundary--

Most common next steps

Connect key-value extraction to getting started, pricing, and broader data extraction workflows

OPEN GETTING STARTED

Use the following:

Data Extraction API When you need specific fields extracted to a schema, with confidence scores and source context for every value

Table extraction If the workflow also needs structured tabular rows

Get started:

Getting started For API key setup

Postman collection For the fastest first request

Supported languages For JavaScript, Python, Java, PHP, and HTTP implementation options

REST API reference For endpoint details

Platform resources:

Security documentation For compliance review

Privacy documentation For uploaded file handling

Processor API pricing For credits

API reference For endpoint and request details

Security documentation For document handling and compliance review

Privacy documentation For data handling review

Processor API overview For platform context

Security is our top priority

SOC 2 Type 2 audited

Nutrient’s infrastructure is SOC 2 Type 2 audited and GDPR-compliant. See our privacy policy and security documentation for details on data handling.

HTTPS encryption

All communication between your application and Nutrient is done via HTTPS to ensure your data is encrypted when it’s sent to us.

Safe payment processing

All payments are handled by Paddle. Nutrient DWS Processor API never has direct access to any of your payment data.

Frequently asked questions

How do I extract key-value pairs from forms via API?

Send a document to the Build endpoint with the key-value pair extraction action and receive the detected fields back as JSON — no templates or rules to maintain. The getting started guide covers API key setup and your first request.

What types of documents does key-value pair extraction support?

It works on invoices, forms, IDs, and other documents with varying layouts, irregular spacing, and inconsistent structure. For structured tabular rows, pair it with table extraction.

How is key-value pair extraction different from full data extraction?

Key-value pair extraction detects field-and-value pairs like dates, IDs, and emails. The broader Data Extraction API spans key-value, table, and text extraction in a single workflow.

Which programming languages can call the API?

Any language that makes HTTP requests. Nutrient provides examples for JavaScript, Python, Java, C# (.NET), and PHP, plus curl and a Postman collection.

Is the key-value pair extraction API SOC 2 compliant?

Yes. The API is backed by Nutrient’s SOC 2 Type 2-audited infrastructure — built for use in business-critical and regulated workflows.

How is the key-value pair extraction API priced?

The API runs on credits, with a specific credit cost per action. See Processor API pricing; new accounts include free monthly credits.

Ready to try it?

Create an account to get your DWS Processor API key and start making API calls.

START FOR FREE