Resources
The objects the API returns and how they reference each other. Endpoint pages link each field's type to its definition here.
JobResult
The v1 job result. The same object is returned by the synchronous response, the poll, and every future result surface.
| Field | Type | Description | Required |
|---|---|---|---|
| jobId | string (uuid) | Single job identity, shared by every path that references this job. | Yes |
| status | JobStatus | Lifecycle status of a job. verdict is present only when completed. rejected is reserved for future use and is not currently produced. | Yes |
| verdict | Verdict | Overall verdict for a completed job, with per-dimension breakdown. Present only when status is completed. | No |
| expertReview | ExpertReview | Present when a verification specialist has reviewed this job. Single-file jobs only. | No |
| error | JobResultError | Why a job ended in error or rejected status; present only for those statuses. Uses the same code vocabulary as endpoint errors. | No |
| metadata | object | Caller-supplied metadata, echoed back verbatim. | No |
| createdAt | string (date-time) | When the job was created (ISO 8601). | Yes |
| completedAt | string (date-time) | When processing finished (ISO 8601). | No |
Verdict
Overall verdict for a completed job, with per-dimension breakdown. Present only when status is completed.
| Field | Type | Description | Required |
|---|---|---|---|
| assessment | string | Headline, customer-actionable assessment (e.g. ai_generated). | Yes |
| confidence | ConfidenceLevel | Qualitative confidence in the enclosing assessment: the verdict's overall call, or a single dimension's result. | Yes |
| display | VerdictDisplay | Rendered English copy for a verdict. assessment remains the stable machine key; branch and localize off that, never off these strings. Absent on jobs completed before this copy was stored. | No |
| dimensions | array<Dimension> | The axes of analysis behind the verdict, each with its own result. | Yes |
Dimension
An axis of analysis carrying its own aggregated result.
| Field | Type | Description | Required |
|---|---|---|---|
| key | string | Stable identifier of the dimension, e.g. ai_detection. | Yes |
| label | string | Human-readable name of the dimension. | Yes |
| assessment | string | Aggregated assessment for this dimension. | No |
| score | number | Aggregated numeric score in [0, 1]. | Yes |
| confidence | ConfidenceLevel | Qualitative confidence in the enclosing assessment: the verdict's overall call, or a single dimension's result. | No |
VerdictDisplay
Rendered English copy for a verdict. assessment remains the stable machine key; branch and localize off that, never off these strings. Absent on jobs completed before this copy was stored.
| Field | Type | Description | Required |
|---|---|---|---|
| label | string | Short badge or table-cell copy, e.g. Inconclusive. | Yes |
| title | string | Headline for the main result indicator. | No |
| description | string | Supporting sentence shown under the headline. | No |
ExpertReview
Present when a verification specialist has reviewed this job. Single-file jobs only.
| Field | Type | Description | Required |
|---|---|---|---|
| verdict | ExpertReviewVerdict | The specialist's overall verdict override. Present when the specialist overrode the overall verdict; the job's top-level verdict field keeps returning the automated result either way. | No |
| dimensions | array<ExpertReviewDimension> | The dimensions the specialist overrode. Dimensions not listed here stand as the automated analysis reported them. | Yes |
| confidence | ConfidenceLevel | The specialist's confidence in this review. | Yes |
| notes | string | The specialist's note to you, when they left one. | No |
| reviewedAt | string (date-time) | When the review was completed (ISO 8601). | Yes |
ExpertReviewVerdict
The specialist's overall verdict override. Present when the specialist overrode the overall verdict; the job's top-level verdict field keeps returning the automated result either way.
| Field | Type | Description | Required |
|---|---|---|---|
| assessment | string | The specialist's overall verdict. | Yes |
| display | VerdictDisplay | Rendered copy for the specialist's verdict. | No |
ExpertReviewDimension
One dimension the specialist overrode.
| Field | Type | Description | Required |
|---|---|---|---|
| key | string | Stable identifier of the dimension, from the same vocabulary as verdict.dimensions[].key. | Yes |
| label | string | Human-readable name of the dimension. | Yes |
| assessment | string | The specialist's finding for this dimension. Categorical: an expert review carries no numeric score. | Yes |
ConfidenceLevel
Qualitative confidence in the enclosing assessment: the verdict's overall call, or a single dimension's result.
Values: high, medium, low
JobStatus
Lifecycle status of a job. verdict is present only when completed. rejected is reserved for future use and is not currently produced.
Values: processing, completed, error, rejected
JobSummary
Compact summary of one job in a list; GET /v1/jobs/{jobId} returns the full result.
| Field | Type | Description | Required |
|---|---|---|---|
| id | string (uuid) | Job identifier: the jobId accepted by GET /v1/jobs/{jobId}. | Yes |
| applicationId | string | The application the job belongs to. | Yes |
| metadata | object | Caller-supplied metadata, echoed back verbatim. {} when the submission carried none. | Yes |
| createdAt | string (date-time) | null | When the job was created (ISO 8601). | Yes |
| updatedAt | string (date-time) | null | When the job last changed (ISO 8601). | Yes |
PaginationMeta
Page-based pagination metadata for list responses.
| Field | Type | Description | Required |
|---|---|---|---|
| page | integer | The page this response contains, counted from 1. | Yes |
| pageSize | integer | Number of jobs per page used for this response. | Yes |
| total | integer | Total number of jobs across all pages. | Yes |
| totalPages | integer | Total number of pages at this pageSize. | Yes |
| hasNextPage | boolean | true when a page after this one exists. | Yes |
JobResultError
Why a job ended in error or rejected status; present only for those statuses. Uses the same code vocabulary as endpoint errors.
| Field | Type | Description | Required |
|---|---|---|---|
| code | ErrorCode | Stable machine-readable error code. The same vocabulary is used by every endpoint and by jobs in error or rejected status. | Yes |
| message | string | Human-readable explanation of why the job failed. | Yes |
ApiError
Standard error response returned by every public endpoint (Decision 5C).
| Field | Type | Description | Required |
|---|---|---|---|
| code | ErrorCode | Stable machine-readable error code. The same vocabulary is used by every endpoint and by jobs in error or rejected status. | Yes |
| message | string | Human-readable explanation of the error. | Yes |
| details | object | Optional structured context for the error (e.g. the offending field). | No |
| retryAfter | integer | Seconds to wait before retrying. Set for rate_limited and service_unavailable. | No |
ErrorCode
Stable machine-readable error code. The same vocabulary is used by every endpoint and by jobs in error or rejected status.
Values: invalid_request, unsupported_format, unauthorized, forbidden, not_found, file_too_large, unprocessable, rate_limited, internal_error, service_unavailable
See Error codes for what each code means and how to respond.