Import a same-workspace record document

Creates records with their exported IDs or updates matching IDs in one transaction. Embedded descendants are created after their parents, saved-price snapshots are preserved, and readable outbound links are merged. The document must match the current workspace's type IDs and schema revision. Maximum 100 records and 500 links and unlinks per request. Rows are sparse: a row needs only ref and the fields to set; an omitted field stays empty on create and unchanged on update, and state missing clears it. Create rejects existing IDs; update checks the version of a row when given, so one request can patch different values per record, and unlinks (update only) removes links. For more records, send consecutive requests of up to 100 rows with their own idempotency keys. Retries of the identical request use its idempotency key.

Requires: create access to the list in create mode, edit access in update mode.

POST
/v1/records/import

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/import" \  -H "Content-Type: application/json" \  -d '{    "document": {      "format": "customermates-records",      "version": 1,      "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",      "schemaRevision": 9007199254740991,      "records": [        {          "ref": {            "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",            "recordId": "0470cfd4-dcf3-4d8c-ac28-58c6deeff25f"          }        }      ]    },    "mode": "create",    "idempotencyKey": "stringst"  }'
{
  "created": 9007199254740991,
  "updated": 9007199254740991,
  "linked": 9007199254740991,
  "unlinked": 9007199254740991,
  "schemaRevision": 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