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

# Create a Contract custom field

> Add a custom field to a contract model — used as a contract variable and synced to your CRM.

A Contract custom field captures information specific to your legal templates — for example, a clause variant, a jurisdiction, an effective date, or a guaranteed minimum. The field appears on contract records, can be referenced as a variable inside the contract text, and optionally syncs to your CRM.

This guide walks through the full lifecycle in three steps.

<Note>
  You must have the **Admin** role with **Data → Read & Write** authorized. CRM mapping additionally requires **Developers** access.
</Note>

## What you'll build

In this example, you'll add a **Jurisdiction** field on Contract Model — a Text field that drives a clause variant in your contract templates. Sales reps will pick it during quoting, and it will appear in the contract via a `{{contract.jurisdiction}}` variable.

| Field            | Type | Purpose                                               |
| ---------------- | ---- | ----------------------------------------------------- |
| **Jurisdiction** | Text | Country or state under which the contract is governed |

The field will be **mandatory**, **editable by sales reps**, and **not displayed to the customer** (it's an internal legal-ops marker — the customer sees the resolved clause text in the contract itself, not the variable name).

## Step 1: Create the field in the Data model

<Steps>
  <Step title="Open Data model">
    Go to **Settings → Data → Data model** and click the **Contract Model** object.
  </Step>

  <Step title="Click + New">
    In the top right of the field list, click **+ New** to open the field creation form.
  </Step>

  <Step title="Fill in General Information">
    * **Name**: `Jurisdiction`
    * **API Name**: Qwoty generates `jurisdiction` automatically. Edit if you need a specific identifier (for example, `governing_jurisdiction`).
    * **Data Type**: pick `Text`
  </Step>

  <Step title="Save">
    Click **Save** in the top right. The new field appears in the Contract Model object's field list with the **Custom** badge.
  </Step>
</Steps>

<Check>
  The field exists in the data model. Next, configure how it behaves on each contract model record.
</Check>

## Step 2: Configure the field on the contract model

The field exists, but it doesn't yet appear on any contract. Activate it on the contract models where it applies, and configure the three properties.

<Steps>
  <Step title="Open the contract model">
    Navigate to **Documents → Contract Model** and open the contract template you want to configure (for example, `Standard Sales Contract`).
  </Step>

  <Step title="Find the Custom Fields section">
    Scroll to the **Custom Fields** section. The `Jurisdiction` field you just created appears, with a toggle and three checkboxes.
  </Step>

  <Step title="Activate the toggle">
    Click the toggle to turn the field on. The toggle turns dark — the field is now part of every contract generated from this model.
  </Step>

  <Step title="Configure the properties">
    Check the boxes that match your needs:

    * **Mandatory** ✓ — the contract can't be generated without a jurisdiction
    * **Editable by sale** ✓ — sales reps pick the value during quoting
    * **Display for customer** — leave unchecked (jurisdiction is internal — the resolved clause text is what the customer sees)
  </Step>

  <Step title="Set a default value (optional)">
    If most of your contracts share the same jurisdiction, set a default (for example, `France`). Sales reps can override it per deal.
  </Step>

  <Step title="Save the contract model">
    Click **Save**.
  </Step>
</Steps>

### Use the field in the contract text

Now that the field is active, you can reference it as a variable inside the contract template's body:

```
This Agreement is governed by the laws of {{contract.jurisdiction}}.
Any dispute shall be settled before the courts of {{contract.jurisdiction}}.
```

When the contract is generated, the variable resolves to the value the sales rep entered. Combine it with conditional blocks (if your contract editor supports them) to swap entire clauses based on the value:

```
{{#if contract.jurisdiction == "France"}}
  ... French-specific arbitration clause ...
{{else if contract.jurisdiction == "Germany"}}
  ... German-specific arbitration clause ...
{{/if}}
```

<Tip>
  Pair custom fields with content blocks ([Documents → Content blocks](/user-guide/documents/reference/content-blocks)) for reusable contract sections that depend on the field's value.
</Tip>

## Step 3: Sync with your CRM (optional)

If your CRM tracks contract metadata (which is often the case in regulated industries), map the Jurisdiction field to a matching CRM field.

<Steps>
  <Step title="Open your CRM integration">
    Go to **Settings → Developers → Integration** and click your connected CRM.
  </Step>

  <Step title="Find the custom fields mapping section">
    Scroll to the custom fields mapping. The Contract Model field appears as `Custom: Jurisdiction`.
  </Step>

  <Step title="Pick a sync direction">
    Open the direction dropdown and choose:

    * **Bidirectional** — if your legal team also updates jurisdiction in the CRM
    * **Qwoty → CRM** — typical: the value is set during quoting and pushed to the CRM record
    * **CRM → Qwoty** — if jurisdiction is determined upstream by your CRM workflows
  </Step>

  <Step title="Select the matching CRM field">
    Pick the CRM field that holds the jurisdiction value. Compatible types: Text, Picklist, Dropdown.
  </Step>

  <Step title="Save changes">
    Click **Save changes** at the bottom of the page.
  </Step>
</Steps>

<Check>
  Your contract jurisdiction now flows between Qwoty and your CRM, and is also resolved as a variable inside generated contracts.
</Check>

## Common Contract custom fields

Beyond Jurisdiction, here are patterns that come up often:

| Field                        | Type                     | Why                                                                |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------ |
| **Effective date**           | Date                     | When the contract takes effect (often differs from signature date) |
| **Auto-renewal flag**        | Text (or future boolean) | Triggers a different renewal clause                                |
| **Notice period (months)**   | Number                   | Used in termination clauses                                        |
| **Liability cap**            | Number                   | Negotiated indemnity ceiling                                       |
| **Governing law**            | Text                     | Combined with Jurisdiction for cross-border contracts              |
| **External legal reference** | Text                     | Internal counsel ticket or case number                             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The variable {{contract.jurisdiction}} resolves to empty in the generated contract">
    Either the field is empty on the contract record, or the variable name doesn't match the API name. Open the contract and verify the field is filled. Check that the variable uses the field's API name exactly (case-sensitive).
  </Accordion>

  <Accordion title="The field is on the contract model but doesn't appear on contracts">
    Check that the toggle is **on** in the Custom Fields section of the contract model. Disabled toggles hide the field from forms.
  </Accordion>

  <Accordion title="Sales reps see the field but it doesn't save their input">
    The **Editable by sale** checkbox is unchecked. Activate it on the contract model.
  </Accordion>

  <Accordion title="My CRM doesn't show a compatible field">
    Add a custom field on the CRM side first (Text or Picklist for Jurisdiction), then refresh the integration mapping section.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Field properties" icon="sliders" href="/user-guide/data-model/reference/field-properties">
    Mandatory, Editable, Display — the three controls that shape behaviour.
  </Card>

  <Card title="Contract models" icon="file-signature" href="/user-guide/documents/reference/contract-model-and-variables">
    How variables, content blocks, and contract models combine.
  </Card>

  <Card title="Create a Quote custom field" icon="file-invoice-dollar" href="/user-guide/data-model/how-tos/create-quote-custom-field">
    Same flow, applied to quotes.
  </Card>

  <Card title="CRM mapping" icon="arrows-rotate" href="/user-guide/data-model/reference/crm-mapping">
    Sync directions and CRM field compatibility.
  </Card>
</CardGroup>