Create Records

​

Path

​

Request

​

Path Parameters

• tableId (string): The unique identifier of the table.

​

Request Body

• records (required)
  • Description: Array of records to create
  • Type: Array
  • Example:
    Copy

    [
      {
        fields: {
          "Name": "John Doe",
          "Age": 30,
          "Email": "john@example.com"
        }
      },
      {
        fields: {
          "Name": "Jane Smith",
          "Age": 28,
          "Email": "jane@example.com"
        }
      }
    ]
    

  • Note: Each record is an item containing a fields object. The fields object contains field names and their corresponding values. Each field type has a different value structure, see Record Field Value Types for details.
• fieldKeyType (optional)
  • Description: Specifies the type of field key
  • Type: String
  • Possible values:
    • “name”: Use field name as key
    • “id”: Use field ID as key
    • “dbFieldName”: Use field dbFieldName as key
  • Example: "name" or "id" or "dbFieldName"
  • Note: If not specified, field name is used as key by default.
  • Usage:
    • When set to “name”:
      Copy

      {
        fields: {
          "Name": "John Doe",
          "Age": 30
        }
      }
      

    • When set to “id”:
      Copy

      {
        fields: {
          "fldABCDEFGHIJKLMN": "John Doe",
          "fldOPQRSTUVWXYZ12": 30
        }
      }
      

• typecast (optional)
  • Description: Whether to automatically convert field value types. By default, strict validation is enforced, requiring input values to match the current field’s data type. If enabled, the system will attempt automatic conversion.
  • Type: Boolean
  • Possible values: true or false
  • Example: true
  • Note: If set to true, the system will attempt to convert input values to the correct field value type.
  • Usage examples:
    • Link field: Can directly use primary key text for linking
      Copy

      {
        "User table": "John Smith"
      }
      

    • Date field: Can use non-standard format date strings
      Copy

      {
        "Date": "2023-05-15"
      }
      

    • User field: Can directly use username
      Copy

      {
        "Assigned To": "John Doe"
      }
      

• order (optional)
  • Description: Specifies the position of new records in a specific view
  • Type: Object
  • Properties:
    • viewId
      • Description: View ID (how to get)
      • Type: String
      • Example: "viwABCDEFGHIJKLMN"
    • anchorId
      • Description: Anchor record ID (how to get)
      • Type: String
      • Example: "rec123456789ABCDE"
    • position
      • Description: Position relative to the anchor record
      • Type: String
      • Possible values:
        • “before”: Before the anchor record
        • “after”: After the anchor record
      • Example: "after"
  • Complete example:
    Copy

    {
      viewId: "viwABCDEFGHIJKLMN",
      anchorId: "rec123456789ABCDE",
      position: "after"
    }
    

  • Note: Using order allows precise control of new record positions in a specific view.

​

Response

​

Success Response

• Status code: 201 Created
• Response body: Returns the created record data.

{
  "records": [
    {
      "id": "record789",
      "fields": {
        "single line text": "text value 1"
      }
    },
    {
      "id": "record567",
      "fields": {
        "single line text": "text value 2"
      }
    }
  ]
}

​

Error Responses

• Status code: 400 Bad Request: Request body format error or missing required fields.
• Status code: 404 Not Found: Specified tableId does not exist.

​

Example Code

curl -X POST 'https://app.teable.io/api/table/__tableId__/record' \
  -H 'Authorization: Bearer __token__' \
  -H 'Content-Type: application/json' \
  -d '{
    "records": [
      {
        "fields": {
          "Name": "John Doe",
          "Age": 30
        }
      }
    ]
  }'