Create, update, delete or link records

Configurable CRM record contract. Record references contain both typeId and recordId. Workspace scope comes from authentication. Decimal values are strings. Writes require their documented revision and idempotency preconditions; pending results refer to a durable operation.

Requires: create access to the list for create; edit access for update, updateMany, link and unlink (on the source record's list); delete access for delete and deleteMany. Every referenced record must be readable.

POST
/v1/records/mutate

Authorization

apiKeyAuth
x-api-key<token>

API key authentication. Create an API key in your user profile and include it in the x-api-key header.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://customermates.com/api/v1/records/mutate" \  -H "Content-Type: application/json" \  -d '{    "expectedRevision": 42,    "idempotencyKey": "create-acme-renewal-2026",    "mutation": {      "action": "create",      "typeId": "0b6f3c1e-8a52-4c39-9d7e-2f4a6b8c1d01",      "fields": [        {          "fieldId": "9a4c2e61-3b5d-4f7a-8c9e-1d2b3a4c5e21",          "value": {            "kind": "text",            "value": "Acme renewal"          }        },        {          "fieldId": "c7e1a3b5-2d4f-4a6c-9e8b-0f1a2b3c4d31",          "value": {            "kind": "decimal",            "value": "12000.00",            "currency": "EUR"          }        }      ]    }  }'
{
  "status": "completed",
  "refs": [
    {
      "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
      "recordId": "0470cfd4-dcf3-4d8c-ac28-58c6deeff25f"
    }
  ],
  "references": [
    {
      "reference": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "schemaRevision": -9007199254740991,
  "trashBatchId": "f9ad794f-414e-4d2a-bff7-4eedbaa196bb",
  "deletionCleaned": [
    {
      "consumer": {
        "kind": "type",
        "id": "string",
        "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
        "label": "string"
      },
      "target": {
        "kind": "type",
        "id": "string",
        "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
        "label": "string"
      },
      "replacement": {
        "kind": "type",
        "id": "string",
        "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
        "label": "string"
      },
      "effect": "countsRecords"
    }
  ],
  "restore": {
    "restoredItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "blocked": [
      {
        "itemId": "f11b669d-7201-4c21-88af-d85092f0c005",
        "reason": "listDeleted",
        "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
        "parent": {
          "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
          "recordId": "0470cfd4-dcf3-4d8c-ac28-58c6deeff25f"
        }
      }
    ],
    "restoredRecords": -9007199254740991,
    "droppedLinks": -9007199254740991
  },
  "warnings": [
    {
      "code": "countryMissing",
      "fieldId": "string",
      "recordIds": [
        "string"
      ],
      "part": "street",
      "expected": [
        "string"
      ],
      "message": "string"
    }
  ]
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
Empty