> ## Documentation Index > Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Start an underwriting file > An underwriting file: one insured's underwriting submission for an agency account, run on one underwriting manual for its whole life. Send first `statements`, such as opening it on a product and the first answers, to record them in the same call; the response is the file, its view and what was recorded, as `recordUnderwritingFileStatements` returns. Who you act as comes from your organization's underwriting roles, never from the request: you act in your first role. Statements the manual refuses are refused before anything is created. Requires edit access to the agency account; the file inherits its access. Not idempotent: after an uncertain response, list underwriting files before retrying. ## OpenAPI ````yaml /openapi.json post /insurance/underwriting/files 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.canary.effectiveai.app/api/v2 description: Canary security: - bearerAuth: [] paths: /insurance/underwriting/files: post: tags: - Underwriting workbench summary: Start an underwriting file description: >- An underwriting file: one insured's underwriting submission for an agency account, run on one underwriting manual for its whole life. Send first `statements`, such as opening it on a product and the first answers, to record them in the same call; the response is the file, its view and what was recorded, as `recordUnderwritingFileStatements` returns. Who you act as comes from your organization's underwriting roles, never from the request: you act in your first role. Statements the manual refuses are refused before anything is created. Requires edit access to the agency account; the file inherits its access. Not idempotent: after an uncertain response, list underwriting files before retrying. operationId: createUnderwritingFile requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingFileCreate' responses: '201': description: >- The new underwriting file, its view and what its first statements recorded. content: application/json: schema: $ref: '#/components/schemas/V2UnderwritingWriteResult' '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: V2UnderwritingFileCreate: type: object properties: manualId: type: string pattern: ^[a-f0-9]{64}$ description: The manual to pin the underwriting file to, for good. agencyAccountId: type: string format: uuid description: The agency account (the insured). You need edit access to it. title: type: string minLength: 1 maxLength: 500 description: Defaults to “Underwriting file”. productId: type: string format: uuid status: type: string enum: - draft - received - in_review - needs_information - accepted_for_quoting - declined - withdrawn default: received description: >- The record status people set. It is a label: what a statement may do is decided from the log, never from it. submissionReference: type: string minLength: 1 maxLength: 200 businessType: type: string enum: - new - renewal requestedEffectiveDate: type: string format: date requestedExpirationDate: type: string format: date receivedAt: type: string format: date-time agencyMessage: type: string maxLength: 20000 description: type: string maxLength: 20000 statements: type: array items: $ref: '#/components/schemas/V2UnderwritingStatement' minItems: 1 maxItems: 200 description: >- First statements, recorded with the underwriting file. If the manual refuses them, nothing is created. required: - manualId - agencyAccountId additionalProperties: false V2UnderwritingWriteResult: allOf: - $ref: '#/components/schemas/V2UnderwritingFileDetail' - type: object properties: dryRun: type: boolean description: >- True for `dryRun=true`: nothing was stored. `entries`, `runs` and `view` are what the statements would produce, priced; `file` is as stored. applyId: type: string nullable: true description: This request; the entries it wrote carry it. Null on a dry run. seqs: type: array items: type: integer description: >- Seqs of the entries your statements appended (the manual’s own entries after them are in `entries`); empty on a dry run. replayed: type: boolean description: >- True when this Idempotency-Key was already applied: nothing new was appended. entries: type: array items: $ref: '#/components/schemas/V2UnderwritingLogEntry' description: >- The entries appended (on a dry run, that would be): your statements, then any the manual wrote itself after them. runs: type: array items: $ref: '#/components/schemas/V2UnderwritingRun' description: >- The ratings this request made with the manual’s bound rater bundles, each kept for good with a rater execution record. On a dry run the what-if is rated too, so the preview is priced, and nothing is kept. Ratings it did not make are in `view.ratings` as `needed`, with their `reason`. required: - dryRun - applyId - seqs - replayed - entries - runs 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. V2UnderwritingStatement: oneOf: - $ref: '#/components/schemas/V2UnderwritingStatement_open' - $ref: '#/components/schemas/V2UnderwritingStatement_answer' - $ref: '#/components/schemas/V2UnderwritingStatement_add' - $ref: '#/components/schemas/V2UnderwritingStatement_complete' - $ref: '#/components/schemas/V2UnderwritingStatement_edit' - $ref: '#/components/schemas/V2UnderwritingStatement_accept' - $ref: '#/components/schemas/V2UnderwritingStatement_request' - $ref: '#/components/schemas/V2UnderwritingStatement_decide' - $ref: '#/components/schemas/V2UnderwritingStatement_request_quote' - $ref: '#/components/schemas/V2UnderwritingStatement_quote' - $ref: '#/components/schemas/V2UnderwritingStatement_bind' - $ref: '#/components/schemas/V2UnderwritingStatement_withdraw' - $ref: '#/components/schemas/V2UnderwritingStatement_assign' discriminator: propertyName: op mapping: open: '#/components/schemas/V2UnderwritingStatement_open' answer: '#/components/schemas/V2UnderwritingStatement_answer' add: '#/components/schemas/V2UnderwritingStatement_add' complete: '#/components/schemas/V2UnderwritingStatement_complete' edit: '#/components/schemas/V2UnderwritingStatement_edit' accept: '#/components/schemas/V2UnderwritingStatement_accept' request: '#/components/schemas/V2UnderwritingStatement_request' decide: '#/components/schemas/V2UnderwritingStatement_decide' request_quote: '#/components/schemas/V2UnderwritingStatement_request_quote' quote: '#/components/schemas/V2UnderwritingStatement_quote' bind: '#/components/schemas/V2UnderwritingStatement_bind' withdraw: '#/components/schemas/V2UnderwritingStatement_withdraw' assign: '#/components/schemas/V2UnderwritingStatement_assign' 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 V2UnderwritingLogEntry: type: object properties: id: type: string description: The entry’s seq as text. seq: type: integer op: $ref: '#/components/schemas/V2UnderwritingLogEntryOp' status: type: string description: The runtime’s status for the entry, such as `active`. actor: type: object properties: userId: type: string side: type: string description: >- carrier, broker, customer, or runtime for entries the manual wrote itself. role: type: string owner: type: string nullable: true human: type: boolean required: - userId - side - role - owner - human recordedAt: type: string format: date-time description: When the entry was stamped. applyId: type: string nullable: true description: The request that wrote it; null for entries the manual wrote itself. required: - id - seq - status - actor - recordedAt - applyId V2UnderwritingRun: type: object properties: id: type: string description: 'Run ID: a digest of the rater, bundle and request.' rater: type: string description: The manual’s name for the rater it answered. package: type: string description: The hosted rater package, such as `imperium/g2`. coveragePart: type: string nullable: true description: The coverage part (`unit` of an offer) whose price asked for it. raterId: type: string description: The rater that rated, for `getRaterReleaseContract`. releaseVersion: type: integer description: >- The rater release the bundle was bound from, for `getRaterReleaseContract`. bundleId: type: string description: >- The exact bundle that rated: the manual's binding for `package` and the `bundleId` of the rater release (and its contract). executionId: type: string nullable: true description: >- The rater execution record of this rating, in the same history as `/v2/insurance/raters` ratings. Null on a dry run, which keeps nothing. ok: type: boolean description: False when the rater refused the request; `refusal` says why. request: type: object additionalProperties: nullable: true description: >- What was rated: the exact `inputs` of the rating request, as sent to the rate route for `raterId` and `releaseVersion`. inputsDigest: type: string description: >- The digest of `request`: the `inputsDigest` of the rating request it answers. outputs: type: object nullable: true additionalProperties: nullable: true description: >- What the rater answered that the manual reads, by output field of that contract's `outputSchema`. Null when refused. refusal: $ref: '#/components/schemas/V2UnderwritingRunRefusal' afterSeq: type: integer description: The log seq the rating was made after. ratedAt: type: string format: date-time description: When the rating was made. required: - id - rater - package - coveragePart - raterId - releaseVersion - bundleId - executionId - ok - request - inputsDigest - outputs - refusal - afterSeq - ratedAt description: >- One rating the runtime made for the file with a bound rater bundle, kept for good. An offer's price uses a run only while it answers the rating request the offer's current inputs make. 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 V2UnderwritingStatement_open: type: object properties: op: type: string enum: - open products: type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 20 required: - op - products additionalProperties: false description: Open the underwriting file on products the manual sells. V2UnderwritingStatement_answer: type: object properties: op: type: string enum: - answer path: type: string minLength: 1 maxLength: 500 value: nullable: true from: type: string minLength: 1 maxLength: 500 description: >- Where the answer was read from, such as a received document, when the manual names sources. target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - path additionalProperties: false description: >- Answer an input: a schema path and its value as typed JSON in the unit the schema states, such as `1200000` for Money. A text value is read strictly: digits, with `$`, `,` and `_` allowed, never a suffix, percent sign or words (`"1.2m"` is refused, not guessed). V2UnderwritingStatement_add: type: object properties: op: type: string enum: - add list: type: string minLength: 1 maxLength: 500 value: type: object additionalProperties: nullable: true target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - list - value additionalProperties: false description: Add an item to a list input, such as a location or class. V2UnderwritingStatement_complete: type: object properties: op: type: string enum: - complete list: type: string minLength: 1 maxLength: 500 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - list additionalProperties: false description: Say a list input has every item. V2UnderwritingStatement_edit: type: object properties: op: type: string enum: - edit path: type: string minLength: 1 maxLength: 500 value: nullable: true because: type: string minLength: 1 maxLength: 5000 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - path - because additionalProperties: false description: Change an accepted value, with the reason. V2UnderwritingStatement_accept: type: object properties: op: type: string enum: - accept path: type: string minLength: 1 maxLength: 500 value: nullable: true target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - path additionalProperties: false description: >- Accept a proposed value, such as one read from a document, as it is or with `value` corrected. Until it is accepted, a proposed value satisfies nothing. V2UnderwritingStatement_request: type: object properties: op: type: string enum: - request path: type: string minLength: 1 maxLength: 500 because: type: string minLength: 1 maxLength: 5000 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - path - because additionalProperties: false description: Ask for an input, with the reason; the question is asked next. V2UnderwritingStatement_decide: type: object properties: op: type: string enum: - decide choice: type: string minLength: 1 maxLength: 500 value: nullable: true because: type: string minLength: 1 maxLength: 5000 package: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]{0,99}$ description: >- The package the decision is for, such as `p1` of offer `xs.p1`: it then counts for that package's offers only. With a `target` on one offer's rule, it is that offer's package (any other is `target_wrong_scope`); a rule that gates clearance takes none. basisAdd: type: array items: type: string minLength: 1 maxLength: 500 maxItems: 50 basisRemove: type: array items: type: string minLength: 1 maxLength: 500 maxItems: 50 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - choice additionalProperties: false description: >- Decide a referral, override or waiver, or a decided input, as a blocker or question names it: `choice` is the rule (`approved` or `declined`), `.waiver` (`waived`), `[""].override` (`overridden`) or the input path. V2UnderwritingStatement_request_quote: type: object properties: op: type: string enum: - request_quote offer: type: string minLength: 1 maxLength: 500 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - offer additionalProperties: false description: Ask the carrier to quote an offer. V2UnderwritingStatement_quote: type: object properties: op: type: string enum: - quote offer: type: string minLength: 1 maxLength: 500 stated: type: object additionalProperties: nullable: true description: >- Terms stated with the quote: outcome fields by the names of the manual's `units[].outcomes`, and `offered` Coverages terms by term name. because: type: string minLength: 1 maxLength: 5000 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - offer additionalProperties: false description: >- Quote an offer. The offer must be quotable for you: its price is known from a rating of its current inputs, and nothing open holds it at quote. V2UnderwritingStatement_bind: type: object properties: op: type: string enum: - bind offer: type: string minLength: 1 maxLength: 500 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - offer additionalProperties: false description: >- Bind a quoted offer. Its quote must stand, and nothing open (a before-bind requirement, a referral, a missing authority) may hold it. V2UnderwritingStatement_withdraw: type: object properties: op: type: string enum: - withdraw offer: type: string minLength: 1 maxLength: 500 description: The offer, or the unit, to withdraw. ending: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]{0,99}$ description: >- How it ended, as one of the manual’s endings, such as `lost` or `declined`. because: type: string minLength: 1 maxLength: 5000 target: type: string minLength: 3 maxLength: 1000 pattern: '^(off|q|in|item|blk|sub|dec):' description: >- The `id` of the view node this statement is about: an offer (`off:…`), a question or selection (`q:…`; a keyed list's also takes a statement on one of its items), an answered input (`in:…`, to correct it), a list item (`item:…`), or a blocker, subjectivity or decision (`blk:…`, `sub:…`, `dec:…`). Copy it from the view or an action's `op`. The server checks, before anything is written, that the node is in the file's view for you now (else 409 `target_stale`), that it takes this statement (else 422 `target_wrong_kind`), and that the statement's path, choice, offer and package are the node's own (else 422 `target_wrong_scope`). A decision on a rule that holds one offer back counts for that offer's package only. required: - op - offer additionalProperties: false description: Withdraw an offer, or every offer of a unit, with how it ended and why. V2UnderwritingStatement_assign: type: object properties: op: type: string enum: - assign role: type: string minLength: 1 maxLength: 100 user: type: string minLength: 1 maxLength: 200 because: type: string minLength: 1 maxLength: 5000 required: - op - role - user additionalProperties: false description: >- Assign the underwriting file to a person in a role, such as its underwriter, with the reason if any. 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. V2UnderwritingLogEntryOp: oneOf: - $ref: '#/components/schemas/V2UnderwritingStatement_open' - $ref: '#/components/schemas/V2UnderwritingStatement_answer' - $ref: '#/components/schemas/V2UnderwritingStatement_add' - $ref: '#/components/schemas/V2UnderwritingStatement_complete' - $ref: '#/components/schemas/V2UnderwritingStatement_edit' - $ref: '#/components/schemas/V2UnderwritingStatement_accept' - $ref: '#/components/schemas/V2UnderwritingStatement_request' - $ref: '#/components/schemas/V2UnderwritingStatement_decide' - $ref: '#/components/schemas/V2UnderwritingStatement_request_quote' - $ref: '#/components/schemas/V2UnderwritingStatement_quote' - $ref: '#/components/schemas/V2UnderwritingStatement_bind' - $ref: '#/components/schemas/V2UnderwritingStatement_withdraw' - $ref: '#/components/schemas/V2UnderwritingStatement_assign' - $ref: '#/components/schemas/V2UnderwritingLogEntryOp_clear' - $ref: '#/components/schemas/V2UnderwritingLogEntryOp_auto_quote' discriminator: propertyName: op mapping: open: '#/components/schemas/V2UnderwritingStatement_open' answer: '#/components/schemas/V2UnderwritingStatement_answer' add: '#/components/schemas/V2UnderwritingStatement_add' complete: '#/components/schemas/V2UnderwritingStatement_complete' edit: '#/components/schemas/V2UnderwritingStatement_edit' accept: '#/components/schemas/V2UnderwritingStatement_accept' request: '#/components/schemas/V2UnderwritingStatement_request' decide: '#/components/schemas/V2UnderwritingStatement_decide' request_quote: '#/components/schemas/V2UnderwritingStatement_request_quote' quote: '#/components/schemas/V2UnderwritingStatement_quote' bind: '#/components/schemas/V2UnderwritingStatement_bind' withdraw: '#/components/schemas/V2UnderwritingStatement_withdraw' assign: '#/components/schemas/V2UnderwritingStatement_assign' clear: '#/components/schemas/V2UnderwritingLogEntryOp_clear' auto_quote: '#/components/schemas/V2UnderwritingLogEntryOp_auto_quote' description: >- What a log entry says, as a typed statement, or a clear or automatic quote the manual wrote itself. V2UnderwritingRunRefusal: type: object nullable: true properties: code: type: string enum: - invalid_inputs - business_rejection description: >- `invalid_inputs`: the request failed the rater’s input constraints. `business_rejection`: the rater declined the risk. 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 description: Each failed constraint, as `rateRaterRelease` reports it. violationsTruncated: type: boolean description: True when the rater reported more violations. required: - code - violations - violationsTruncated description: Why the rater refused; null when `ok`. V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error 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. V2UnderwritingLogEntryOp_clear: type: object properties: op: type: string enum: - clear owner: type: string required: - op - owner additionalProperties: false description: >- The carrier cleared the account: written by the manual itself, not a person. V2UnderwritingLogEntryOp_auto_quote: type: object properties: op: type: string enum: - auto_quote offer: type: string nullable: true owner: type: string nullable: true required: - op - offer - owner additionalProperties: false description: An automatic quote the manual made once the offer was priced. 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.