How to Upload Files and Documents

Uploading files or documents involves working with the Cells API. In DealCloud, all file attachments are stored in a dedicated object/entrylist called Attachments, which is a system object. From there, the entry record of the file can be referenced within other records across other objects if needed.

Therefore, we first need to upload the file to the "Attachments" object/entrylist. Next, we can reference the uploaded file in the relevant record within an Attachment field to show up as an uploaded file.

Step 1 - Identify the Attachments object

First, we need to identify the "Attachments" object/entrylist in our DealCloud site. Using the GET Entry Types API (from the Schema APIs), we can see the Attachment entrylist has an ID of 2010.

GET {{host}}/api/rest/v4/schema/entrytypes
Authorization: {{auth}}

[
  {
    "apiName": "Attachment",
    "singularName": "Attachment",
    "pluralName": "Attachments",
    "entryListType": 7,
    "entryListSubType": 0,
    "id": 2010,
    "name": "Attachment",
    "entryListId": -5
  }
  ...
]

Step 2 - Identify the Attachments object's fields

Next, we want to identify the fields of this Attachments object. We can use the GET Entry Type Fields API endpoint to identify the fields of the Attachments entrylist. We mainly care about the "Title" (or equivalnet) and the "Documents" fields. Other fields are optional for the purposes of uploading a file.

Note that the "Title" field is ID 2099
Note that the "Document" field is ID 2103.
Also note that "Document" is "fieldType": 13. This is the DealCloud field type for binary files and how we can verify we're working with the right field. Attempting to upload files to fields that are not "fieldType": 13 will result in error.

GET {{host}}/api/rest/v4/schema/entrytypes/Attachment/fields
Authorization: {{auth}}

[
  {
    "apiName": "Title",
    "fieldType": 1,
    "isRequired": true,
    "allowDuplicates": true,
    "warnOnNearDuplicates": false,
    "isMoney": false,
    "isMultiSelect": false,
    "entryLists": [],
    "systemFieldType": 9,
    "isKey": false,
    "isCalculated": false,
    "isAttachment": false,
    "isStoreRequestSupported": true,
    "id": 2099,
    "name": "Title",
    "entryListId": 2067
  },
  {
    "apiName": "Document",
    "fieldType": 13,
    "isRequired": true,
    "allowDuplicates": true,
    "warnOnNearDuplicates": false,
    "isMoney": false,
    "isMultiSelect": false,
    "entryLists": [],
    "systemFieldType": 20,
    "isKey": false,
    "isCalculated": false,
    "isAttachment": false,
    "isStoreRequestSupported": true,
    "id": 2103,
    "name": "Document",
    "entryListId": 2067
  }
...
]

Step 3 - Construct the Request Body for File Upload

Now, we need to construct the request body as below with the right values we identified in the previous steps. For the contentType property, refer to this link for common MIME types (opens in a new tab)

{
    "storeRequests": [
    {
      "value": "My New File",               <----- The name of the entry record you want to create
      "ignoreNearDups": true,               <----- OPTIONAL to ignore duplicate name checks
      "entryId": -1,                        <----- Value of -1 means create new entry
      "fieldId": 2099                       <----- ID of the *Title* field
    },
],
    "binaryStoreRequests": [
    {
        "formatType": "pdf",                 <----- The file format
        "contentType": "application/pdf",    <----- The MIME type (see link above)
        "name": "DealCloud is Awesome.pdf",  <----- Exact filename from the source
        "entryId": -1,                       <----- Value of -1 means create new entry
        "fieldId": 2103                      <----- ID of the *Document* field (system binary field)
    }
]
}

Step 4 - Put it all together

Construct the full POST request along with file to be uploaded as below. Alternatively, if you're using Postman, reference the image below on how to format the request.

HTTP Request

POST {{host}}/api/rest/v4/data/entrydata/attachment HTTP/1.1
Authorization: {{auth}}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="model"
Content-Type: application/json
 
{
  "storeRequests": [
    {
      "value": "My New File",
      "ignoreNearDups": true,
      "entryId": -1,
      "fieldId": 2099
    },
],
"binaryStoreRequests": [
    {
        "formatType": "pdf",
        "contentType": "application/pdf",
        "name": "DealCloud is Awesome.pdf",
        "entryId": -1,
        "fieldId": 2103
    }
]
}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="attachment"; filename="FILEPATH:\DealCloud is Awesome.pdf"
Content-Type: <Content-Type header here>
 
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Postman

Upload File Postman

Step 5 - Successful Request Response

Once you successfully make the request, you will get a response like below. Note down the RowId - this is the "entryId" or the "recordId" of the file you just uploaded. We will use this ID to "attach" or reference this file to any other records we need to.

Note, if you don't need to reference this new uploaded file anywhere else, you don't need to follow the following steps.

[
    {
        "entryId": -1,
        "fieldId": 2099,
        "rowId": 10557787,
        "isNoData": false,
        "value": "My New File"
    },
    {
        "entryId": -1,
        "fieldId": 2103,
        "rowId": 10557787,
        "isNoData": false,
        "value": "DealCloud is Awesome.pdf"
    }
]

Step 6 - Identify the Object and Fields to Attach the File

Using the same process laid out in Step 1 and 2, identify the entrylist/object in which you want to attach your newly uploaded file to. Obtain the ID of the relevant "Attachment" field in the relevant object, which should be a "fieldType": 5 - a type of reference field. You will want to make sure you have an attachment field in the relevant object, otherwise you will want to add it from Object Management.

For example, if we want to attach our file to a new Deal record, we will obtain the fields of our Deal object like below.

GET {{host}}/api/rest/v4/schema/entrytypes/Deal/fields
Authorization: {{auth}}

In this example, we have a field called "Deal File", which is an attachment reference field, which we will use to reference our previously uploaded file.

...
{
    "apiName": "DealFile",
    "fieldType": 5,
    "isRequired": false,
    "allowDuplicates": true,
    "warnOnNearDuplicates": false,
    "isMoney": false,
    "isMultiSelect": false,
    "entryLists": [
      2010
    ],
    "systemFieldType": 0,
    "isKey": false,
    "isCalculated": false,
    "isAttachment": true,
    "isStoreRequestSupported": true,
    "id": 3490,                                      <---- The field ID we need
    "name": "Deal File",
    "entryListId": 2037
  }
...

Step 7 - Construct Request for Reference File Attachment

Similar to Step 3 and 4, construct the request for the record you want to attach your file to. In this example, we're creating a new record in our Deals object and attaching the file we just created.

POST {{host}}/api/rest/v4/data/entrydata/Deals HTTP/1.1
Content-Type: application/json
Authorization: {{auth}}
 
{
   'storeRequests': [
        {
            "EntryId": -1,            <----- Value of -1 means create new entry
            "FieldId": 3490,          <----- ID we obtained from Step 6
            "value": 10557787,        <----- The *RowID* we obtained after file upload.
        }
    ]
}

Note, you can add multiple JSON objects in the storeRequests array to fill in additional fields and values in the record you are creating. The above example simply highlights the basic of attaching the file to a new record.

Step 8 - Success

If you follow the above steps, you will have successfully uploaded a file to DealCloud.

Common Errors

Having the wrong object and field IDs in any of the requests
Attempting to upload files to an incorrect type of field. Note, file uploads are only possible to a binary field type, which is fieldType 13
Attmepting to upload files directly to an Attachment field in a random object. Remember, files must first be uploaded to the right field in the Attachments system list, then referenced to any other necessary list.

Guides How to Backlink DMS Documents