Pioneer API Quickstart

Pioneer API lets you send individual “record” payloads that get batched and compiled into uploads for production processing.

1) Get an API key

• Open My API Keys and click Request New Key.
• Choose test for initial integration testing, then use prod when you’re ready for production traffic (both use the same API base URL; the key type controls how it’s handled).
• Copy the secret immediately. For security, it cannot be shown again.
• New keys may take up to ~5 minutes to become active.

2) Understand the required request pieces

Records are sent to POST /records/send. All POST requests with a body must be valid JSON and include Content-Type: application/json.

• Header: x-api-key (required).
• Header: Content-Type must be application/json.
• Header: Idempotency-Key (required on every request). Use a unique value per record (UUID recommended) to safely retry without duplicating submissions.
• Body: batchId (required) — your grouping key. Everything with the same batchId is compiled together.
• Body: batchDuration (required) — determines the batching strategy (short or long).

POST https://api.v1.pioneerdm.com/records/send
Content-Type: application/json
x-api-key: pdm_...
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "batchId": "daily_lead_upload_20240521",
  "batchDuration": "short",

  "firstName": "Ada",
  "lastName": "Lovelace",
  "address1": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701"
}

3) Pick a batching strategy

• short (default): records are collected in a temporary batch. If no new records are received for that batch within a 60-second window, the batch is closed and processed into an upload.
• long: records are collected persistently over a longer period and processed at a fixed, scheduled time (e.g., daily, weekly, or monthly).
• Important: choose long if you plan to send fewer than ~50 records per minute.

4) Send records (fields are flexible)

• Aside from batchId and batchDuration, your record fields are malleable: you can send the fields your use case needs, and they will be included in the resulting upload.
• For the smoothest onboarding and easiest conversion, we recommend sticking to the field list in the OpenAPI docs whenever possible.
• Tip: keep field names consistent across records in the same batchId so your output has stable field names.

5) Confirm processing in the portal

You don’t need cURL to confirm processing—use this portal:

• If you sent batchDuration: "short", check Processed Records and switch to the Test tab to see your uploads.
• If you sent batchDuration: "long", check Batches (then use the Test tab). Long batches appear here before they compile into uploads.

Idempotency + retries

• Idempotency-Key is required on every send.
• If your integration retries, reuse the same idempotency key for that record so duplicates aren’t created.

Common errors

• 400: missing batchId, missing/invalid batchDuration, or missing Idempotency-Key.
• 401/403: missing or invalid x-api-key.