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

# Contracts API: Register and Manage Vendor Contracts

> Register SaaS, cloud, and contractor agreements so Tavryn can track renewal dates, detect waste, and autonomously negotiate savings on your behalf.

The Contracts API is the entry point for bringing vendor agreements into Tavryn. Once you register a contract, Tavryn continuously monitors it for idle seats, usage decline, and approaching renewal windows — then autonomously opens negotiation rounds to recover spend. Every field you provide sharpens the savings heuristics, so the more detail you include, the better the agent performs.

## Create a Contract

> [!NOTE]
>
> If the vendor name you supply does not already exist in Tavryn's vendor registry, a new vendor record is created automatically with a default reputation score of 4.8 and a derived procurement contact email. No additional setup is required.

```http theme={null}
POST /api/contracts
```

### Request Body

**businessId** `string` *required*

UUID of the business that owns this contract. Every contract must be scoped to a business so Tavryn can apply the correct spending policy and treasury balance.

**vendor** `string` *required*

Display name of the vendor (e.g., `"Salesforce"`, `"AWS"`, `"Acme Contractors"`). Tavryn performs a case-insensitive lookup; if the name matches an existing vendor record, the contract is linked to it automatically.

**service** `string` *required*

The specific product or service line covered by this contract (e.g., `"Sales Cloud Enterprise"`, `"EC2 Reserved Instances"`). Used in negotiation outreach and savings reports.

**category** `string` (default: software)

Contract category. Must be one of `"software"`, `"cloud"`, or `"contractors"`. Determines which negotiation playbook and heuristic benchmarks apply.

**currentPrice** `number` *required*

Annual contract value in USD. Must be a positive number. This is the baseline Tavryn negotiates against — do not include taxes or one-time fees.

**renewalDate** `string` *required*

Contract renewal date as an ISO 8601 date string (e.g., `"2025-11-01"` or `"2025-11-01T00:00:00.000Z"`). Tavryn uses this date to trigger proactive negotiation before the renewal window closes.

**seatCount** `number | null`

Total number of licensed seats on the contract. When combined with `activeSeats`, Tavryn can calculate idle-seat waste and construct a seat-reduction opening offer.

**activeSeats** `number | null`

Number of seats currently in active use. Must not exceed `seatCount`. The idle seat ratio `(seatCount - activeSeats) / seatCount` directly feeds the savings estimation model.

### Response

A successful request returns the newly created contract record along with the resolved vendor object.

**success** `boolean`

`true` when the contract is created without error.

**contract** `object`

The full contract record as persisted in the database.

**contract fields**

**id** `string`

UUID of the newly created contract.

**vendor\_id** `string`

UUID of the vendor record linked to this contract.

**service** `string`

The service or product name.

**category** `string`

One of `"software"`, `"cloud"`, or `"contractors"`.

**current\_price** `number`

Annual contract value in USD.

**renewal\_date** `string`

Renewal date as a UTC ISO 8601 timestamp.

**seat\_count** `number | null`

Total licensed seats, or `null` if not provided.

**active\_seats** `number | null`

Active seats in use, or `null` if not provided.

**status** `string`

Initial contract status. Always `"active"` on creation.

**vendors** `object`

The full vendor record linked to this contract, including `id`, `name`, `category`, `reputation_score`, and `contact`.

### Example Request

```bash theme={null}
curl -X POST https://your-tavryn-instance.com/api/contracts \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "e3b0c442-98fc-1c14-b39f-92d1282048c0",
    "vendor": "Notion",
    "service": "Team Plan",
    "category": "software",
    "currentPrice": 12000,
    "renewalDate": "2025-11-01",
    "seatCount": 50,
    "activeSeats": 31
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "contract": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "vendor_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "service": "Team Plan",
    "category": "software",
    "current_price": 12000,
    "renewal_date": "2025-11-01T00:00:00.000Z",
    "seat_count": 50,
    "active_seats": 31,
    "status": "active",
    "vendors": {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "name": "Notion",
      "category": "software",
      "reputation_score": 4.8,
      "contact": "procurement@notion.com"
    }
  }
}
```

### Status Codes

| Code | Meaning |
| - | - |
| `200` | Contract created successfully. |
| `400` | Request body failed validation. The response includes a `details` field with per-field error messages. |
| `500` | An internal error occurred while writing to the database. |


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