> ## 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. # Record an input on an underwriting file > Record something a person or system said or did, such as a value from the application, an accepted document or a referral decision, and apply it with the file's pinned guidelines. The server sets the input's `seq`, time and actor; `role` is the authority you claim and is recorded, not verified. An input the guidelines cannot apply, such as a field they do not define, is refused with 400 and the problems in `details` on `data`, and nothing is recorded. Pass `expectedSeq` (the `seq` you last read) to get 409 instead of recording on a file that moved on. A wrong value is fixed with a later `value.corrected` input; inputs are never edited or deleted. Not idempotent: after an uncertain response, list the inputs before retrying, or retry with the same `expectedSeq`, which returns 409 if the first attempt was recorded. Requires `scope` and edit access to the submission. ## OpenAPI ````yaml /openapi.json post /insurance/uw-submissions/{submissionId}/file/inputs 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/uw-submissions/{submissionId}/file/inputs: post: tags: - Underwriting summary: Record an input on an underwriting file description: >- Record something a person or system said or did, such as a value from the application, an accepted document or a referral decision, and apply it with the file's pinned guidelines. The server sets the input's `seq`, time and actor; `role` is the authority you claim and is recorded, not verified. An input the guidelines cannot apply, such as a field they do not define, is refused with 400 and the problems in `details` on `data`, and nothing is recorded. Pass `expectedSeq` (the `seq` you last read) to get 409 instead of recording on a file that moved on. A wrong value is fixed with a later `value.corrected` input; inputs are never edited or deleted. Not idempotent: after an uncertain response, list the inputs before retrying, or retry with the same `expectedSeq`, which returns 409 if the first attempt was recorded. Requires `scope` and edit access to the submission. operationId: createUwSubmissionFileInput parameters: - schema: type: string format: uuid required: true name: submissionId in: path - schema: type: string pattern: ^mc:[A-Za-z0-9][A-Za-z0-9-]{0,127}$ description: Authorization scope UUID or stable slug prefixed with mc:. required: true description: Authorization scope UUID or stable slug prefixed with mc:. name: scope in: query requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2UwFileInputCreate' responses: '201': description: >- The recorded input, the file after it, and what the guidelines newly ask for because of it. content: application/json: schema: type: object properties: input: $ref: '#/components/schemas/V2UwFileInput' file: $ref: '#/components/schemas/V2UwFile' effects: type: array items: $ref: '#/components/schemas/V2UwFileEffect' description: Items this input newly opened, such as a referral to send. required: - input - file - effects additionalProperties: false '400': description: >- Invalid request, or guidelines or an input the guidelines cannot use; `details` lists each problem. Restart a list after `invalid_cursor`. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: Credential or scope access denied, or the change is not permitted. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: Scope, product, guidelines, submission, file or input not found. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '409': description: >- The resource changed or already exists: read it again before retrying. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '413': description: Request body is too large. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: Content-Type must be application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: Temporarily unavailable. Honor Retry-After in seconds. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2UwFileInputCreate: type: object properties: type: type: string enum: - artifact.attached - evidence.accepted - evidence.rejected - value.proposed - value.accepted - value.entered - value.corrected - value.selected - value.rejected - collection.completed - collection.reopened - referral.decided - review.completed - subjectivity.satisfied - stage.requested - stage.done - stage.declined - note description: >- What happened. value.* records a fact (entered, proposed, accepted, corrected, selected or rejected); evidence.* accepts or rejects a document; artifact.attached attaches one; collection.* completes or reopens a list; referral.decided, review.completed, subjectivity.satisfied and stage.* record decisions; note adds a remark. data: type: object additionalProperties: nullable: true default: {} description: >- The input itself, such as `{ "field": "insured_name", "value": "Example Bar LLC" }` for value.entered. role: type: string minLength: 1 maxLength: 200 description: >- The authority you act with, such as Underwriter or Manager, which referrals and reviews check. It is recorded with you as the actor and is not verified. expectedSeq: type: integer minimum: 0 description: >- The `seq` you last read. If the file has moved on, the input is refused with 409 and nothing is recorded. required: - type additionalProperties: false V2UwFileInput: type: object properties: id: type: string description: Stable input ID. seq: type: integer description: Position in the file, from 1. at: type: string format: date-time description: When it was recorded. type: type: string data: type: object additionalProperties: nullable: true actor: type: object properties: userId: type: string nullable: true name: type: string role: type: string nullable: true description: The authority the actor claimed, if any. required: - userId - name - role required: - id - seq - at - type - data - actor V2UwFile: type: object properties: submissionId: type: string guidelines: allOf: - $ref: '#/components/schemas/V2UwGuidelinesVersion' - description: The guidelines version the file is pinned to. seq: type: integer description: The number of the last input, or 0 before the first. updatedAt: type: string format: date-time view: $ref: '#/components/schemas/V2UwFileView' required: - submissionId - guidelines - seq - updatedAt - view V2UwFileEffect: type: object properties: id: type: string description: 'Stable ID: the same open item keeps the same ID across inputs.' kind: type: string enum: - request - refer - review - decline - chase description: >- request: ask for a fact before a stage. refer: get approval from a role. review: a role must do a piece of work. decline: decline reasons apply. chase: a subjectivity is overdue. stage: type: string nullable: true need: type: string description: 'request: the fact to ask for.' role: type: string description: 'refer and review: the role who must act.' obligation: type: string label: type: string reasons: type: array items: type: string description: 'decline: the reasons that apply.' subjectivity: type: string due: type: string nullable: true required: - id - kind 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. accessUrl: type: string nullable: true format: uri description: >- Where to add the product to your account, for product_access_required. required: - code V2UwGuidelinesVersion: type: object nullable: true properties: id: type: string description: The guidelines `id`. versionId: type: string description: The exact version. Read it with `downloadFile` and `versionId`. version: type: integer description: Version number, starting at 1. required: - id - versionId - version description: >- The guidelines version the submission's file is pinned to, or null before the file is opened. V2UwFileView: type: object properties: title: type: string through: type: integer description: The last input reflected, as its `seq`. asOf: type: string nullable: true description: The time of that input. headline: type: array items: type: object properties: name: type: string label: type: string value: $ref: '#/components/schemas/V2UwFileValue' required: - name - label - value description: The figures the guidelines lead with, such as premium. stages: type: array items: type: object properties: stage: type: string description: A milestone the guidelines name, such as rate, quote or bind. status: type: string enum: - declined - ineligible - done - blocked - waiting - ready open: type: array items: type: object properties: label: type: string kind: type: string description: gate, referral, review, require, rating or select. location: type: string nullable: true description: The location it applies to, or null for the account. state: type: string enum: - met - not met - open value: $ref: '#/components/schemas/V2UwFileValue' required: - label - kind - location - state - value description: What still stands in the way of this stage. required: - stage - status - open description: Each stage in order, with what is still open. next: type: string nullable: true description: The next stage to work on, or null. missing: type: array items: type: string description: Facts still needed for the next stage. declines: type: array items: type: object properties: id: type: string reason: type: string location: type: string nullable: true state: type: string enum: - applies - may apply required: - id - reason - location - state obligations: type: array items: type: object properties: id: type: string kind: type: string enum: - referral - review label: type: string role: type: string stage: type: string nullable: true location: type: string nullable: true applies: type: string enum: - 'yes' - open decision: type: string nullable: true by: type: string nullable: true satisfied: type: boolean note: type: string nullable: true required: - id - kind - label - role - stage - location - applies - decision - by - satisfied - note description: Referrals and reviews the guidelines call for, and how each stands. subjectivities: type: array items: type: object properties: id: type: string label: type: string state: type: string due: type: string nullable: true required: - id - label - state - due open: type: array items: $ref: '#/components/schemas/V2UwFileEffect' description: Everything the file is waiting on someone to do. sections: type: array items: type: object properties: id: type: string nullable: true title: type: string level: type: integer line: type: integer blocks: type: array items: type: object additionalProperties: nullable: true description: >- Headings, text, lists, rules and tables, each annotated for this submission. required: - id - title - level - line - blocks description: >- The guidelines document, section by section, annotated with this submission. problems: type: array items: type: string description: Problems with the inputs, if any. required: - title - through - asOf - headline - stages - next - missing - declines - obligations - subjectivities - open - sections - problems description: The whole file as an underwriter reads it now. V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error V2UwFileValue: anyOf: - type: object properties: known: type: boolean enum: - true text: type: string description: The value as written in the file, such as `USD 65,934`. provisional: type: boolean enum: - true description: Present when the value rests on a fact no one has confirmed yet. required: - known - text - type: object properties: known: type: boolean enum: - false need: type: array items: type: string description: The facts this value is waiting on. notes: type: array items: type: string description: Why it cannot be worked out yet, when not a fact. required: - known - need - notes 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.