Record Processing API (1.0.5)

API for receiving individual records for processing in batches.

All POST requests with a body must be sent as valid JSON with the Content-Type: application/json header.

Clients can send records to the API through the /records/send endpoint. Records are grouped into a "batch" and processed based on the chosen batchDuration 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 a CSV file.
long: Records are collected persistently over a longer period and processed at a fixed, scheduled time (e.g., daily, weekly, or monthly).

Download OpenAPI description

OPENAPI.json

OPENAPI.yaml

Servers

Mock server

https://pioneer-api-v1.redocly.app/_mock/openapi/

Testing Server

https://api.pioneerdm.com/

Production Server

https://api.v1.pioneerdm.com/

General

General API information

Operations

Records

Operations for sending records and retrieving processed upload status

Operations

Send a Single Record

Request

Submits a single record as a JSON object to be added to a batch. The request body must be valid JSON and you must include the Content-Type: application/json header.

The batchId and batchDuration fields are required within the JSON object. This endpoint also requires x-api-key and idempotency-key headers.

Security

apiKeyAuth

Headers

idempotency-keystring(uuid)required

A unique key (e.g., UUID) to ensure a request is processed only once. If a request with this key has completed, the server returns the cached response.

Example: a7b2c9d8-e1f2-3456-7890-1k2l3m4n5o6p

Bodyapplication/jsonrequired

The record object to be submitted.

batchIdstringrequired

Explicit identifier for the batch this record belongs to.

Example: "daily_lead_upload_20240521"

batchDurationstringrequired

Important. Determines the batching strategy. 'short' uses a time-based inactivity window (e.g., 60 seconds) to close and process the batch. 'long' collects records over a longer period to be processed at a fixed, scheduled time (e.g., daily, weekly, or monthly). It is very important to select a long batch duration if your company plans to send less than 50 records a minute.

Default "short"

Example: "long"

mail_datestring(date)

An optional, desired mail date in YYYY-MM-DD format. This is not a guaranteed mailing date but is used as a hint for grouping records with similar desired timelines.

Example: "2024-06-20"

messagestring

The main body text or message for the mail piece. Can contain merge variables (e.g., {{to.name}} or {{offer_code}}).

Example: "Hello {{to.name}}, don't miss out on our summer sale! Use code {{offer_code}} for 20% off."

metadataobject

Optional metadata associated with the record. This field is no longer used for deriving a batch identifier.

metaobject

Alias for 'metadata'. Optional metadata associated with the record.

descriptionstring

Example: "Demo postcard with merge variables"

toobject

Example: {"name":"Alex Ray","address_line1":"123 Main St","city":"Anytown","state":"CA","address_zip":"90210"}

fromobject

Example: {"name":"Pioneer Corp","address_line1":"456 Sender Ave","city":"Senderville","state":"NY","address_zip":"10001"}

merge_variablesobject

An object containing key-value pairs for dynamic data insertion. Each key in this object can be used as a placeholder in string fields like 'message' (e.g., {{offer_code}}). The system will replace the placeholder with the corresponding value. This is useful for custom data not available in other top-level fields like 'to' or 'from'.

Example: {"offer_code":"SUMMER24"}

frontstring

Example: "tmpl_front_abc"

backstring

Example: "tmpl_back_xyz"

sizestring

Example: "4x6"

property name*anyadditional property

curl -i -X POST \
  https://pioneer-api-v1.redocly.app/_mock/openapi/records/send \
  -H 'Content-Type: application/json' \
  -H 'idempotency-key: a7b2c9d8-e1f2-3456-7890-1k2l3m4n5o6p' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "description": "Demo postcard with merge variables",
    "batchId": "daily_lead_upload_20240521",
    "batchDuration": "long",
    "mail_date": "2024-06-20",
    "to": {
      "name": "Alex Ray",
      "address_line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "address_zip": "90210"
    },
    "from": {
      "name": "Pioneer Corp",
      "address_line1": "456 Sender Ave",
      "city": "Senderville",
      "state": "NY",
      "address_zip": "10001"
    },
    "front": "tmpl_front_abc",
    "back": "tmpl_back_xyz",
    "message": "Hello {{to.name}}, don'\''t miss out on our summer sale! Use code {{offer_code}} for 20% off.",
    "merge_variables": {
      "offer_code": "SUMMER24"
    }
  }'

