Import - Full Import Reference

We recommend that you publish and export a sample document to get the full JSON object for that custom type. You can then use this JSON file as your template when you generate your JSON files for import.

The reference below give details for every field that can be imported and an example of the required JSON.

Type

The value for type must be an existing Custom Type id in the target repository.

Copy
      "type": "post"
    

Tags

Include any tags you want for the document in an array of strings. Even if you are only adding one tag, it must be in an array.

Tags that do not already exist in the repository will be created.

Copy
      "tags": ["foo", "bar"]
    

UID

The UID is a unique identifier for the content. A UID must be unique for a given type.

The value required for the UID field is a string that must not contain any spaces or special characters (only dashes). If the import file contains special characters or spaces, it will be automatically corrected (spaces are replaced by dashes and special characters are removed).

Duplicate UIDs

If you are trying to add a document with a UID that is already used on an existing document in the repository, it will be automatically add an incremented number to the end of the UID (example: "my-new-page" will automatically become "my-new-page1").

Copy
      "uid": "my-unique-identifier"
    

Key Text

Let's say that you have a Key Text field with the API ID of "subtitle-text" in your target custom type. Simply add a string for the Key Text value.

Copy
      "subtitle-text": "This is my subtitle text!"
    

Select

Let's say you have a Select field with the API ID of "author" in your target custom type. Add a string for the value that matches one of the configured options for the Select field.

Invalid Options

If the value provided does not match an option that is configured in the target custom type for the Select field, no value will be set for the imported content.

Copy
      "author": "John Doe"
    

Color

Here is how you would assign a value to a Color field that has an API ID of "title-color". This field takes a string of a Hex color value.

Be sure to provide a valid Hex color value. If an invalid color code is given, it will import the invalid value.

Copy
      "title-color": "#62a9c4"
    

Timestamp

Lets say that you have a Timestamp field with the API ID of "event-time". You just need to provide a string with a valid timestamp.

If the timestamp format is not valid, no value will be loaded into the field.

Copy
      "event-time": "2016-09-15T22:00:00+00:00"
    

Date

Let's assuming that the target custom type has a Date field type with an API ID of "release-date". Just provide a string with the date in the following format: "YYYY-MM-DD".

If the date format is not correct, no value will be entered for the field.

Copy
      "release-date": "2016-09-16"
    

Range

The following example is for a Range field with an API ID of "price-discount". You just need to provide the field a string with the number value.

Note that there is no control on this. If the number doesn't respect the configured range, its value will be set anyway.

If the value of this is not a number, no value will be imported.

Copy
      "price-discount": "15"
    

Number

Let's say that you have a Number field with an API ID of "price". Assign this field a string with the number you want to give the field.

If the value given is not a number, no value will be imported.

Copy
      "price": "19"
    

Rich Text

To import a Rich Text field, you must provide an array of 1 object per paragraph. Each paragraph has a type line that defines the paragraph's formatting option.

The type options available are:

  • heading1
  • heading2
  • heading3
  • heading4
  • heading5
  • heading6
  • paragraph
  • preformatted

Each paragraph can also have inline rich formatting options. The available options for rich formatting within a paragraph are:

  • strong (for bold text)
  • em (to add italics)
  • hyperlink (to add a link to an external web page, internal page, or internal media library item)
  • o-list-item (an ordered list)
  • list-item (an unordered list)

You can also insert other media items into your Rich Text content. Here are the available options:

  • Image
  • Embed

Rich Text Configuration

Note that the content you define will be imported regardless of whether or not it agrees with the configuration of the Rich Text field. That is, if your Rich Text field is defined in the custom type to only have the type "heading1", it will not prevent you from uploading text of the type "paragraph" or "heading2" to that field.


The same goes for if the import file has multi paragraphs while the Rich Text field is configured to only have one single line of content. The multi-line content will be imported anyway. Be aware of this.

Rich Text - Single paragraph example

Here is a simple example of a Rich Text field with the API ID of "title". This field takes only a single line of text which we've defined to be a heading1 element.

Copy
      "title": [
  {
    "type": "heading1",
    "content": {
      "text": "This is the document title",
      "spans": []
    }
  }
]
    

Rich Text - Multiple paragraph example

The following is an example of a multi-paragraph Rich Text field with the API ID of "body".

This assumes that the target field is configured for multiple paragraphs.

Copy
      "body": [
  {
    "type": "heading1",
    "content": {
      "text": "This is my section title",
      "spans": []
    }
  },
  {
    "type": "paragraph",
    "content": {
      "text": "Here is the text for that section.",
      "spans": []
    }
  }
]
    

The following is an example of a paragraph section that might be included in a Rich Text field import array. In this case, the text is a hyperlink.

Copy
      {
  "type": "paragraph",
  "content": {
    "text": "Donec quis dui at dolor tempor interdum.",
    "spans": [
      {
        "type": "hyperlink",
        "start": 0,
        "end": 40,
        "data": {
          "url": "https://prismic.io",
          "preview": {
            "title": "https://prismic.io"
          }
        }
      }
    ]
  }
}
    

Rich Text Section - Image

The following is an example of an image section that might be included in a Rich Text field import array.

Copy
      {
  "type": "image",
  "content": {
    "text": "",
    "spans": []
  },
  "data": {
    "width": 640,
    "height": 480,
    "origin": {
      "id": "V9vEGhgAABgAn8s7",
      "url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg",
      "width": 640,
      "height": 480
    },
    "edit": {
      "zoom": 1,
      "crop": {
        "x": 0,
        "y": 0
      },
      "background": "#fff"
    },
    "url": "https://prismic-io.s3.amazonaws.com/import-test/8fa93b1b22b51ec7050d2684d70e40446c2335f0_technics-q-c-640-480-7.jpg"
  }
}
    

