Quickstart Guide

This guide will help you make your first API request and extract data from a document in just a few minutes.

Prerequisites

An Adteco account (sign up here)
An API key (get one from API Settings)
A sample document (invoice, receipt, etc.)

Step 1: Get Your API Key

Log in to your Adteco account
Navigate to DocExtract → Settings → API Keys
Click New Key and give it a name
Copy your API key (starts with sk_live_ or sk_test_)

Important: Save your API key securely. You won't be able to see it again!

Step 2: Create an Extractor

curl -X POST https://api.adteco.com/v1/extractors \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Extractor",
    "document_type": "invoice",
    "field_definitions": [
      {
        "name": "invoice_number",
        "type": "text",
        "required": true,
        "description": "The unique invoice identifier"
      },
      {
        "name": "total_amount",
        "type": "currency",
        "required": true,
        "description": "Total amount due"
      },
      {
        "name": "invoice_date",
        "type": "date",
        "required": true,
        "description": "Date the invoice was issued"
      },
      {
        "name": "vendor_name",
        "type": "text",
        "required": false,
        "description": "Name of the vendor/supplier"
      }
    ]
  }'

const response = await fetch('https://api.adteco.com/v1/extractors', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Invoice Extractor',
    document_type: 'invoice',
    field_definitions: [
      {
        name: 'invoice_number',
        type: 'text',
        required: true,
        description: 'The unique invoice identifier',
      },
      {
        name: 'total_amount',
        type: 'currency',
        required: true,
        description: 'Total amount due',
      },
      {
        name: 'invoice_date',
        type: 'date',
        required: true,
        description: 'Date the invoice was issued',
      },
      {
        name: 'vendor_name',
        type: 'text',
        required: false,
        description: 'Name of the vendor/supplier',
      },
    ],
  }),
});

const extractor = await response.json();
console.log('Extractor ID:', extractor.id);

import requests

response = requests.post(
    'https://api.adteco.com/v1/extractors',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Invoice Extractor',
        'document_type': 'invoice',
        'field_definitions': [
            {
                'name': 'invoice_number',
                'type': 'text',
                'required': True,
                'description': 'The unique invoice identifier',
            },
            {
                'name': 'total_amount',
                'type': 'currency',
                'required': True,
                'description': 'Total amount due',
            },
            {
                'name': 'invoice_date',
                'type': 'date',
                'required': True,
                'description': 'Date the invoice was issued',
            },
            {
                'name': 'vendor_name',
                'type': 'text',
                'required': False,
                'description': 'Name of the vendor/supplier',
            },
        ],
    },
)

extractor = response.json()
print('Extractor ID:', extractor['id'])

Response:

{
  "id": "ext_abc123...",
  "name": "Invoice Extractor",
  "document_type": "invoice",
  "field_definitions": [...],
  "created_at": "2024-11-23T10:00:00Z",
  "is_active": true
}

Save the id from the response - you'll need it to process documents.

Step 3: Submit a Document

Now let's extract data from a document using your extractor.

# First, convert your document to base64
base64_doc=$(base64 -i invoice.pdf)

curl -X POST https://api.adteco.com/v1/documents \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "extractor_id": "ext_abc123...",
    "document": "'$base64_doc'",
    "mime_type": "application/pdf"
  }'

import fs from 'fs';

// Read and convert document to base64
const documentBuffer = fs.readFileSync('./invoice.pdf');
const base64Document = documentBuffer.toString('base64');

const response = await fetch('https://api.adteco.com/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    extractor_id: 'ext_abc123...',
    document: base64Document,
    mime_type: 'application/pdf',
  }),
});

const job = await response.json();
console.log('Job ID:', job.id);
console.log('Status:', job.status);

import requests
import base64

# Read and convert document to base64
with open('invoice.pdf', 'rb') as f:
    document_bytes = f.read()
    base64_document = base64.b64encode(document_bytes).decode('utf-8')

response = requests.post(
    'https://api.adteco.com/v1/documents',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'extractor_id': 'ext_abc123...',
        'document': base64_document,
        'mime_type': 'application/pdf',
    },
)

job = response.json()
print('Job ID:', job['id'])
print('Status:', job['status'])

Response:

{
  "id": "job_xyz789...",
  "extractor_id": "ext_abc123...",
  "status": "queued",
  "created_at": "2024-11-23T10:05:00Z"
}

Step 4: Get Extraction Results

Processing typically takes 3-10 seconds. You can either:

Poll the job endpoint to check status
Use webhooks to get notified when processing completes (recommended)

curl -X GET https://api.adteco.com/v1/documents/job_xyz789... \
  -H "Authorization: Bearer sk_live_your_api_key"

// Poll for results
async function waitForResults(jobId) {
  while (true) {
    const response = await fetch(
      `https://api.adteco.com/v1/documents/${jobId}`,
      {
        headers: {
          'Authorization': 'Bearer sk_live_your_api_key',
        },
      }
    );

    const job = await response.json();

    if (job.status === 'completed') {
      return job.extracted_data;
    } else if (job.status === 'failed') {
      throw new Error(`Job failed: ${job.error_details?.message}`);
    }

    // Wait 2 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

const extractedData = await waitForResults('job_xyz789...');
console.log(extractedData);

import time

def wait_for_results(job_id):
    while True:
        response = requests.get(
            f'https://api.adteco.com/v1/documents/{job_id}',
            headers={'Authorization': 'Bearer sk_live_your_api_key'},
        )

        job = response.json()

        if job['status'] == 'completed':
            return job['extracted_data']
        elif job['status'] == 'failed':
            raise Exception(f"Job failed: {job['error_details']['message']}")

        # Wait 2 seconds before checking again
        time.sleep(2)

extracted_data = wait_for_results('job_xyz789...')
print(extracted_data)

Completed Response:

{
  "id": "job_xyz789...",
  "status": "completed",
  "extracted_data": {
    "invoice_number": "INV-2024-001",
    "total_amount": 1250.50,
    "invoice_date": "2024-11-15",
    "vendor_name": "Acme Corporation"
  },
  "confidence": {
    "invoice_number": 0.98,
    "total_amount": 0.95,
    "invoice_date": 0.99,
    "vendor_name": 0.92
  },
  "processing_time_ms": 4532,
  "cost_credits": 2,
  "completed_at": "2024-11-23T10:05:05Z"
}