Documentation

Getting Started

ParseTap normalizes data from multiple sources into a consistent schema. This guide will help you set up your first data stream in under 10 minutes.

1. Create an Account

Sign up at parsetap.dev. The free tier includes 100,000 records per month with no credit card required.

2. Install the SDK

Choose your language:

# Node.js / TypeScript
npm install @parsetap/sdk

# Python
pip install parsetap

# Go
go get github.com/parsetap/parsetap-go

# Rust
cargo add parsetap

3. Initialize the Client

import { ParseTap } from '@parsetap/sdk';

const client = new ParseTap({
  apiKey: 'your_api_key_here'
});

4. Define a Schema

const schema = client.schema('payment_events', {
  eventId: { type: 'string', from: ['id', 'event_id', 'eventId'] },
  timestamp: { type: 'datetime', from: ['created', 'created_at', 'timestamp'] },
  amount: { type: 'number', from: ['amount', 'amount_total'], transform: 'cents_to_dollars' },
  currency: { type: 'string', from: ['currency'], transform: 'uppercase' },
  customerEmail: { type: 'string', from: ['email', 'customer_email', 'customer.email'] }
});

5. Receive Normalized Data

client.on('payment_events', (event) => {
  console.log(event.eventId);       // Normalized field name
  console.log(event.timestamp);     // JavaScript Date object
  console.log(event.amount);        // Converted from cents
  console.log(event.currency);      // Uppercase
  console.log(event.customerEmail); // Extracted from nested path
});

Authentication

All API requests require authentication via API key. Include your key in the Authorization header:

Authorization: Bearer pt_live_your_api_key_here

API keys are available in two modes:

• pt_live_* — Production keys with full access
• pt_test_* — Test keys for development (data not persisted)

Security: Never expose API keys in client-side code. Use environment variables and server-side requests only.

Defining Schemas

Schemas define the structure of data you want to receive. ParseTap maps incoming data from any source to your schema automatically.

Field Types

• string — Text values
• number — Integer or floating point
• boolean — True/false values
• datetime — ISO 8601 timestamps (auto-converted from unix, various formats)
• array — Lists of values
• object — Nested structures

Field Mapping

The from property accepts an array of possible source paths. ParseTap tries each in order:

email: {
  type: 'string',
  from: ['email', 'customer_email', 'user.email', 'data.object.email']
}

Built-in Transforms

• uppercase / lowercase — Case conversion
• trim — Remove whitespace
• cents_to_dollars — Divide by 100
• unix_to_iso — Convert unix timestamp
• parse_json — Parse JSON string

Data Sources

ParseTap supports multiple ingestion methods:

Webhooks

Point third-party webhooks at your ParseTap endpoint:

https://ingest.parsetap.dev/v1/webhooks/your_endpoint_id

Direct API

Push data directly via the API:

POST /v1/ingest/:schema_name
Content-Type: application/json

{ "your": "data" }

SDK Push

await client.ingest('payment_events', {
  id: 'evt_123',
  created: 1699574400,
  amount_total: 4999
});

API Reference

Base URL: https://api.parsetap.dev/v1

POST /ingest/:schema

Ingest data into a schema.

curl -X POST https://api.parsetap.dev/v1/ingest/payment_events \
  -H "Authorization: Bearer pt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"id": "evt_123", "amount": 4999}'

GET /schemas

List all schemas.

GET /schemas/:name

Get schema details.

PUT /schemas/:name

Create or update a schema.

GET /events

Query processed events. Supports filtering by schema, date range, and field values.

GET /events/:id

Get a specific event by ID.

SDKs

Official SDKs are available for:

• TypeScript/JavaScript: github.com/parsetap/parsetap-js
• Python: github.com/parsetap/parsetap-python
• Go: github.com/parsetap/parsetap-go
• Rust: github.com/parsetap/parsetap-rust

All SDKs are open source and accept contributions. See individual repositories for documentation.

Webhooks

ParseTap can deliver normalized events to your application via webhooks.

Configuring Delivery

client.subscribe('payment_events', {
  url: 'https://your-app.com/webhooks/parsetap',
  secret: 'whsec_your_signing_secret'
});

Verifying Signatures

All webhook deliveries include a signature header:

X-ParseTap-Signature: t=1699574400,v1=5257a869e...

Verify using the SDK:

const isValid = client.webhooks.verify(payload, signature, secret);

Error Handling

API errors return standard HTTP status codes with a JSON body:

{
  "error": {
    "code": "validation_error",
    "message": "Field 'email' failed validation: invalid email format",
    "field": "email",
    "documentation_url": "https://parsetap.dev/docs/errors#validation_error"
  }
}

Common Error Codes

• authentication_error — Invalid or missing API key
• validation_error — Data failed schema validation
• schema_not_found — Referenced schema does not exist
• rate_limit_exceeded — Too many requests
• internal_error — Server error (retry with backoff)

Rate Limits

Rate limits vary by plan:

• Free: 100 requests/minute, 100K records/month
• Pro: 1,000 requests/minute, 1M records/month
• Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1699574460