Ironclad Public API: Entity References Guide

Overview

Entity references allow you to link entities (counterparties, vendors, customers, etc.) to workflows and records in Ironclad. This guide covers how to work with entity references across different API endpoints and the various approaches for handling entity data in API responses.

Entity Reference Approaches

Ironclad provides two approaches for handling entity references in API responses. These references are returned by workflow and record endpoints, but not by schema endpoints (which use a different format).

1. Returning Entity Reference (Minimal Information)

Description: The API returns only minimal reference information:

recordId - The unique identifier for the entity
subTypeId - The relationship type ID that defines the entity's role in the workflow or record (e.g., customer, vendor, counterparty, etc.). This ID corresponds to a relationship type that determines how the entity is used in the context. You can retrieve available relationship types using the Get Relationship Types endpoint.

Example Response:

{
  "entity_reference": [
    {
      "type": "reference",
      "value": {
        "recordId": "06cb35af-bcc5-4aca-a7e8-cc4f4a1035d2",
        "subTypeId": "b9369328-af3a-4120-933b-c3476cc16973"
      }
    }
  ]
}

2. Hydrating Entity in API Response (Detailed Information)

Description: The API includes hydrated entity details:

readableId
attributes (e.g., pocName, pocEmail, address)

Example Response:

{
  "entity_reference": [
    {
      "type": "reference",
      "value": {
        "recordId": "8e2e25d1-37fa-4d77-804c-a865adebfe83",
        "readableId": "ENTITY-1",
        "attributes": {
          "entity_pocName": "Jane Doe",
          "entity_pocEmail": "[email protected]",
          "entity_address": {
            "type": "address",
            "value": {
              "lines": ["123 Business St"],
              "locality": "San Francisco",
              "region": "CA",
              "postcode": "94105",
              "country": "US"
            }
          },
          "entity_category": "external",
          "entity_businessType": "company"
        }
      }
    }
  ]
}

API Endpoints

1. Reading Entity Information from Workflows

List all workflows

Endpoint: GET /workflows

Required OAuth Scope: public.workflows.readWorkflows

Query Parameters:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| hydrateEntities | boolean | No | false | Include full entity details in the response |
| filter | string | No | none | Filter response by a formula |

Filtering by Entity:

You can filter records by entity using the filter parameter with formulas. For example, to find all records associated with a specific entity:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/records?filter=Equals([entity], "c207c133-1f21-41b0-b6df-6ae01629cb3e")' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

For more information about available formulas and filtering options, see the Formulas Help Center.

Example Request:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflows?hydrateEntities=true' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

Response Code: 200 OK

Example Response:

{
  "page": 0,
  "pageSize": 20,
  "count": 1,
  "list": [
    {
      "id": "681b91ce943b808e0503eeea",
      "title": "Contract Agreement with Example Corporation",
      "template": "68126d0c48031c7f40ad5e5a",
      "step": "Sign",
      "attributes": {
        "readableId": "IC-5",
        "counterpartyName": "Example Corporation",
        "entity_reference": [
          {
            "recordId": "8e2e25d1-37fa-4d77-804c-a865adebfe83",
            "readableId": "ENTITY-1",
            "namedTypeIds": [
              "b9369328-af3a-4120-933b-c3476cc16973"
            ],
            "attributes": {
              "entity_address": {
                "type": "address",
                "value": {
                  "lines": ["123 Business St"],
                  "locality": "San Francisco",
                  "region": "CA",
                  "postcode": "94105",
                  "country": "US"
                }
              },
              "entity_pocName": "Jane Doe",
              "entity_category": "external",
              "entity_pocEmail": "[email protected]",
              "entity_businessType": "company"
            }
          }
        ]
      }
    }
  ]
}

Get specific workflow

Endpoint: GET /workflows/:id

Required OAuth Scope: public.workflows.readWorkflows

2. Creating Workflows with Entity References

Create workflow synchronously

Endpoint: POST /workflows

Required OAuth Scope: public.workflows.createWorkflows

Entity Mapping Behavior:

When you provide an entity reference during workflow creation, the system will automatically populate any workflow fields that are mapped to entity properties. If you provide a value for a field that is mapped to an entity property, your provided value will take precedence over the entity's value.

Note: The exact mapping behavior depends on your workflow template configuration. Some fields may be automatically populated from entity data, while others may require manual input.

Request Body:

{
  "template": "your-template-id",
  "attributes": {
    "entity_reference": "ENTITY-1",
    "counterpartyName": "Example Company",
    "other_field": "other_value"
  }
}

Example Request:

curl --request POST \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflows' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "template": "your-template-id",
       "attributes": {
         "entity_reference": "ENTITY-1",
         "counterpartyName": "Example Corporation"
       }
     }'

Response Code: 201 Created

Create workflow asynchronously

Endpoint: POST /workflows/async

Required OAuth Scope: public.workflows.createWorkflows

Note: The request body format is identical to the synchronous workflow creation endpoint.

3. Updating Workflows with Entity References

Update workflow metadata

Endpoint: PATCH /workflows/:id/attributes

Required OAuth Scope: public.workflows.updateWorkflows

Note: The workflow must be at the Review step to update attributes.

Setting an Entity Reference:

{
  "updates": [
    {
      "action": "set",
      "path": "entity_reference",
      "value": "ENTITY-1"
    }
  ]
}

Removing an Entity Reference:

{
  "updates": [
    {
      "action": "remove",
      "path": "entity_reference"
    }
  ]
}

Response Code: 200 OK

Example Response:

{
  "id": "workflow-id",
  "title": "Updated Workflow Title",
  "step": "Review",
  "attributes": {
    "counterpartyName": "Example Corporation"
  }
}

Example Request:

