> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herondata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a draft policy version

> Create a new draft cloned from the current active version's policy_definition, or a blank definition if there is no active version.




## OpenAPI

````yaml https://app.herondata.io/swagger post /api/policy_version
openapi: 3.0.0
info:
  contact:
    email: support@herondata.io
    name: Support
  title: Heron Data API
  version: '2021-07-19'
servers:
  - description: Production
    url: https://app.herondata.io
security:
  - ApiKeyAuth:
      - key_XXX
externalDocs:
  description: Read Tutorial
  url: https://docs.herondata.io/
paths:
  /api/policy_version:
    post:
      tags:
        - Policy Versions
      summary: Create a draft policy version
      description: >
        Create a new draft cloned from the current active version's
        policy_definition, or a blank definition if there is no active version.
      parameters:
        - description: Account to act on. Honoured only for admins.
          in: query
          name: user_id
          required: false
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyVersionCreateSchema'
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  policy_version:
                    $ref: '#/components/schemas/PolicyVersionSchema'
                type: object
          description: OK
        '404':
          description: Not found
        '422':
          description: >-
            A draft already exists, or policy versions changed concurrently.
            When a draft exists, `errors` holds one entry with code
            `draft_exists` and the open draft's `draft_version`,
            `draft_author_email` and `draft_last_edited_at`. Nothing is changed:
            publish or delete that draft, or check with its author, before
            starting new changes. An automated sync should stop and tell someone
            rather than edit and publish a draft it didn't open.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PolicyVersionCreateSchema:
      properties:
        change_description:
          maxLength: 255
          nullable: true
          type: string
      type: object
    PolicyVersionSchema:
      properties:
        author_email:
          description: >-
            Email of whoever last acted on this version: the drafter while it is
            a draft, the publisher once published
          readOnly: true
          type: string
        backtest_status:
          allOf:
            - $ref: '#/components/schemas/PolicyVersionBacktestStatus'
          readOnly: true
        change_description:
          description: What changed in this version
          nullable: true
          readOnly: true
          type: string
        created:
          format: date-time
          readOnly: true
          type: string
        last_edited_at:
          format: date-time
          nullable: true
          readOnly: true
          type: string
        policy_definition:
          allOf:
            - $ref: '#/components/schemas/PolicyDefinition'
          readOnly: true
        published_at:
          format: date-time
          nullable: true
          readOnly: true
          type: string
        status:
          enum:
            - draft
            - active
            - archived
          readOnly: true
        version:
          description: Version number, unique per account
          readOnly: true
          type: integer
      type: object
    PolicyVersionBacktestStatus:
      properties:
        backtest_heron_id:
          nullable: true
          readOnly: true
          type: string
        deal_count:
          description: Deals the backtest covered
          nullable: true
          readOnly: true
          type: integer
        finished_at:
          format: date-time
          nullable: true
          readOnly: true
          type: string
        flipped_deal_count:
          description: Deals whose outcome changed, null unless the run completed
          nullable: true
          readOnly: true
          type: integer
        run_status:
          description: >-
            Status of this version's latest backtest, null if it has never been
            backtested
          enum:
            - pending
            - running
            - complete
            - failed
            - null
          nullable: true
          readOnly: true
        stale:
          description: >-
            The version was edited after that backtest was asked for, so re-run
            before publishing
          readOnly: true
          type: boolean
      type: object
    PolicyDefinition:
      properties:
        policy_sections:
          items:
            $ref: '#/components/schemas/PolicyVersionSection'
          type: array
      required:
        - policy_sections
      type: object
    PolicyVersionSection:
      properties:
        branches:
          description: >-
            Ordered routes through the section; the section's own checks run on
            every route
          items:
            $ref: '#/components/schemas/PolicyBranch'
          type: array
        checks:
          items:
            $ref: '#/components/schemas/Check'
          type: array
        default_branch:
          allOf:
            - $ref: '#/components/schemas/DefaultPolicyBranch'
          description: Runs when no branch's condition passes
          nullable: true
        display_order:
          nullable: true
          type: integer
        heron_id:
          nullable: true
          type: string
        name:
          type: string
        use_case:
          enum:
            - background_check
            - cashflow
      required:
        - name
      type: object
    PolicyBranch:
      properties:
        checks:
          items:
            $ref: '#/components/schemas/Check'
          type: array
        condition:
          allOf:
            - $ref: '#/components/schemas/Check'
          description: >-
            Selects this branch when it passes. Branches are tried in order and
            the first match runs; a condition that fails or is missing data does
            not match.
        heron_id:
          description: Stable across renames; omit for a new branch and one is minted
          nullable: true
          type: string
        name:
          type: string
      required:
        - condition
        - name
      type: object
    Check:
      properties:
        attribute_description:
          description: >-
            What the attribute measures. Present only for accounts on policy
            versions
          nullable: true
          type: string
        attribute_display_name:
          description: >-
            The attribute's human-readable name. Present only for accounts on
            policy versions
          nullable: true
          type: string
        attribute_label:
          nullable: true
          type: string
        attribute_unit:
          description: >-
            The unit of `attribute_label`, for formatting the attribute's value
            and the check's threshold. Null for a check without an attribute or
            an attribute with no declared unit
          enum:
            - currency
            - percentage
            - count
            - ratio
            - days
            - years
            - text
            - null
          nullable: true
        attribute_validators:
          description: >-
            The validity operators `attribute_label` offers, as in the
            catalogue's `check_options[].validators`, so a saved `is_valid` /
            `is_invalid` check can be worded. Empty for a check without an
            attribute or an attribute with no validity rule
          items:
            additionalProperties: {}
            type: object
          nullable: true
          type: array
        attribute_value_set:
          description: >-
            The vocabulary `attribute_label` draws from, so the editor can offer
            a dropdown. Keys into the /policy_value_sets response. Null for free
            text
          enum:
            - us_state
            - naics_industry
            - naics_code
            - restricted_industries
            - merchant
            - crm_decline_reason
            - iso_source_name
            - business_entity_type
            - fraud_network_finding
            - broker_velocity
            - null
          nullable: true
        boolean_check:
          allOf:
            - $ref: '#/components/schemas/BooleanCheck'
          nullable: true
        composite_check:
          allOf:
            - $ref: '#/components/schemas/CompositeCheck'
          nullable: true
        date_check:
          allOf:
            - $ref: '#/components/schemas/DateCheck'
          nullable: true
        date_delta_to_now_check:
          allOf:
            - $ref: '#/components/schemas/DateDeltaToNowCheck'
          nullable: true
        enhanced_sql_check:
          allOf:
            - $ref: '#/components/schemas/EnhancedSQLCheck'
          nullable: true
        group:
          nullable: true
          type: string
        heron_id:
          description: >-
            Stable across edits; omit for a new check and one is minted. Policy
            versions only
          nullable: true
          type: string
        identity:
          description: Stable kind:key identity used to match stored check evaluations
          nullable: true
          readOnly: true
          type: string
        name:
          nullable: true
          type: string
        numeric_check:
          allOf:
            - $ref: '#/components/schemas/NumericCheck'
          nullable: true
        parameters:
          additionalProperties:
            type: string
          nullable: true
          type: object
        sql_check:
          allOf:
            - $ref: '#/components/schemas/SQLCheck'
          nullable: true
        string_check:
          allOf:
            - $ref: '#/components/schemas/StringCheck'
          nullable: true
      type: object
    DefaultPolicyBranch:
      properties:
        checks:
          items:
            $ref: '#/components/schemas/Check'
          type: array
        condition:
          description: >-
            Not allowed: the default runs when no branch matches. Accepted only
            to report that at its path
          nullable: true
          writeOnly: true
        decline_code:
          description: Optional code sent with a failed or review_required result
          nullable: true
          type: string
        decline_description:
          description: Required when result is failed or review_required
          nullable: true
          type: string
        heron_id:
          nullable: true
          type: string
        name:
          default: Default
          type: string
        result:
          description: >-
            What happens to deals no branch matches when the default has no
            checks; required then
          enum:
            - passed
            - failed
            - review_required
            - null
          nullable: true
      type: object
    BooleanCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        value:
          type: boolean
      type: object
    CompositeCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        checks:
          items:
            $ref: '#/components/schemas/Check'
          type: array
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        max_failing:
          nullable: true
          type: integer
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        type:
          enum:
            - AND
            - OR
            - AT_MOST_FAILING
      type: object
    DateCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        type:
          enum:
            - equal
            - not_equal
            - before
            - before_or_on
            - after
            - after_or_on
        value:
          format: date
          nullable: true
          type: string
      type: object
    DateDeltaToNowCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        pass_if_value_missing:
          default: false
          type: boolean
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        type:
          enum:
            - greater_than
            - greater_than_or_equal
            - less_than
            - less_than_or_equal
        value:
          additionalProperties: {}
          nullable: true
          type: object
      type: object
    EnhancedSQLCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        check_type:
          enum:
            - equal
            - not_equal
            - greater_than
            - greater_than_or_equal
            - less_than
            - less_than_or_equal
            - before
            - before_or_on
            - after
            - after_or_on
            - is_in
            - is_not_in
        column_name:
          type: string
        comparison_value: {}
        data_type:
          enum:
            - numeric
            - date
            - string
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        query_name:
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
      required:
        - check_type
        - column_name
        - comparison_value
        - data_type
        - query_name
      type: object
    NumericCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        type:
          enum:
            - equal
            - not_equal
            - greater_than
            - greater_than_or_equal
            - less_than
            - less_than_or_equal
        value:
          description: >-
            The threshold: a number as a string, {"variable": {...}} to compare
            with another variable (with an optional "factor" that scales it), or
            {"lookup": {"table_heron_id", "column_id"}} to read it from a lookup
            table column
          oneOf:
            - type: string
            - $ref: '#/components/schemas/VariableThreshold'
      type: object
    SQLCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        column_name:
          type: string
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        query_name:
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
      required:
        - column_name
        - query_name
      type: object
    StringCheck:
      properties:
        auto_decline:
          default: false
          type: boolean
        decline_code:
          description: >-
            The CRM's identifier for this decline reason, e.g. a LendSaas reason
            id. Left unset, the CRM sync falls back to this check's
            decline_description.
          nullable: true
          type: string
        decline_description:
          nullable: true
          type: string
        email_template_name:
          nullable: true
          type: string
        ignore_metric_availability:
          default: false
          type: boolean
        is_mandatory:
          default: false
          type: boolean
        match_count:
          nullable: true
          type: integer
        on_failure:
          default: fail
          enum:
            - fail
            - review_required
        on_missing:
          default: missing_data
          description: >-
            What the check reports when it would report missing data:
            `missing_data` (the default), `fail` or `pass`. A check saved with
            an older flag (`pass_if_value_missing` on a date-delta check) reads
            as the setting it stands for. With `ignore_metric_availability` or
            `pass_if_value_missing` set, only that setting is accepted
          enum:
            - missing_data
            - fail
            - pass
        pass_description:
          nullable: true
          type: string
        transaction_scope:
          allOf:
            - $ref: '#/components/schemas/TransactionScope'
          nullable: true
        type:
          enum:
            - equal
            - not_equal
            - starts_with
            - starts_with_any_of
            - does_not_start_with_any_of
            - contains
            - does_not_start_with
            - does_not_contain
            - is_in
            - is_not_in
            - has_none_of
            - has_any_of
            - has_only
            - has_fewer_than_n_matches
            - has_more_than_n_matches
            - is_valid
            - is_invalid
        value:
          description: >-
            The value as a string, or {"lookup": {"table_heron_id"}} for is_in,
            is_not_in, has_any_of, has_none_of or has_only to read the list from
            a lookup table's rows
          oneOf:
            - type: string
            - $ref: '#/components/schemas/TableList'
      type: object
    TransactionScope:
      properties:
        file_classes:
          items:
            type: string
          nullable: true
          type: array
        min_reconciliation_status:
          enum:
            - failed
            - not_possible
            - reconciled
            - null
          nullable: true
          type: string
      type: object
    VariableThreshold:
      properties:
        factor:
          description: >-
            Scales the variable: the check passes when the value <type> factor ×
            variable. Default 1. More than 0, at most 100, up to 4 decimal
            places
          type: number
        variable:
          $ref: '#/components/schemas/ComparedVariable'
      required:
        - variable
      type: object
    TableList:
      properties:
        lookup:
          $ref: '#/components/schemas/TableListReference'
      required:
        - lookup
      type: object
    ComparedVariable:
      properties:
        attribute_label:
          type: string
        parameters:
          additionalProperties:
            type: string
          nullable: true
          type: object
      required:
        - attribute_label
      type: object
    TableListReference:
      properties:
        table_heron_id:
          description: Heron ID of the lookup table whose row keys are the list
          type: string
      required:
        - table_heron_id
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.