> ## Documentation Index > Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Get an underwriting file > An underwriting file with its view as you may see it now: each offer's `id` and `stage`, the `ratings` it needs and holds, and the engine's own fields for its view `format`, such as what blocks each offer, decisions, outcomes and the questions to answer next. Tolerate fields you do not know. `actingAs` is who you act as; `lastSeq` is what to send as `after`. Every write returns this same view after its change. The view is computed from the stored log and ratings when you read it, so time-based rules (quote validity, lapses) are current. Requires read access to the file; missing or inaccessible files return 404. Read-only. ## OpenAPI ````yaml /openapi.json get /insurance/underwriting/files/{fileId} openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://api.effectiveai.app/api/v2 description: Production security: - bearerAuth: [] paths: /insurance/underwriting/files/{fileId}: get: tags: - Underwriting workbench summary: Get an underwriting file description: >- An underwriting file with its view as you may see it now: each offer's `id` and `stage`, the `ratings` it needs and holds, and the engine's own fields for its view `format`, such as what blocks each offer, decisions, outcomes and the questions to answer next. Tolerate fields you do not know. `actingAs` is who you act as; `lastSeq` is what to send as `after`. Every write returns this same view after its change. The view is computed from the stored log and ratings when you read it, so time-based rules (quote validity, lapses) are current. Requires read access to the file; missing or inaccessible files return 404. Read-only. operationId: getUnderwritingFile parameters: - schema: type: string format: uuid description: >- Underwriting file ID: the `id` of `createUnderwritingFile` or `listUnderwritingFiles`. required: true description: >- Underwriting file ID: the `id` of `createUnderwritingFile` or `listUnderwritingFiles`. name: fileId in: path responses: '200': description: The underwriting file and its view. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingFileDetail' '400': description: >- Invalid request, manual sources with errors, or rater bindings that do not match; `details` names each problem. Restart a list after `invalid_cursor`. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '403': description: >- `authority_required`: your role may not make this statement, another may. `underwriting_role_required`: you have no underwriting role. Or access is denied. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '404': description: Manual or underwriting file not found, or not visible to you. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '409': description: >- `stale_after`: the log moved past `after`; read the underwriting file and resend with `lastSeq`. `file_closed` or `wrong_stage`: the file or offer is not where the statement needs it. `offer_blocked`: something open (`blockers`) holds the offer a quote or bind is for. `rating_not_valid`: that offer has no valid rating of its current inputs (`rating` says why and how to recover). `target_stale`: the statement's `target` is not in the file's view for you now; read the file again. `idempotency_conflict`: the key was used with another request. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '413': description: Request body is too large. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '415': description: Content-Type must be application/json. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '422': description: >- `statement_rejected`: the manual cannot apply it (type, path or another rule); `no_route`: no one may do it. `target_wrong_kind`: that node does not take this statement; `target_wrong_scope`: the statement's path, choice, offer or package is not the node's. `statementIndex` (and `target`) say which. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' '503': description: >- `temporarily_unavailable`: the underwriting runtime is not configured on this server yet, or could not answer. Honor Retry-After. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingError' security: - bearerAuth: [] components: schemas: V2UnderwritingFileDetail: type: object properties: file: $ref: '#/components/schemas/V2UnderwritingFile' lastSeq: type: integer description: Send as `after` with your next statements. actingAs: $ref: '#/components/schemas/V2UnderwritingActor' view: $ref: '#/components/schemas/V2UnderwritingView' required: - file - lastSeq - actingAs - view V2UnderwritingError: allOf: - $ref: '#/components/schemas/V2CodedError' - type: object properties: runtimeCode: type: string description: >- For underwriting refusals: the underwriting runtime’s own code, for diagnosis only. Act on `code`. statementIndex: type: integer nullable: true description: >- For underwriting refusals: the index of the statement it is about, when known. lastSeq: type: integer description: >- The underwriting file log’s last seq, for stale_after: send it as `after` after re-reading. target: type: string nullable: true description: >- The view node id a target_stale, target_wrong_kind or target_wrong_scope statement named. offer: type: string description: >- The offer a wrong_stage, offer_blocked or rating_not_valid quote or bind was for, when the server read it. blockers: type: array items: type: string description: >- For offer_blocked: the ids of the view nodes that hold the offer. rating: type: object properties: status: type: string description: >- The offer's rating status (`rating.status` of its view): `pending`, `stale`, `refused`, `unavailable`, or `incomplete` when inputs it needs are not accepted. runIds: type: array items: type: string description: The runs its outcomes are valued from. waitingOn: type: array items: type: string description: The paths the price waits on. recovery: type: string nullable: true description: What makes the rating valid again. required: - status - runIds - waitingOn - recovery description: >- For rating_not_valid: why the offer’s price is not usable, and how to recover. V2UnderwritingFile: type: object properties: id: type: string description: >- Stable underwriting file ID; also the ID of its underwriting submission record. title: type: string status: type: string enum: - draft - received - in_review - needs_information - accepted_for_quoting - declined - withdrawn description: The record status people set. agencyAccountId: type: string description: The agency account (the insured). Access follows it. productId: type: string nullable: true underwriterIds: type: array items: type: string description: Users assigned to underwrite it. manualId: type: string pattern: ^[a-f0-9]{64}$ description: The manual it is pinned to for good. lastSeq: type: integer description: >- Its last log entry, as of its latest change. Send the `lastSeq` of `getUnderwritingFile` as `after` with the next statements. stages: type: array items: $ref: '#/components/schemas/V2UnderwritingStage' description: The offers' stages after its latest change, in stage order. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - title - status - agencyAccountId - productId - underwriterIds - manualId - lastSeq - stages - createdAt - updatedAt V2UnderwritingActor: type: object properties: userId: type: string side: type: string enum: - carrier - broker - customer role: type: string description: 'The role you act and read in: your first role.' roles: type: array items: type: string description: Every role your organization maps you to. owner: type: string nullable: true description: The carrier a carrier acts for; null when the manual has one. human: type: boolean description: False for an API key or agent acting for its owner. required: - userId - side - role - roles - owner - human description: Who you act as here. V2UnderwritingView: type: object properties: format: type: string description: >- The engine’s view format, such as `rsl.workbench/1`; it names the schema of every other field. lastSeq: type: integer minimum: 0 description: The log seq the view was read at. offers: type: array items: $ref: '#/components/schemas/V2UnderwritingViewOffer' ratings: type: array items: $ref: '#/components/schemas/V2UnderwritingRatingRequest' description: >- Every rating the file needs or holds. A quote or bind needs each rating its offer reads to be `current`. required: - format - lastSeq - offers - ratings additionalProperties: nullable: true description: >- The workbench view as you may see it now. `format`, `lastSeq`, the offers’ `id` and `stage`, and `ratings` are this API’s contract; every other field is defined by the engine’s view `format`. Tolerate fields you do not know. V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. dataset: type: string enum: - naic - osha description: Dataset needed for dataset_not_enabled. businessCode: type: string description: The rater’s own refusal code, for business_rejection. violations: type: array items: type: object properties: code: type: string description: Authored or built-in constraint code message: type: string description: Authored message for the failed constraint path: type: string description: Input path of the offending value; empty for the request value: nullable: true description: Offending input value, size-bounded by the runtime constraint: type: string description: The constraint the value failed, as text cite: type: string nullable: true description: >- Filing citation of the constraint, when the source cites one required: - code - message - path - value - constraint - cite additionalProperties: false maxItems: 256 description: >- Each input constraint the submission failed, for invalid_inputs and business_rejection. violationsTruncated: type: boolean description: >- True when the rater reported more violations than violations holds. executionId: type: string description: >- The recorded execution of a failed rating, for rater rating failures. accessUrl: type: string nullable: true format: uri description: Not currently returned. required: - code V2UnderwritingStage: type: string enum: - absent - not_offered - declined - gather - indicated - quotable - quoted - bound - withdrawn description: >- An offer's stage: `absent` or `not_offered` before it is offered, `declined` or `withdrawn` when out, else `gather`, `indicated`, `quotable`, `quoted`, `bound`. V2UnderwritingViewOffer: type: object properties: id: type: string description: The offer’s stable view id; send it as a statement’s `target`. stage: allOf: - $ref: '#/components/schemas/V2UnderwritingStage' - nullable: true required: - id - stage additionalProperties: nullable: true description: 'An offer: its id and stage, and the engine’s fields for it.' V2UnderwritingRatingRequest: type: object properties: id: type: string description: >- Stable id of this rating: one per offer group and rater. Its `inputsDigest` changes when the inputs do. offers: type: array items: type: string description: The offers whose price reads it. rater: type: object properties: raterId: type: string description: '`raterId` of the rate route.' releaseVersion: type: integer minimum: 1 description: '`releaseVersion` of the rate route.' required: - raterId - releaseVersion description: 'The rater release to rate with: the manual’s binding.' package: type: string description: The hosted rater package the manual names, such as `imperium/g2`. bundleId: type: string description: >- The exact bundle the manual is bound to; the runtime rates with it alone. inputs: type: object additionalProperties: nullable: true description: >- The exact `inputs` the runtime rates with: what `POST /v2/insurance/raters/{raterId}/releases/{releaseVersion}/rate` takes. inputsDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- `sha256:` and the SHA-256 of the canonical JSON of `inputs` (keys sorted, no whitespace). A run answers the request whose digest it carries. status: type: string enum: - needed - current - stale - refused description: >- `needed`: not rated yet (see `reason`). `stale`: rated, but for earlier inputs, and not yet for these (see `reason`). `current`: the kept run answers these inputs. `refused`: the rater refused these inputs; change them. reason: type: string enum: - not_permitted - unavailable description: >- For `needed` or `stale`: why the latest change did not rate it. `not_permitted`: the writer may not run the rater (`raters:run`); it is rated by the next change someone who may run it makes. `unavailable`: the rater could not answer; any later change rates it. runId: type: string description: The kept run (`current`, `refused`). required: - id - offers - rater - package - bundleId - inputs - inputsDigest - status description: >- A rating the file needs or holds. The runtime rates it with the bound bundle when a change makes it needed; each run has a rater execution record. V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.