Responses

OK. Standard response for successfully receiving a record for a 'short' duration batch. This status is also returned for an idempotent replay of any previously successful request (both 'short' and 'long'), in which case the idempotency field will be populated.

Bodyapplication/json

messagestringrequired

Example: "Record accepted for short batching."

batchDurationstringrequired

Value"short"

Example: "short"

batchStringstringrequired

The identifier for the batch the record was added to. Use this string to query processed uploads later via /records/get.

Example: "my_crm_direct_mail_q1_promo_postcard"

compilesOnstring(date-time)required

An estimated timestamp for when this batch will be processed if no more records are sent to it.

Example: "2024-05-21T18:13:02.123Z"

countinteger(int32)required

The current number of records received for this batch during its current lifecycle.

Example: 15

idempotencyobject(IdempotencyInfo)

Present if the request was successfully replayed using an Idempotency-Key, indicating a cached response.

Response

application/json

{
  "message": "Record accepted for short batching.",
  "batchDuration": "short",
  "batchString": "my_crm_direct_mail_q1_promo_postcard",
  "compilesOn": "2024-05-21T18:13:02.123Z",
  "count": 15,
  "idempotency": {
    "message": "Request was already processed. Returning cached response.",
    "key": "a7b2c9d8-e1f2-3456-7890-1k2l3m4n5o6p"
  }
}

Get Processed Upload Summaries by Batch

Request

Retrieves summary information about processed uploads from the database that match the provided batchString and are associated with the authenticated API key. This does not retrieve records from a temporary 'short' batch that has not yet been processed.

Security

apiKeyAuth

Bodyapplication/jsonrequired

Specify the batch identifier to retrieve processed upload summaries for.

batchStringstringrequired

The batch identifier to query processed uploads for.

Example: "daily_lead_upload_20240521"

curl -i -X POST \
  https://pioneer-api-v1.redocly.app/_mock/openapi/records/get \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "batchString": "daily_lead_upload_20240521"
  }'

Responses

Successfully retrieved processed upload summaries. The 'uploads' array will be empty if no matching processed uploads are found.

Bodyapplication/json

uploadsArray of objects(UploadSummary)required

An array of processed uploads matching the request. The array is empty if no matches are found.

uploads[]._idstringrequired

The unique identifier of the Upload document in MongoDB.

Example: "65d6a4b2f3e1c2a3b4d5e6f7"

uploads[].batchIdstringrequired

The batch identifier associated with this upload.

Example: "daily_lead_upload_20240521"

uploads[].statusstringrequired

The current processing status of the upload.

Example: "CSV_UPLOADED"

uploads[].createdAtstring(date-time)required

Timestamp when the Upload document was first created.

Example: "2024-02-21T18:12:02.123Z"

uploads[].updatedAtstring(date-time)required

Timestamp when the Upload document was last updated.

Example: "2024-02-21T18:15:30.456Z"

uploads[].originalRecordCountinteger(int32)required

The total number of records in the processed batch.

Example: 150

uploads[].csvGeneratedAtstring(date-time)required

Timestamp when the CSV file for this batch was generated.

Example: "2024-02-21T18:15:29.987Z"

uploads[].s3Keystringrequired

The key of the generated CSV file in S3.

Example: "data/daily_lead_upload_20240521_2024-02-21T18-15-29-987Z.csv"

uploads[].typestringrequired

The type associated with the API key used ('e.g., prod', 'test').

Example: "prod"

Response

application/json

{
  "uploads": [
    { … }
  ]
}

Record Processing API (1.0.5)

General

Records

Send a Single Record

Request

Responses

Was this helpful?

Get Processed Upload Summaries by Batch

Request

Responses

Was this helpful?

Record Processing API (1.0.5)

General

Records

Send a Single Record

RequestExpand all

Responses

Was this helpful?

Get Processed Upload Summaries by Batch

Request

Responses

Was this helpful?

Request