Ironclad Public API: Record Amendments Guide

Overview

Ironclad’s Records Public API lets you create, update, and manage amendment records that stay in sync with their parent contracts. An amendment is still a record. When creating amendments to an existing contract in Ironclad, it may be useful to be able to “roll up” the new terms of the amendment to the parent contract. Doing so would allow users to view the latest effective terms of an agreement that has been amended, reducing the risk that they make a decision based on outdated information.

API Endpoints

1. Create Amendment

Create Record

Endpoint: POST /records/

Required OAuth Scope: public.records.createRecords

Description: Creates an amendment record, optionally configuring property rollups to the parent contract. Payload fields:

• parent: Moves or links the amendment to a parent with cycle detection.
  • recordId: Parent record ID. May be an UUID or a readableId (IC-1234)
  • parentLinkType : Must be “amendment”
• propertiesToAmend: Adds keys to the rollup map. Each key to roll up must be included.

Example: Create amendment with rollup

{
  "type": "nda",
  "name": "Amendment #1 - Updated Terms",
  "properties": {
    "counterpartyName": { "type": "string", "value": "Acme Corporation Ltd" },
    "contractValue": {
      "type": "monetary_amount",
      "value": { "amount": 150000.0, "currency": "USD" }
    }
  },
  "parent": {
    "recordId": "IC-1",
    "parentLinkType": "amendment"
  },
  "propertiesToAmend": {
    "counterpartyName": { "amendmentType": "replace" },
    "contractValue": { "amendmentType": "replace" }
  }
}

2. Replace Amendment

Replace a Record

Endpoint: PUT /records/{id}

Required OAuth Scope: public.records.updateRecords

Description: Replaces the entire amendment record and refreshes the rollup definition. Payload fields:

• parent: Moves or links the amendment to a parent with cycle detection.
  • recordId: Parent record ID. May be an UUID or a readableId (IC-1234)
  • parentLinkType : Must be “amendment”
• propertiesToAmend: Adds keys to the rollup map. Notes:
• Supply complete state for the amendment.
• Including propertiesToAmend refreshes the parent rollup map.

Example: Replace amendment with rollup

{
  "type": "nda",
  "name": "Amendment #1 - Revised Terms",
  "properties": {
    "counterpartyName": {
      "type": "string",
      "value": "Acme Corporation International"
    },
    "contractValue": {
      "type": "monetary_amount",
      "value": { "amount": 200000.0, "currency": "USD" }
    }
  },
  "parent": {
    "recordId": "IC-123",
    "parentLinkType": "amendment"
  },
  "propertiesToAmend": {
    "counterpartyName": { "amendmentType": "replace" },
    "contractValue": { "amendmentType": "replace" }
  }
}

3. Update Amendment

Update Record Metadata

Endpoint: PATCH /records/{id}

Required OAuth Scope: public.records.updateRecords

Description: Performs targeted updates, rollup adjustments, and parent relinking in a single call. Payload fields:

• setParent: Moves or links the amendment to a parent with cycle detection.
  • recordId: Parent record ID. May be an UUID or a readableId (IC-1234)
  • parentLinkType : Must be “amendment”
• addPropertiesToAmend: Adds keys to the rollup map.
• removePropertiesToAmend: Removes keys from the rollup map.
• addProperties, removeProperties: Standard record mutations processed alongside rollup operations.
• Rollup adjustments remain available to maintain existing amendments when the feature flag is disabled.

Example: Move amendment and adjust rollup

{
  "setParent": {
    "recordId": "IC-456",
    "parentLinkType": "amendment"
  },
  "addPropertiesToAmend": {
    "contractValue": { "amendmentType": "replace" }
  },
  "addProperties": {
    "contractValue": {
      "type": "monetary_amount",
      "value": { "amount": 175000.0, "currency": "USD" }
    }
  }
}

3. Retrieve Amended Parent Record

Retrieve a Record

Endpoint: GET /records/{id}

Required OAuth Scope: public.records.readRecords

Description: Returns amendment or parent record details. When rollup data exists and the feature flag is enabled:

• Amended fields include originalValue.
• Parents expose an amendments array containing child IDs or readable IDs.

Example: Parent record with rolled-up values

{
  "id": "IC-123",
  "properties": {
    "counterpartyName": {
      "type": "string",
      "originalValue": "Acme Corporation",
      "value": "Acme Corporation Ltd"
    },
    "contractValue": {
      "type": "monetary_amount",
      "originalValue": { "amount": 100000.0, "currency": "USD" },
      "value": { "amount": 150000.0, "currency": "USD" }
    }
  },
  "amendments": ["IC-124"]
}

4. Delete Amendment

Delete a Record

Endpoint: DELETE /records/{id}

Required OAuth Scope: public.records.deleteRecords

Description: Deletes the amendment record. Deleting an amendment contract will remove the contract relationship link, and and data that was updating the parent will return to the original value. Response: 204 No Content on success.

Validation Rules

• Metadata: Property IDs must exist and match type definitions; invalid keys return INVALID_PARAM.
• Rollup inputs: Keys in propertiesToAmend / addPropertiesToAmend must appear in the payload properties / addProperties (depending on endpoint).
• Parent checks: Parent must exist, be visible, be archived, and must not itself amend a record.
• Authorization: Edit permission required on both amendment and parent when applying rollup.
• Relationships: No self-parenting, no amending amendments, and no cycles.

Error Handling

Ironclad APIs follow typical HTTP status code error convention.

Common Error Codes

Related Resources

• Contract Families Overview
• Getting Started with Ironclad API - API fundamentals
• Authentication Guide - API authentication
• Rate Limits - API usage limits