Content Management API > Record

Create a new record

The payload to pass to create a new record always depends on the specific settings of its model and the fields it declares.

When creating a new record, you don't need to specify a value for every field of it's model, as the ones you don't specify will be set to the field's default value (if available), or null (which is a valid value for every type of field).

Different values for different field types

If you do want to provide an explicit value for a field, then each type of field requires a different type of value. Most of the field types require scalar values — ie. a Single-line string requires a string, an Integer field requires a number, etc:

1
{
2
  // If the model has a `title` single-line string field...
3
  "name": "Alfie",
4
  // If the model has an `age` integer field...
5
  "age": 4
6
  // And so on :)
7
}

Some other fields, like Geo-location or Color fields, require objects instead of simple data types:

1
{
2
  // If the model has a `location` field of type 'Geo-location'...
3
  "location": { "latitude": 45.0703393, "longitude": 7.686864 },
4
  // If the model has an `accent_color` field of type 'Color'...
5
  "accent_color": { "red": 239, "green": 208, "blue": 156, "alpha": 255 }
6
}

We'll analyze in detail every different type of field that DatoCMS offers in the following examples.

Localized fields

Fields can be localized. If that's the case, records need to express a value for multiple locales using an object, whose keys represent the locale itself.

If your model has the "All locales required?" option turned on, then you MUST express a field value for all environment's locales:

1
{
2
  // If the model has a `title` single-line string field...
3
  "name": {
4
    "en": "Alfie",
5
    "it": "Asso"
6
  },
7
  // If the model has an `color` field...
8
  "age": {
9
    "en": { "red": 255, "green": 0, "blue": 0, "alpha": 255 },
10
    "it": { "red": 0, "green": 255, "blue": 0, "alpha": 255 }
11
  }
12
  // And so on :)
13
}

Otherwise, you can just define a subset of them (as long as all localized fields express the exact same subset!):

1
{
2
  // Even if the environment has many locales, since the model has the "All locales required?" option
3
  // turned off, we can define only the Italian locale:
4
  "name": {
5
    "it": "Asso"
6
  },
7
  "age": {
8
    "it": { "red": 0, "green": 255, "blue": 0, "alpha": 255 }
9
  }
10
}

Field type values

Single-line string

The field accepts String values.

Multi-line text

The field accepts simple String values.

Boolean

The field accepts simple Boolean values.

Integer

The field accepts simple Integer values.

Float

The field accepts simple Float values.

Date

The field accepts String values in ISO 8601 date format (ie. "2015-12-29").

Date time

The field accepts String values in ISO 8601 date-time format (ie. "2020-04-17T16:34:31.981+01:00").

If you're on legacy timezone management, remember that when sending an ISO8601 datetime you should keep in mind that the system will ignore any provided timezone, and will use the project's timezone instead.

Color