Preview the cost before submitting
Creating a submission consumes credits. To see the cost first, callPOST /api/pricing/estimate with the same blobPaths you intend to submit — nothing else is needed. Do this after uploading your assets and before creating the submission — it is read-only and consumes nothing.
The asset type and MIME type are derived from the blobPath server-side (the same way the submission does), and the price is computed from a metric measured on the uploaded bytes (video duration, document page count) — so the estimate matches what you are charged when you submit. The measurement is cached, so the submission that follows does not re-read the file.
blobPath so you can map it back to the file you sent. The response returns the cost per file plus a totalCredits for the batch:
A file with
priceable: false can’t be priced, and unpriceableReason says why: unreadable (the file is damaged; export it again), password_protected (remove the password), too_many_pixels (an image over about 179 megapixels; downscale it), or page_count / duration (the metric could not be measured). It costs 0 here and is excluded from totalCredits, but it will be rejected when you create the submission, so fix or re-upload it first.Creating a submission
A submission is a request to process one or more uploaded assets. After creating a submission, the API queues your assets for processing. Each asset object carriesblobPath (the path returned by an upload) and, optionally, previousSubmissionId for versioning and a per-asset sidekickIds list (see Choosing sidekicks below). Do not send filename or contentType in asset objects — they are not part of the schema. The other top-level fields are sidekickIds (required — see below), name (an optional display name for the submission, up to 120 characters — defaults to the first asset’s filename if omitted), metadata (an optional arbitrary object), and externalReference (an optional structured {system, ref} reference to the external work item this submission originates from). Unlike metadata, externalReference is returned on the status endpoint and echoed on the asset.processing.* webhook, so an integration can correlate the completion back without keeping its own mapping. Its system is capped at 64 characters and its ref payload must serialize to under 4 KB; exceeding either is rejected with 422.
Choosing sidekicks
sidekickIds is the submission-level list of sidekicks to run for compliance checking. At least one is required — a submission with no sidekick has nothing to check, so a request that omits sidekickIds or sends an empty list is rejected with 422.
To discover which sidekicks your workspace can run — and the asset types each one accepts — call List available sidekicks and use the returned id values. An asset whose type no selected sidekick supports (e.g. a PDF paired only with a video sidekick) is rejected at submit time, so make sure each asset is covered by a sidekick that handles its type.
Per-asset selection (optional). Each asset may also carry its own sidekickIds to run only a subset of the sidekicks on that asset. A per-asset list must be a subset of the submission-level sidekickIds; an empty (or omitted) per-asset list means the asset inherits the full submission-level set. Use this when different assets in one submission need different checks — keep the submission-level list as the union of every asset’s selection.
Single asset submission
Multiple asset submission
Submit multiple assets in a single request for batch processing:contract.pdf narrows its checks to just the document sidekick via its own sidekickIds. The per-asset list stays a subset of the submission-level sidekickIds.
Matching created assets to your inputs
To tell which created asset came from which input, give each asset anexternalId of your own — a file id, a row id from your system, anything up to 255 characters. It is echoed on the matching asset in the response:
externalId is optional. Each one must be unique within the submission (a repeat is rejected with 422), and assets you send without one come back without one.
Attaching tags and supporting context
A submission can also carry top-leveltags and contextItems (both optional). Tags are key/value labels (found-or-created automatically — no pre-creation or UUID lookup needed). Context items are supporting files or links the review can use. Each entry’s applyTo is "all" (default) or a list of asset blobPaths.
A context file is uploaded the same way as an asset — request an upload URL, PUT the bytes, then reference the returned blobPath:
contextType values.
Response format
A successful create returns201 with this shape:
submissionId (not id). You’ll use it to check status and retrieve results.
If a pushed tag is refused by tag governance, the submission still succeeds (201) and the refusal is named in skippedTags instead — see Plain tags and skippedTags.
Safe retries with Idempotency-Key
If a create request times out or the connection drops, you can’t tell whether the submission was created. Retrying without protection risks a second submission — a second review, and a second charge. Send anIdempotency-Key header to make the retry safe. Send the same key again and you get the submission it already created rather than a new one:
How it behaves:
- You choose the key. Up to 255 characters, opaque to us. Derive it from whatever makes the submission unique in your system — a job id, or a UUID you generate and store before the first attempt. Retries of one submission must reuse the key; a new submission needs a new key.
- Keys are scoped to your workspace and do not expire. Reusing a key months later still returns the original submission.
- Concurrent requests are safe. If two requests with the same key arrive at once, one submission is created and both receive it.
- A replay describes the same submission — the same
submissionId,workflowId,ablyChanneland assets, and thestatusthe original201reported. It is rebuilt rather than stored, so three things can differ from the first response:skippedTagsis always empty (refused tags were reported on the original response only); an asset’sversionGroupIdreflects any newer version submitted since; and assets are listed in your retry’s order, matched byexternalId— or, for assets sent without one, by filename. Two unlabelled assets with the same filename can’t be told apart, so they may come back in either order: give them anexternalIdif you need to know which is which. To see where the submission is now, callGET /api/submissions/{submission_id}. - Check the
Idempotent-Replayed: trueheader to tell a replay apart, rather than relying on the200status alone. - Re-uploading before a retry is fine. Each upload returns a new
blobPath, so requests are compared on the file name in eachblobPath— including the paths in a tag’s or context item’sapplyTo— not the full path. - List order doesn’t matter.
assets,sidekickIds,tags,contextItemsandapplyToare compared as sets, so a retry may list them in any order. Everything else —name,metadata,externalReference— is compared exactly as sent. - Same key, different request →
409. Changing the files, sidekicks, tags,externalIds or anything else under the same key is treated as a mistake rather than answered with a submission you didn’t ask for. Use a new key. - The header is optional. Without it, every request creates a new submission.
Asset versioning
Versioning is explicit. To create a new version of an asset, submit a new submission whose asset references the prior asset throughpreviousSubmissionId. The new submission becomes the next version in the same version group.
1
Upload the revised file
Upload the corrected file and get its
blobPath.2
Reference the previous submission
Include
previousSubmissionId on the asset so the API links it as the next version.3
List versions
Use
/submissions/{submission_id}/versions to list all versions in the group.Batch submission example
A complete example of uploading multiple files and creating a batch submission:Status transitions
A submission moves through the statuses below. The terminal states arecomplete, partial, and failed.
A live create returns
queued, not submitted. Because assets are admitted to review a few at a time, a submission flips to processing as soon as any asset starts and stays there until every asset has settled — so part of its work may still be waiting while it reads processing.
There is no created, completed, or processed status. Use complete for the all-success terminal state and partial for a mixed outcome.
Error handling
If submission creation fails, check these common cases.Invalid blob path (403)
blobPath matches the value returned by the upload endpoint exactly.
Previous submission not found (404)
previousSubmissionId does not resolve to a submission in your workspace.
Asset already submitted (409)
blobPath has already been submitted. Use versioning with previousSubmissionId to create a new version.
Idempotency-Key reused for a different request (409)
Idempotency-Key already created a submission from a different request body. Nothing was created. If this is a new submission, send a new key — see Safe retries with Idempotency-Key.
Request validation failed (422)
sidekickIdsmissing or empty — at least one sidekick is required (see Choosing sidekicks).- A per-asset
sidekickIdsis not a subset of the submission-levelsidekickIds. - Two assets share an
externalId— each must be unique within the submission. - An asset’s type has no compatible sidekick — e.g. a PDF submitted only with a video sidekick.
Best practices
- Upload with presigned URLs — request a URL per file and
PUTthe bytes straight to Azure Blob Storage. - Batch related assets — group related files into one submission.
- Version explicitly — use
previousSubmissionIdrather than re-submitting the same path. - Handle retries — implement exponential backoff for transient failures, and send an
Idempotency-Keyso a retried create can’t make a duplicate. - Label assets with
externalId— match created assets to your inputs by identity, not list position. - Log submission IDs — save the
submissionIdfor audit trails and support.