API Reference

The Snapparse API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes.

API Base URL

https://api.snapparse.app/v1

Authentication

Your API requests are authenticated using API keys. Any request that does not include an API key will return an error. Pass your key in the X-API-Key header.

curl -X GET "https://api.snapparse.app/v1/extractors" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json"

Your API keys carry many privileges, so be sure to keep them secure! Do not share them in publicly accessible areas such as GitHub or client-side code.

Extractors

List Extractors

Retrieve a list of all extractors in your account. The response includes the extractor configurations and extraction counts.

GET/v1/extractors

Example Request

curl -X GET "https://api.snapparse.app/v1/extractors" \
     -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "EXT_123",
      "name": "Invoice Parser",
      "schema": [{ "key": "amount", "type": "number" }],
      "description": "Parses invoices",
      "status": "ACTIVE",
      "language": "Multi-Lingual",
      "options": [],
      "classificationKeywords": ["invoice"],
      "totalExtractions": 150,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Extractor

Create a new extractor with a specific JSON schema to structure your parsed data.

POST/v1/extractors

Request Payload

{
  "name": "Invoice Parser",
  "schema": [
    { "key": "amount", "type": "number", "description": "Total invoice amount" },
    { "key": "vendor", "type": "string" }
  ],
  "description": "Extracts basic info from invoices",
  "language": "English",
  "options": ["use_browser"],
  "classificationKeywords": ["invoice", "receipt"]
}

Example Request

curl -X POST "https://api.snapparse.app/v1/extractors" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Invoice Parser",
       "schema": [{ "key": "amount", "type": "number" }]
     }'

Example Response

{
  "success": true,
  "data": {
    "id": "EXT_124",
    "name": "Invoice Parser",
    "schema": [...],
    "email": "1a2b3c4d@snapparse.app",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Get Extractor

Retrieve details of a specific extractor by its ID.

GET/v1/extractors/:id

Example Request

curl -X GET "https://api.snapparse.app/v1/extractors/EXT_123" \
     -H "X-API-Key: YOUR_API_KEY"

Update Extractor

Update the configuration or schema of an existing extractor.

PUT/v1/extractors/:id

Request Payload

{
  "name": "Updated Invoice Parser",
  "options": ["use_browser", "high_res"]
}

Example Request

curl -X PUT "https://api.snapparse.app/v1/extractors/EXT_123" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Updated Invoice Parser"
     }'

Delete Extractor

Permanently delete an extractor and stop accepting new submissions.

DELETE/v1/extractors/:id

Example Request

curl -X DELETE "https://api.snapparse.app/v1/extractors/EXT_123" \
     -H "X-API-Key: YOUR_API_KEY"

Export to CSV

Download all completed extractions for an extractor as a CSV file.

GET/v1/extractors/:id/export

Example Request

curl -X GET "https://api.snapparse.app/v1/extractors/EXT_123/export" \
     -H "X-API-Key: YOUR_API_KEY" \
     -o extractions.csv

Extraction

Sync Extraction

Run an extraction synchronously. The request will stay open until processing is complete and return the JSON payload. Suitable for small files or text.

POST/v1/extract/sync

Request Payload

{
  "extractorId": "EXT_123",
  "source": "URL",
  "content": "https://example.com/invoice.pdf"
}

Example Request

curl -X POST "https://api.snapparse.app/v1/extract/sync" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "extractorId": "EXT_123",
       "source": "URL",
       "content": "https://example.com/invoice.pdf"
     }'

Example Response

{
  "success": true,
  "data": {
    "extractionId": "EXN_550",
    "data": { "amount": 1240.50, "vendor": "AWS" },
    "confidence": 0.99,
    "latency": 4200,
    "creditsUsed": 1
  }
}

Async Extraction

Enqueue an extraction job to run in the background. Returns an extraction ID immediately. Use GET /v1/extractions/:id or webhooks to retrieve the result.

POST/v1/extract

Request Payload

{
  "extractorId": "EXT_123",
  "source": "TEXT",
  "content": "Invoice #001 from ACME Corp. Total: $500"
}

Example Request

curl -X POST "https://api.snapparse.app/v1/extract" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "extractorId": "EXT_123",
       "source": "TEXT",
       "content": "Invoice from ACME. Total $500"
     }'