curl --request PATCH \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflows/:id/attributes' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "updates": [
         {
           "action": "set",
           "path": "entity_reference",
           "value": "ENTITY-1"
         }
       ]
     }'

Response Code: 200 OK

Example Response:
Note: This is an excerpt from the full response.

{
    "id": "689cd5acfacbcd36740bea21",
    "title": "Contract with Company Solutions Inc.",
    "template": "68126d0c48031c7f40ad5e5a",
    "step": "Review",
    "attributes": {
        "entity_reference": [
            {
                "recordId": "6d5637d5-4534-4b79-920f-c0d51ff93222",
                "subTypeId": "ba53e018-f0ce-4892-868b-0744d7ea96cd"
            }
        ],
        ...
    }
    ...
}

4. Reading Workflow Schemas with Entity Information

List all workflow schemas

Endpoint: GET /workflow-schemas

Required OAuth Scope: public.workflowSchemas.readWorkflowSchemas

Example Request:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflow-schemas' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

Get specific workflow schema

Endpoint: GET /workflow-schemas/:templateId

Required OAuth Scope: public.workflowSchemas.readWorkflowSchemas

Example Request:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflow-schemas/your-template-id' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

Response Code: 200 OK

Example Response:

{
  "id": "your-template-id",
  "name": "Standard Agreement Template",
  "schema": {
    "entity_reference": {
      "type": "referenceType",
      "displayName": "Counterparty",
      "propertyKey": "entity_reference"
    },
    "counterpartyName": {
      "type": "string",
      "displayName": "Counterparty Name",
      "propertyKey": "counterpartyName"
    },
    "agreementDate": {
      "type": "date",
      "displayName": "Agreement Date",
      "propertyKey": "agreementDate"
    }
  }
}

5. Reading Entity Information from Records

List all records

Endpoint: GET /records

Required OAuth Scope: public.records.readRecords

Filtering by Entity:

You can filter workflows by entity using the filter parameter with formulas. For example, to find all workflows associated with a specific entity:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/workflows?filter=Equals([entity], "c207c133-1f21-41b0-b6df-6ae01629cb3e")' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

For more information about available formulas and filtering options, see the Formulas Help Center.

Example Request:

curl --request GET \
     --url 'https://na1.ironcladapp.com/public/api/v1/records?hydrateEntities=true' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'accept: application/json'

Response Code: 200 OK

Example Response:

{
  "page": 0,
  "pageSize": 20,
  "count": 1,
  "list": [
    {
      "id": "record-id",
      "name": "Sample Contract Record",
      "type": "contract",
      "addProperties": {
        "entity_reference": [
          {
            "type": "reference",
            "value": {
              "recordId": "8e2e25d1-37fa-4d77-804c-a865adebfe83",
              "readableId": "ENTITY-1",
              "attributes": {
                "entity_pocName": "Jane Doe",
                "entity_pocEmail": "[email protected]",
                "entity_category": "external",
                "entity_businessType": "company"
              }
            }
          }
        ],
        "counterpartyName": {
          "type": "string",
          "value": "Example Corporation"
        }
      }
    }
  ]
}

Get specific record

Endpoint: GET /records/:id

Required OAuth Scope: public.records.readRecords

6. Creating Records with Entity References

Create record

Endpoint: POST /records

Required OAuth Scope: public.records.createRecords

Request Body:

{
  "type": "contract",
  "name": "My API Generated Record",
  "addProperties": {
    "entity_reference": {
      "type": "reference",
      "value": "ENTITY-1"
    },
    "counterpartyName": {
      "type": "string",
      "value": "Example Company"
    },
    "agreementDate": {
      "type": "date",
      "value": "2024-01-15"
    }
  }
}

Example Request:

curl --request POST \
     --url 'https://na1.ironcladapp.com/public/api/v1/records' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "type": "contract",
       "name": "Sample Contract Record",
       "addProperties": {
         "entity_reference": {
           "type": "reference",
           "value": "ENTITY-1"
         },
         "counterpartyName": {
           "type": "string",
           "value": "Example Corporation"
         },
         "agreementDate": {
           "type": "date",
           "value": "2024-01-15"
         }
       }
     }'

Response Code: 201 Created

7. Updating Records with Entity References

Update record

Endpoint: PATCH /records/:id

Required OAuth Scope: public.records.updateRecords

Example Request:

curl --request PATCH \
     --url 'https://na1.ironcladapp.com/public/api/v1/records/:id' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "addProperties": {
         "entity_reference": {
           "type": "reference",
           "value": "ENTITY-2"
         }
       }
     }'

Response Code: 200 OK

Entity Reference Schema

In workflow schemas, entity reference fields appear as:

{
  "entity_reference": {
    "type": "referenceType",
    "displayName": "Counterparty",
    "propertyKey": "entity_reference"
  }
}

Error Handling

When working with entity references, you may encounter the following specific errors:

Entity-Specific Error Codes

Code	Description
`INVALID_ENTITY_REFERENCE`	The specified entity does not exist or is not accessible
`FORBIDDEN`	You do not have permission to access the specified entity
`INVALID_PARAM`	The entity reference format is invalid or the entity is archived

Error Response Format

{
  "code": "INVALID_ENTITY_REFERENCE",
  "message": "Entity with ID ENTITY-1 not found or not accessible",
  "param": "entity_reference"
}

Entity Reference Validation

When working with entity references, the following validation rules apply:

Entity Existence: The referenced entity must exist in your Ironclad workspace
Permission Requirements:
- Read operations: The requesting user must have read access to the referenced entity
- Write operations: The requesting user must have write access to both the workflow/record and the referenced entity
Reference Format: Entity references can be provided as:
- Entity Ironclad ID (e.g., ENTITY-1)
- Entity record ID (UUID format)

Related Resources

Entities CRUD API Guide - 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