Create or update records (upsert)

Records are created if they don't exist, or updated if matched by systemRef.

Partial Success Behavior:

• Each record is processed independently
• Successful records are persisted even if others fail
• Check summary.failed and individual records[].status for failures
• Failed records include error details in records[].error

Limits: Maximum 100 records per request.

Business Applications:

• Bulk record import
• Entity synchronization

Real Example:

curl --location 'https://{{host}}/api/v1/records' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

Update existing records only

Only updates existing records. Returns error if record not found by systemRef. The systemRef field is required for all records in PUT requests.

Partial Success Behavior:

• Each record is processed independently
• Successful records are persisted even if others fail
• Records not found will have status FAILED with error code RECORD_NOT_FOUND
• Check summary.failed and individual records[].status for failures

Limits: Maximum 100 records per request.

Business Applications:

• Strict update workflows
• Guaranteed existence updates

Real Example:

curl --location 'https://{{host}}/api/v1/records' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": example value
}'

Delete (inactivate) records

Soft-deletes records by marking them as inactive. Returns error if record not found. The systemRef field is required for all records in DELETE requests.

Partial Success Behavior:

• Each record is processed independently
• Successful deletions are persisted even if others fail
• Records not found will have status FAILED with error code RECORD_NOT_FOUND
• Check summary.failed and individual records[].status for failures

Limits: Maximum 100 records per request.

Business Applications:

• Bulk inactivation
• Record cleanup

List available record types

Returns record types that can be managed via this API, with schema URLs.

Business Applications:

• Discover record types

Get field schema for a record type

Returns field definitions including types, validation, and foreign key relationships.

Business Applications:

• Dynamic form generation
• Field validation
• Integration mapping

List all custom record types

Returns all custom record type definitions for the tenant. Use includeInactive=true to include deactivated record types.

Business Applications:

• Discover custom record types
• Integration configuration

Create a new custom record type

Creates a new custom record type with the specified field schema. The record type name must be unique and follow naming conventions.

Business Applications:

• Define custom data structures
• Extend system capabilities

Real Example:

curl --location 'https://{{host}}/api/v1/records/custom' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Example Name",
  "displayName": "Example Name",
  "description": "example value"
}'

Get a custom record type by name

Returns the full definition of a custom record type including its field schema.

Business Applications:

• View record type schema
• Integration setup

Update a custom record type

Updates an existing custom record type. Only provided fields will be updated. Note: Changing fields may affect existing data.

Business Applications:

• Modify record type definitions
• Add new fields

Real Example:

curl --location 'https://{{host}}/api/v1/records/custom/{name}' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "displayName": "Example Name",
  "description": "example value",
  "fields": example value
}'