# Create records

`POST https://api.airtable.com/v0/{baseId}/{tableIdOrName}`

Creates multiple records. Note that table names and table ids can be used interchangeably.
We recommend using table IDs so you don't need to modify your API request when your table name changes.

Your request body should include an array of record objects. Each of these objects should have one key
whose value is an inner object containing your record's cell values, keyed by either field name or field id.

Returns a unique array of the newly created record ids if the call succeeds.

You can also include a single record object at the top level.

## Requirements

- **Authentication:** [Personal access token](https://airtable.com/developers/web/api/authentication.md#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication.md#types-of-token)
- **Scope:** [`data.records:write`](https://airtable.com/developers/web/api/scopes.md#data-records-write)
- **User role:** Base editor
- **Billing plans:** All plans

## Path parameters

- `baseId: string`

- `tableIdOrName: string`

## Request body

- `fields: object` — optional

  Create **a single** record

  - `[key: string]: object | number | true | string | string | number | true | array<string | number> | array<object> | array<number | string | boolean | unknown> | array<string>`

- `records: array<object>` — optional

  Create **multiple** records

  Pass in multiple records to create multiple in one request

  - `fields: object` — required

    - `[key: string]: object | number | true | string | string | number | true | array<string | number> | array<object> | array<number | string | boolean | unknown> | array<string>`

- `returnFieldsByFieldId: boolean` — optional

  An optional boolean value that lets you return field objects keyed by the field id.

  This defaults to `false`, which returns field objects where the key is the field name.

- `typecast: boolean` — optional

  The Airtable API will perform best-effort automatic data conversion from string values
  if the typecast parameter is passed in. Automatic conversion is disabled by default to
  ensure data integrity, but it may be helpful for integrating with 3rd party data sources.

## Response format

Response is one of the following variants:

### Variant 1

- `records: array<object>` — required

  - `id: string` — required

    Record ID

  - `createdTime: string` — required

    A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z"

  - `fields: object` — required

    Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).

    See [Cell Values](https://airtable.com/developers/web/api/field-model.md) for more information on cell value response types.

    - `[key: string]` — [Cell value](https://airtable.com/developers/web/api/field-model.md)

- `details: object` — optional

  - `message: "partialSuccess"` — required

  - `reasons: array<"attachmentsFailedUploading" | "attachmentUploadRateIsTooHigh">` — required

### Variant 2

- `id: string` — required

  Record ID

- `createdTime: string` — required

  A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z"

- `fields: object` — required

  Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).

  See [Cell Values](https://airtable.com/developers/web/api/field-model.md) for more information on cell value response types.

  - `[key: string]` — [Cell value](https://airtable.com/developers/web/api/field-model.md)

- `details: object` — optional

  - `message: "partialSuccess"` — required

  - `reasons: array<"attachmentsFailedUploading" | "attachmentUploadRateIsTooHigh">` — required

### Example — Success response multiple

```sh
curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
    "records": [
      {
        "fields": {
          "Address": "333 Post St",
          "Name": "Union Square",
          "Visited": true
        }
      },
      {
        "fields": {
          "Address": "1 Ferry Building",
          "Name": "Ferry Building"
        }
      }
    ]
  }'
```

```json
{
  "records": [
    {
      "createdTime": "2022-09-12T21:03:48.000Z",
      "fields": {
        "Address": "333 Post St",
        "Name": "Union Square",
        "Visited": true
      },
      "id": "rec560UJdUtocSouk"
    },
    {
      "createdTime": "2022-09-12T21:03:48.000Z",
      "fields": {
        "Address": "1 Ferry Building",
        "Name": "Ferry Building"
      },
      "id": "rec3lbPRG4aVqkeOQ"
    }
  ]
}
```

### Example — Success response single

```sh
curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
    "fields": {
      "Address": "333 Post St",
      "Name": "Union Square",
      "Visited": true
    }
  }'
```

```json
{
  "createdTime": "2022-09-12T21:03:48.000Z",
  "fields": {
    "Address": "333 Post St",
    "Name": "Union Square",
    "Visited": true
  },
  "id": "rec560UJdUtocSouk"
}
```