Create, Update or Upsert Data using Cells API

POST {{host}}/api/rest/v4/data/entrydata/{{entryTypeId}}
Authorization: Bearer {{token}}
 
or
 
PUT {{host}}/api/rest/v4/data/entrydata/{{entryTypeId}}
Authorization: Bearer {{token}}

• To only Create, use POST method.
  • If using POST method, all entryIds must be negative and not existing.
• To update or upsert, use PUT method.
  • entryIds can either be negative to indicate new, or existing.

Params

Details

The Cells API request body includes a very specific json object with 2 fields: "storeRequests" and "binaryStoreRequests" which are both optional arrays of objects.

{ 
  "storeRequests": [{},{}], 
  "binaryStoreRequests" :[{},{}]
}

storeRequests

storeRequests array is used for all non-binary data like strings, numbers, text etc.

• This is where you normal data will go.

storeRequests includes the data "value", the "fieldId" the value is associated to, and either a negative or positive "entryId". To associate field data to different unique entries, use a different entryId. For example, all fields with entryId = -1 would belong in the same "row" of data. All fields with entryId = -2, would belong to a second row.

Sample

"storeRequests": [
  {
    "entryId": -1, -- entryId: negative indicating a new entry, or positive for an existing entry
    "fieldId": 2300, -- fieldId that this value will be associated
    "ignoreNearDups": true,  -- true or false 
    "value": "1st row, 1st Field" --value
  },
  {
    "entryId": -1, --associates this entry with the above field
    "fieldId": 2227,
    "ignoreNearDups": true,
    "value": "1st row. Second Field"
  },
  {
    "entryId": -2, --associates this entry with a new entry in this payload
    "fieldId": 2300,
    "ignoreNearDups": true,
    "value": "2nd row, 1st Field"
  },
  {
    "entryId": -2, --associates this entry with the above field
    "fieldId": 2227,
    "ignoreNearDups": true,
    "value": "2nd row. Second Field"
  },
]

binaryStoreRequests

binaryStoreRequests are used for all documents, images, binary data, and attachments. It is the array that contains the metadata for the binary data, associating the entryId and fieldId information to the Filename in the MIME attachement.

Binary data may be stored in 2 different system field types: 13 and 16.

• FieldType 13 is any "Binary" data like a pdf or other document.
• FieldType 16 is "Image" like png or jpeg.

Tip See Field Types and How to Upload Files for more details.

Associating metadata to the filename of the MIME attachment.

binaryStoreRequests follow a similar pattern as storeRequests for "fieldId" and "entryId" as stated above. The difference here is that the binary data itself is associated to the multipart MIME attachment as "fileName" with the "formatType" indicating to DealCloud what type of file it is.

"binaryStoreRequests": [
    {
        "entryId": -1,  -- entryId: negative indicating a new entry, or positive for an existing entry and associates it to storeRequest json if present
        "fieldId": 9569, -- fieldId that this attachment will be associated
        "formatType": "jpg", -- matches the file extension of the attachment
        "contentType": "image/jpg", -- matches standard mime types
        "name": "Headshot.jpg" -- attachment filename
    }
]

Additional Requirements

• Supports up to 10,000 fields per payload.
• If any data in a payload is invalid, the entire payload fails.
• Do not split an Entry across payloads.
  • The new Entry Id is only valid for the payload. Splitting a entry across payloads will result in new entries with partially filled fields.
• Binary data is handled using multi-part MIME payload.
• When building the MIME part for the binaryStoreRequest json, the Content-Disposition form-data name MUST equal "model" with a Content-Type of application/json: e.g. Content-Disposition: form-data; name="model"
  • Additionally, when building the 2nd MIME part containing the binary data, the Content-Disposition form-data name MUST equal "attachment" with a filename equal to the incoming file and it's Content-Type equaling the appropriate MIME content type. e.g. Content-Disposition: form-data; name="attachment"; filename="Headshot.jpg" Content-Type: image/jpg
  • When uploading binary data, it's important to recognize the order of the form-data in the multipart MIME message.
    • The order MUST be "json" form-data, containing either storeRequest/binaryStoreRequest json followed then by the attachments in the next form-data boundary.
    • If any filenames have the same name

Samples

Sample Requests

POST {{host}}/api/rest/v4/data/entrydata/{{entryTypeId}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "storeRequests": [
    {
      "value": "Created Via API",
      "ignoreNearDups": true,
      "entryId": -1,
      "fieldId": 2300
    },
    {
      "value": "Second Field",
      "ignoreNearDups": true,
      "entryId": -1,
      "fieldId": 2227
    }
  ]
}