> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Poll Transactions
> Stedi Core-compatible **Poll Transactions**. Returns transactions in ascending processing order so an incremental consumer can follow the stream without gaps.
Supply either `startDateTime` (initial poll) **or** `pageToken` (subsequent polls) — at least one is required. Unlike the list endpoint, polling **always** returns a `nextPageToken`, including on an empty page: when no new transactions are ready, the token re-encodes your current position rather than advancing the cursor, so no transaction can be skipped by a concurrent webhook or a delayed retry. Persist the token and pass it back on the next poll.
## Overview
Returns transactions **in ascending processing order** so an incremental consumer can follow the stream without missing anything. This is a 1:1 drop-in for Stedi's [Poll Transactions](https://www.stedi.com/docs/healthcare/api-reference/get-poll-transactions) operation.
Use polling when you want to mirror every transaction into your own system: keep the returned `nextPageToken`, wait, then call again with that token. Use [List Transactions](/api-reference/endpoint/stedi/list-transactions) when you want to search or browse history.
## Authentication
JWT Bearer token from [`POST /api/token`](/api-reference/endpoint/token), with the `api-access` feature.
## Query parameters
ISO 8601 date-time for the **initial** poll, e.g. `2026-10-01T00:00:00Z`. Only transactions processed after this time are returned. Required on the first call when you do not yet have a `pageToken`.
Cursor from the previous poll's `nextPageToken`. Pass this on every poll after the first. If both `pageToken` and `startDateTime` are supplied, the token takes precedence.
Maximum transactions per poll, `1`–`500`. Defaults to `100`.
You must supply **at least one** of `pageToken` or `startDateTime`; otherwise the request returns `400 BadRequestException`.
## Example
First poll, then continue with the returned cursor:
```bash theme={null}
# Initial poll
curl "https://forecaster.cairhealth.com/api/stedi/2023-08-01/polling/transactions?startDateTime=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# Subsequent poll — reuse nextPageToken from the previous response
curl "https://forecaster.cairhealth.com/api/stedi/2023-08-01/polling/transactions?pageToken=$NEXT_PAGE_TOKEN" \
-H "Authorization: Bearer $ACCESS_TOKEN"
```
A polling loop:
```ts theme={null}
async function poll(cursor?: string) {
const url = new URL(
'https://forecaster.cairhealth.com/api/stedi/2023-08-01/polling/transactions',
);
if (cursor) {
url.searchParams.set('pageToken', cursor);
} else {
url.searchParams.set('startDateTime', new Date().toISOString());
}
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.CAIR_ACCESS_TOKEN}` },
});
const page = await response.json();
for (const transaction of page.items) {
await handleTransaction(transaction);
}
// Always persist this token, even when items is empty.
return page.nextPageToken as string;
}
```
## Response
```json theme={null}
{
"items": [
{
"transactionId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
"fileExecutionId": "ffeeddccbbaa99887766554433221100",
"status": "succeeded",
"direction": "OUTBOUND",
"mode": "production",
"processedAt": "2026-10-05T15:00:00.000Z",
"artifacts": [
{
"artifactType": "application/edi-x12",
"usage": "input",
"sizeBytes": 4096,
"url": "https://forecaster.cairhealth.com/api/stedi/2023-08-01/transactions/a1b2c3d4e5f60718293a4b5c6d7e8f90/input",
"model": "transaction"
}
],
"partnership": {
"partnershipId": "local-clearinghouse",
"partnershipType": "x12",
"sender": { "profileId": "local" },
"receiver": { "profileId": "clearinghouse" }
},
"x12": {
"metadata": {
"interchange": { "acknowledgmentRequestedCode": "0", "controlNumber": 43 },
"functionalGroup": {
"controlNumber": 2,
"release": "005010X222A1",
"date": "2026-10-05",
"time": "15:00:00",
"functionalIdentifierCode": "HC"
},
"transaction": { "controlNumber": "0001", "transactionSetIdentifier": "837" },
"sender": { "applicationCode": "ZZ", "isa": { "qualifier": "ZZ", "id": "SUBMITTER" } },
"receiver": { "applicationCode": "ZZ", "isa": { "qualifier": "ZZ", "id": "RECEIVER" } }
}
}
}
],
"nextPageToken": "1f2e3d4c5b6a79880716253443526170"
}
```
## Cursor semantics
Unlike the list endpoint, polling **always returns a `nextPageToken`**, including when `items` is empty.
* On a **full or partial page**, the token points at the last returned transaction. Call again immediately to continue.
* On an **empty page**, the token re-encodes your current position rather than jumping to the present. This guarantees zero gaps: a webhook that arrives slightly out of order, or an uploaded X12 with a historical `processedAt`, is still delivered on a later poll.
* Never discard the token on an empty page — that is how the stream advances.
There is a short maturity delay of a few seconds before a transaction becomes pollable, so an in-flight insert cannot be observed half-written. A transaction may therefore appear a few seconds after it is created.
## Stop condition
Polling is a never-ending stream by design; decide your own cadence (for example every 30 seconds) and stop when your process exits. Reuse the same cursor across restarts so you do not miss or duplicate the boundary transaction.
## OpenAPI
````yaml GET /api/stedi/2023-08-01/polling/transactions
openapi: 3.1.0
info:
title: Cair Health APIs
description: APIs for the Cair Health platform
license:
name: MIT
version: 1.0.0
servers:
- url: https://forecaster.cairhealth.com
security:
- bearerAuth: []
paths:
/api/stedi/2023-08-01/polling/transactions:
get:
summary: Poll transactions
description: >-
Stedi Core-compatible **Poll Transactions**. Returns transactions in
ascending processing order so an incremental consumer can follow the
stream without gaps.
Supply either `startDateTime` (initial poll) **or** `pageToken`
(subsequent polls) — at least one is required. Unlike the list endpoint,
polling **always** returns a `nextPageToken`, including on an empty
page: when no new transactions are ready, the token re-encodes your
current position rather than advancing the cursor, so no transaction can
be skipped by a concurrent webhook or a delayed retry. Persist the token
and pass it back on the next poll.
operationId: stediPollTransactions
parameters:
- name: pageSize
in: query
required: false
description: >-
Maximum number of transactions to return in a page (1–500). Defaults
to 100.
schema:
type: integer
minimum: 1
maximum: 500
default: 100
- name: pageToken
in: query
required: false
description: >-
Cursor returned as `nextPageToken` by the previous poll. Pass this
on every poll after the first. Mutually exclusive with
`startDateTime` (the token wins).
schema:
type: string
- name: startDateTime
in: query
required: false
description: >-
ISO 8601 date-time for the initial poll, e.g.
`2026-10-01T00:00:00Z`. Only transactions after this time are
returned. Required on the first poll when no `pageToken` is
available.
schema:
type: string
format: date-time
responses:
'200':
description: A page of new transactions. `nextPageToken` is always present.
content:
application/json:
schema:
$ref: '#/components/schemas/StediPollTransactionsResponse'
example:
items:
- transactionId: a1b2c3d4e5f60718293a4b5c6d7e8f90
fileExecutionId: ffeeddccbbaa99887766554433221100
status: succeeded
direction: OUTBOUND
mode: production
processedAt: '2026-10-05T15:00:00.000Z'
artifacts:
- artifactType: application/edi-x12
usage: input
sizeBytes: 4096
url: >-
https://forecaster.cairhealth.com/api/stedi/2023-08-01/transactions/a1b2c3d4e5f60718293a4b5c6d7e8f90/input
model: transaction
partnership:
partnershipId: local-clearinghouse
partnershipType: x12
sender:
profileId: local
receiver:
profileId: clearinghouse
x12:
metadata:
interchange:
acknowledgmentRequestedCode: '0'
controlNumber: 43
functionalGroup:
controlNumber: 2
release: 005010X222A1
date: '2026-10-05'
time: '15:00:00'
functionalIdentifierCode: HC
transaction:
controlNumber: '0001'
transactionSetIdentifier: '837'
sender:
applicationCode: ZZ
isa:
qualifier: ZZ
id: SUBMITTER
receiver:
applicationCode: ZZ
isa:
qualifier: ZZ
id: RECEIVER
nextPageToken: 1f2e3d4c5b6a79880716253443526170
'400':
description: Invalid query parameter, cursor, or filter combination.
content:
application/json:
schema:
$ref: '#/components/schemas/StediError'
'401':
description: Missing or invalid Cair access token.
content:
application/json:
schema:
$ref: '#/components/schemas/StediError'
'500':
description: Unexpected server error while reading transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/StediError'
security:
- bearerAuth: []
components:
schemas:
StediPollTransactionsResponse:
type: object
required:
- items
- nextPageToken
properties:
items:
type: array
items:
$ref: '#/components/schemas/StediTransactionSummary'
nextPageToken:
type: string
description: >-
Always present. Pass it back on the next poll. On an empty page it
encodes your current position so no transactions are skipped.
StediError:
type: object
description: Stedi-compatible error envelope.
required:
- message
properties:
message:
type: string
description: Human-readable error message.
code:
type: string
description: Stedi error code.
enum:
- BadRequestException
- UnauthorizedException
- AccessDeniedException
- ResourceNotFoundException
- UnprocessableEntityException
- ServiceException
StediTransactionSummary:
type: object
description: A processed transaction, matching Stedi Core `TransactionSummary`.
required:
- transactionId
- fileExecutionId
- status
- direction
- mode
- processedAt
- artifacts
- partnership
properties:
transactionId:
type: string
description: Unique transaction identifier.
fileExecutionId:
type: string
description: Identifier of the file execution the transaction belongs to.
status:
type: string
enum:
- succeeded
- failed
direction:
type: string
enum:
- INBOUND
- OUTBOUND
- UNKNOWN
mode:
type: string
enum:
- test
- production
- other
processedAt:
type: string
format: date-time
description: >-
When the transaction was processed, ISO 8601. For uploaded /
EOB-converted X12 this is the historical check date from the X12
`GS04` header.
artifacts:
type: array
description: >-
Downloadable artifacts. Only `input` and `output` artifacts are
returned; URLs point back at Cair.
items:
$ref: '#/components/schemas/StediArtifact'
partnership:
$ref: '#/components/schemas/StediPartnership'
x12:
type: object
required:
- metadata
properties:
metadata:
$ref: '#/components/schemas/StediX12Metadata'
transactionSetting:
type: object
properties:
guideId:
type: string
transactionSettingId:
type: string
fragments:
type: object
properties:
keyName:
type: string
fragmentCount:
type: integer
batchSize:
type: integer
translationErrors:
type: array
description: >-
Details about errors that prevented Cair from processing the
transaction.
items:
$ref: '#/components/schemas/StediTranslationError'
businessIdentifiers:
type: array
description: Business identifiers extracted from the transaction.
items:
$ref: '#/components/schemas/StediBusinessIdentifier'
StediArtifact:
type: object
description: A downloadable artifact associated with a transaction.
required:
- artifactType
- usage
- sizeBytes
- url
- model
properties:
artifactType:
type: string
description: The MIME type of the artifact.
enum:
- text/csv
- application/edifact
- application/filepart
- application/json
- application/pdf
- text/psv
- text/tsv
- application/edi-x12
- application/xml
- application/zip
- image/jpeg
- image/png
- image/tiff
- text/plain
- unknown
usage:
type: string
description: The role the artifact plays in the transaction.
enum:
- attachment
- input
- metadata
- output
sizeBytes:
type: integer
description: Artifact size in bytes.
minimum: 0
url:
type: string
description: >-
Cair-hosted download URL. Following it returns a `302` to a
presigned artifact URL.
model:
type: string
description: The artifact model.
enum:
- execution
- fragment
- transaction
- fault
StediPartnership:
type: object
description: The EDI partnership the transaction was exchanged on.
required:
- partnershipId
- partnershipType
- sender
- receiver
properties:
partnershipId:
type: string
description: Partnership identifier, e.g. `local-clearinghouse`.
partnershipType:
type: string
enum:
- x12
- edifact
sender:
type: object
required:
- profileId
properties:
profileId:
type: string
receiver:
type: object
required:
- profileId
properties:
profileId:
type: string
StediX12Metadata:
type: object
description: >-
Metadata parsed from the X12 interchange, functional group, and
transaction headers.
required:
- interchange
- functionalGroup
- transaction
- sender
- receiver
properties:
interchange:
type: object
required:
- acknowledgmentRequestedCode
- controlNumber
properties:
acknowledgmentRequestedCode:
type: string
description: X12 `ISA14`.
controlNumber:
type: integer
minimum: 0
maximum: 999999999
functionalGroup:
type: object
required:
- controlNumber
- release
- date
- time
- functionalIdentifierCode
properties:
controlNumber:
type: integer
minimum: 0
maximum: 999999999
release:
type: string
description: Implementation guide version, e.g. `005010X221A1`.
date:
type: string
description: '`YYYY-MM-DD`.'
time:
type: string
description: '`HH:MM:SS`.'
functionalIdentifierCode:
type: string
description: X12 `GS01`, e.g. `HC`, `HP`.
transaction:
type: object
required:
- controlNumber
- transactionSetIdentifier
properties:
controlNumber:
type: string
transactionSetIdentifier:
type: string
description: 3-digit X12 transaction set ID, e.g. `835`.
sender:
$ref: '#/components/schemas/StediX12Profile'
receiver:
$ref: '#/components/schemas/StediX12Profile'
StediTranslationError:
type: object
required:
- message
properties:
message:
type: string
context:
type: object
properties:
code:
type: string
schemaPath:
type: string
mark:
type: object
properties:
start:
type: object
required:
- line
- column
properties:
line:
type: integer
column:
type: integer
end:
type: object
required:
- line
- column
properties:
line:
type: integer
column:
type: integer
StediBusinessIdentifier:
type: object
description: A business identifier extracted from the transaction.
required:
- elementId
- element
- name
- value
properties:
elementId:
type: string
description: X12 element ID, e.g. `1028` or `127`.
element:
type: string
description: The element where the value was found, e.g. `CLP-01`.
name:
type: string
description: Human-readable name of the identifier.
value:
type: string
description: The identifier value.
StediX12Profile:
type: object
required:
- applicationCode
- isa
properties:
applicationCode:
type: string
isa:
type: object
required:
- qualifier
- id
properties:
qualifier:
type: string
id:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.