Ironclad Public API: Entities Guide

Overview

The Ironclad Public API provides programmatic access to manage entities (counterparties, vendors, customers, etc.) in your Ironclad workspace. This guide covers the Entities endpoints available in our public API.

Entity Properties

System-generated Entity Properties

Ironclad provides several built-in properties for entities:

API Endpoints

1. List Entities

List Entities

Endpoint: GET /entities

Required OAuth Scope: public.entities.readEntities

Filtering

The Entities API supports formula-based filtering using Ironclad's formula language.

Filter Examples

Filter by status:

And(Equals([entityStatus], "ACTIVE"))

Filter by relationship type:

And(Equals([relationshipType], "4c1fd506-3dbf-4367-b4be-044cb81dd769"))

Filter by custom property:

Equals([entity_pocEmail], '[email protected]')

Combined filters:

And(Equals([entityStatus], "ACTIVE"), Equals([relationshipType], "cddd4b1e-a219-43b8-a86e-6da0fa6aba4a"))

2. Get Entity

Retrieve an entity

Endpoint: GET /entities/{id}

Required OAuth Scope: public.entities.readEntities

3. Create Entity

Create a new Entity

Endpoint: POST /entities

Required OAuth Scope: public.entities.createEntities

4. Update Entity

Update Entity

Endpoint: PATCH /entities/:id

Required OAuth Scope: public.entities.updateEntities

5. Delete Entity

Delete an Entity

Endpoint: DELETE /entities/{id}

Required OAuth Scope: public.entities.deleteEntities

6. Get Relationship Types

Retrieve available entity relationship types.

Endpoint: GET /entities/relationship-types

Required OAuth Scope: public.entities.readRelationshipTypes

Parent-Child Entity Relationships

Ironclad supports hierarchical relationships between entities through parent-child relationships. This allows you to model organizational structures, subsidiaries, and other hierarchical business relationships.

Setting Parent-Child Relationships

You can establish parent-child relationships by including a parentId field in your entity create and update requests. The parentId should reference the Ironclad ID of the parent entity. Both readable IDs (e.g., ENTITY-1) and UUIDs are accepted and will be automatically converted as needed.

Happy/Unhappy Path Examples

Case 1: Set Entity ParentId (Success)

Endpoint: PATCH /entities/ENTITY-6

Request Body:

{
  "name": "TechStart Solutions Inc.",
  "setParent": {
    "recordId": "ENTITY-5"
  }
}

Response:

{
    "id": "e93d53e6-2580-405c-88aa-0637ccf30499",
    "ironcladId": "ENTITY-6",
    "name": "TechStart Solutions Inc.",
    "setParent": {
      "recordId": "7f3a8c63-8970-4f24-942c-999ba0f7f823"
    }
    
}

Case 2: Can't Set Entity as Its Own Parent (Error)

Endpoint: PATCH /entities/ENTITY-6

Request Body:

{
  "setParent": {
    "recordId": "ENTITY-6"
  }
}

Response:

Invalid relationship for e93d53e6-2580-405c-88aa-0637ccf30499. Cannot set a record as it's own parent

Case 3: Error if ParentId Does Not Exist

Endpoint: PATCH /entities/ENTITY-6

Request Body:

{
  "setParent": {
    "recordId": "ENTITY-?"
  }
}

Response:

{
    "code": "INVALID_PARAM",
    "message": "parent entity with id ENTITY-? not found",
    "param": "parentId"
}

Case 4: Disallow Cycles

Entity Hierarchy:

• Entity 1 is a child of Entity 2

We will attempt to set Entity 2's parent to Entity 1, introducing a cycle.

Endpoint: PATCH /entities/ENTITY-2

Request Body:

{
  "setParent": {
    "recordId": "ENTITY-1"
  }
}

Response:

{
    "code": "INVALID_PARAM",
    "message": "setting ENTITY-1 as parent would create a cycle in the parent-child relationship",
    "param": "parentId"
}

Error Handling

Ironclad APIs follow typical HTTP status code error convention.

Common Error Codes

Related Resources

• Entity References in Workflows and Records - Complete entity management
• Getting Started with Ironclad API - API fundamentals
• Authentication Guide - API authentication
• Rate Limits - API usage limits
• Entities Overview Guide
• Entities and Relationship Types Guide
• Other Entities Articles