Fieldloop Batches and Receipts
Definition
Submit captured application records to an existing source with a Fieldloop Submission key from Admin → API Keys. New keys carry that capability across the workspace. Configure the intended Project/source; older key restrictions and current permissions remain enforced. Receipt reads belong to the original submitter.
Submit a batch
Replace the fictional record with selected, redacted data in batch.json. Your application owns source_event_id. Each log needs RFC3339 occurred_at and at least one of input, output, messages, trajectory or action. Optional feedback is nested in its log; source relationships use provider_ref, session_ref and trace_ref.
Use the Project URL from the quickstart, an existing issued source ID and one logical batch key. Preserve the exact file/key for uncertain retries.
POST /v1/organizations/{organizationKey}/projects/{projectId}/fieldloop/sources/{sourceId}/batches
Authorization: Bearer <credential from your secret mechanism>
Content-Type: application/json
Idempotency-Key: <application-owned logical batch key>
{
"logs": [{
"source_event_id": "support-ticket-1042:reply",
"occurred_at": "2026-10-31T09:30:00Z",
"input": {"question": "Has my bicycle shipped?"},
"output": {"reply": "Your bicycle is being packed."},
"context": {"application": "Bicycle Shop"}
}]
}
SOURCE_URL="${PROJECT_URL}/fieldloop/sources/${TEAMMATELY_FIELDLOOP_SOURCE}"
curl --fail-with-body \
--header "Authorization: Bearer ${TEAMMATELY_API_KEY}" \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: ${BATCH_OPERATION_KEY}" \
--data-binary @batch.json \
"${SOURCE_URL}/batches"
Read the receipt
202 acknowledges durable receipt of the bytes. Retain data.batch_id:
| Field | Interpretation |
|---|---|
batch_id, source_id, sequence | Issued identity and destination order |
status | uploading, received, processing, processed, failed, cancelled or deleted |
row_count | Submitted population |
accepted_count, duplicate_count | Accepted records and recognized duplicates |
conflict_count, rejected_count | Rows requiring inspection |
rows, safe_error_code | Per-row outcomes and error code when returned |
processed can include rejected/conflicting rows. Polling reads an existing batch rather than submitting another one.
curl --fail-with-body \
--header "Authorization: Bearer ${TEAMMATELY_API_KEY}" \
"${SOURCE_URL}/batches/${BATCH_ID}"
Recovery and inspection
Replay a lost response with identical bytes/key. Retain source records until admission is known. Inspect Fieldloop → Logs for original content and processing state. Source consent, Threads and Case creation are separate workflows.
SDK guides cover continuous ingestion. FieldloopBatch, FieldloopLog and FieldloopReceiptEnvelope in the OpenAPI define request/receipt fields.