Example Response

{
  "success": true,
  "data": {
    "extractionId": "EXN_551",
    "status": "PENDING",
    "message": "Extraction job enqueued."
  }
}

Batch Extraction

Submit up to 20 documents in a single request for background processing.

POST/v1/extract/batch

Request Payload

{
  "extractorId": "EXT_123",
  "items": [
    { "source": "URL", "content": "https://example.com/doc1.pdf" },
    { "source": "URL", "content": "https://example.com/doc2.pdf" }
  ]
}

Example Request

curl -X POST "https://api.snapparse.app/v1/extract/batch" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "extractorId": "EXT_123",
       "items": [
         { "source": "URL", "content": "https://example.com/1.pdf" },
         { "source": "URL", "content": "https://example.com/2.pdf" }
       ]
     }'

Example Response

{
  "success": true,
  "data": {
    "count": 2,
    "extractionIds": ["EXN_552", "EXN_553"],
    "message": "Batch extraction jobs enqueued."
  }
}

Extraction Results

Get Extraction

Fetch the result and status of a specific extraction job.

GET/v1/extractions/:id

Example Request

curl -X GET "https://api.snapparse.app/v1/extractions/EXN_550" \
     -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "EXN_550",
    "extractorId": "EXT_123",
    "status": "COMPLETED",
    "source": "URL",
    "fileName": "invoice.pdf",
    "confidence": 0.98,
    "latency": 3200,
    "creditsUsed": 1,
    "data": { "amount": 500 },
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

List Extractions

List extractions for a specific extractor with pagination. Filter by status if needed.

GET/v1/extractions?extractorId=...

Example Request

curl -X GET "https://api.snapparse.app/v1/extractions?extractorId=EXT_123&limit=10&page=1" \
     -H "X-API-Key: YOUR_API_KEY"

Retry Extraction

Re-queue a failed or completed extraction to run again.

POST/v1/extractions/:id/retry

Example Request

curl -X POST "https://api.snapparse.app/v1/extractions/EXN_550/retry" \
     -H "X-API-Key: YOUR_API_KEY"

Delete Extraction

Delete an extraction record from your account.

DELETE/v1/extractions/:id

Example Request

curl -X DELETE "https://api.snapparse.app/v1/extractions/EXN_550" \
     -H "X-API-Key: YOUR_API_KEY"

Files

Upload File

Upload a file (PDF, image, doc) to our secure storage and receive a URL. You can use this URL as the content for extraction.

POST/v1/upload

Example Request

curl -X POST "https://api.snapparse.app/v1/upload" \
     -H "X-API-Key: YOUR_API_KEY" \
     -F "file=@/path/to/your/invoice.pdf"

Example Response

{
  "success": true,
  "data": {
    "id": "FILE_890",
    "url": "https://s3.snapparse.app/users/123/pdf/invoice.pdf",
    "fileName": "invoice.pdf",
    "fileType": "application/pdf"
  }
}

Webhooks

Webhooks allow you to receive real-time notifications about events in your account. When an extraction event occurs, we'll send an HTTP POST request to your configured URL.

8 Retry Attempts

We'll retry delivery with exponential backoff for up to 4 hours if your server is down.

Secure Signatures

Each request includes a signature so you can verify it came from Snapparse.

Event Tracking

Monitor every delivery attempt and response code directly in your dashboard.

Idempotency

Each event has a unique ID to help you avoid duplicate processing.

Available Events

extraction.processing

Triggered as soon as we begin ingesting your document.

extraction.completed

Triggered when extraction is successful. This payload includes the full JSON data.

extraction.failed

Triggered if the extraction fails after all retries are exhausted.

Verify Signatures

We sign each webhook request with an X-Snap-Signature header. This allows you to verify that the request was sent by Snapparse.

const crypto = require('crypto');

const signature = req.headers['x-snap-signature'];
const payload = JSON.stringify(req.body);

const [tPart, vPart] = signature.split(',');
const timestamp = tPart.split('=')[1];
const signatureHash = vPart.split('=')[1];

const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(`${timestamp}.${payload}`)
  .digest('hex');

if (signatureHash !== expected) {
  return res.status(401).send("Invalid Signature");
}