Rich Text Section - Embed element

The following is an example of an embed element that might be included in a Rich Text field import array.

Copy
      {
  "type": "embed",
  "data": {
    "type": "video",
    "embed_url": "https://www.youtube.com/watch?v=y6y_4_b6RS8"
  },
  "content": {
    "text": "",
    "spans": []
  }
}
    

The following is an example of a paragraph section that might be included in a Rich Text field import array. In this case, the second word is a hyperlink to an image in the media library.

Copy
      {
  "type": "paragraph",
  "content": {
    "text": "Cras iaculis ultricies nulla.",
    "spans": [
      {
        "type": "hyperlink",
        "start": 5,
        "end": 12,
        "data": {
          "wioUrl": "wio://medias/V9vEGhgAABgAn8s7",
          "url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg",
          "kind": "image",
          "id": "V9vEGhgAABgAn8s7",
          "height": "480",
          "width": "640",
          "size": "41298",
          "date": "09/16/16 10:03",
          "name": "technics-q-c-640-480-7.jpg",
          "preview": {
            "title": "technics-q-c-640-480-7.jpg",
            "image": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg"
          }
        }
      }
    ]
  }
}
    

Images

Reference not yet available. For the time being, you may refer to an export JSON sample to see the syntax for importing images.

Images - Importing a local image

Let's say that you have an Image field with an API ID of "illustration". Here is how you would define the url if you wanted to upload the image along with the document. You would need to make sure to include image.jpg in the import ZIP file.

Copy
      "illustration": {
  "origin": {
    "url": "image.jpeg"
  },
  "url": "image.jpeg"
}
    

Import a distant image

The importer will download the resources from the provided urls and add them to your repository’s media library. If a given asset is used several times in one import batch, that asset will be added only once to the media library.

You can see an example on how to import an asset in your prismic.io media library.

Copy
      "my-image": {
    "origin": {
      "url": "https://pbs.twimg.com/profile_images/770646787006861312/bX2KLhDL.jpg"
    }
  }
    

GeoPoint

Let's say that you have a GeoPoint field with an API ID of "location". You just need to provide the latitude & longitude values as shown below.

Copy
      "location": {
  "position": {
    "lat": 47.6205063,
    "lng": -122.3492774
  }
}
    

Embed

Let's say that you have an Embed field with an API ID of "soundcloud-player". You must specify the "type" field and the "embed_url".

Refer to a JSON export example of the type of embed you are trying to include to know what you need to set for "type".

Copy
      "soundcloud-player": {
  "type": "rich",
  "embed_url": "https://soundcloud.com/seacastle-1"
}
    

Let's say that you have a Link field with an API ID of "document-link". The following example would add a link to an existing document in the repository of the type "page" with the document ID of "V-p_rx4AAB4AmyHa".

Copy
      "document-link": {
  "id": "V-p_rx4AAB4AmyHa",
  "mask": "page"
}
    

Let's say that you have a Link field with an API ID of "web-link". The following example would add a link to the web.

Copy
      "web-link": {
  "url": "http://seacastleband.com"
}
    

Let's say that you have a Link field with an API ID of "media-link". The following example would add a link to an existing asset in the repository's media library with the ID of "V9vHXBgAABgAn9hF".

Copy
      "media-link": {
  "wioUrl": "wio://medias/V9vHXBgAABgAn9hF",
  "url": "https://prismic-io.s3.amazonaws.com/import-test%2F0fcf1760-dce7-4d12-8e20-a3e11472c797_city-q-c-640-480-4.jpg",
  "kind": "image",
  "id": "V9vHXBgAABgAn9hF",
  "height": "480",
  "width": "640",
  "size": "34769",
  "date": "09/16/16 10:04",
  "name": "city-q-c-640-480-4.jpg"
}
    

Let's say that you have a Link field with an API ID of "media-link". The following example would add a link to a new asset to be loaded into the repository's media library. You would need to make sure to include the asset file in the import ZIP file.

The import module will upload the asset into the media library and add the link to this field.

Copy
      "media-link": {
  "url": "image.png",
  "kind": "image",
  "name": "image name",
  "id": "",
  "size": "",
  "height": "",
  "width": ""
}
    

Group

Let's say that you have a repeatable Group field with an API ID of "links-group". Inside that group you have a Key Text field with the API ID of "label" and a Link field with the API ID of "link".

The following example would add two sets of links with labels.

Copy
      "links-group": [
  {
    "label": "Link This!",
    "link": {
      "url": "http://css-tricks.com"
    }
  },
  {
    "label": "Link That!",
    "link": {
      "url": "http://jurassicpark.com"
    }
  }
]
    

Slices

Slices are content blocks that can be freely organized within a Slice zone. A single Slice can contain several group items.

If you look at the exported JSON for a Slice that contains several items within a group, you’ll see the following object for each item.

Copy
      "key": "alternated-highlights$b0b1de36-ffb7-406d-86ca-0855dae17c7e",

    

If you want to import several items within a Slice, the import JSON should just contain the Slice ID like this:

Copy
      "key": "alternated-highlights",
    

The hash after the $ will be automatically assigned by the importer.

Other than that, refer to the exported JSON for each of your slice types to see what what the import JSON code needs to be imported.