1. Introduction

Remote files are files that are stored on a remote location and not, for example, on your local drive. Currently, we only support files that originate from Google Drive.

For adding remote files in Pipedrive we have two endpoints POST /files/remote and POST /files/remoteLink. The following tutorial will cover code samples and explanations for working with those endpoints.

• POST /files/remote allows you to create a new file in Google Drive and specify which item (Deal, Person or Organization) that created file will be linked and associated to in Pipedrive.
  
• With POST /files/remoteLink you can link a file that already exists in Google Drive to an item (Deal, Person or Organization).

2. A. Creating a remote file and link it to an item

First, you need to think about how you authenticate your request to our API. You can use either an API token (see the code snippet below) or OAuth. For more information about authenticating your requests, see authentication.

// Pipedrive API token
$api_token = 'YOUR_API_TOKEN';
// Pipedrive company domain
$company_domain = 'YOUR_COMPANY_DOMAIN';
// URL for creating an empty remote file and associate it with an item
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/files/remote?api_token=' . $api_token;

You also need to give values to the following parameters and make the POST request. You can see the full code example below.

3. Full code example (PHP)

Don't forget to authenticate your request. You can use the following URL for a request with api_token.

// URL for creating an empty remote file and linking it with an item
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/files/remote?api_token=' . $api_token;

Here's the PHP code snippet

<?php
//add authentication with api_token here
$data = array(
    'file_type' => gdoc,
    'title' => 'New proposal for John Doe',
    'item_type' => deal,
    'item_id' => 12,
    'remote_location'=> googledrive
);
  
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
 
echo 'Sending request...' . PHP_EOL;
 
$output = curl_exec($ch);
curl_close($ch);
 
// Create an array from the data that is sent back from the API
// As the original content from server is in JSON format, you need to convert it to PHP array
$result = json_decode($output, true);
 
// Check if the data returned in the result is not empty
if (empty($result['data'])) {
    exit('Adding failed' . PHP_EOL);
}
 
// Check if file ID came back, if it did, print out success message
if (!empty($result['data']['id'])) {
    echo 'File created and linked successfully! ' . PHP_EOL;
}

4. Full code example (Node.js)

And the Node.js equivalent

//All tutorial Node.Js code examples are for reference only and shouldn't be used in production code as is. In production, a new new pipedrive.ApiClient() instance should be initialised separately for each request.
const pipedrive = require('pipedrive');
const defaultClient = new pipedrive.ApiClient();

// Configure authorization by settings api key
// PIPEDRIVE_API_KEY is an environment variable that holds real api key
defaultClient.authentications.api_key.apiKey = process.env.PIPEDRIVE_API_KEY;

async function addRemoteFile() {
    try {
        console.log('Sending request...');

        const api = new pipedrive.FilesApi(defaultClient);

        // you can assign a file to a deal , person , organization , activity or product by setting the itemType and itemId
        const fileType = 'gdoc';
        const title = 'File 1';
        const itemId = 35;
        const itemType = 'deal';
        const remoteLocation = 'googledrive';
        const response = await api.addFileAndLinkIt(fileType, title, itemType, itemId, remoteLocation)

        console.log('File successfully added and linked', response);
    } catch (err) {
        const errorToLog = err.context?.body || err;

        console.log('Adding failed', errorToLog);
    }
}

addRemoteFile();

5. B. Linking an existing remote file to an item

To link an existing remote file to an item you need first authenticate your request and then add values to the following parameters. The user needs to have an activated Google Account in Pipedrive for the file to be added successfully. You can see the full code example below.

6. Code example

Don't forget to authenticate your request. You can use the following URL for a request with api_token.

// URL for linking an existing remote file
$url = 'https://' . $company_domain . '.pipedrive.com/api/v1/files/remoteLink?api_token=' . $api_token;

Complete sample code can be found below:

<?php
//Add authentication with api_token here
$data = array(
    'item_type' => deal,
    'item_id' => 12,
    'remote_id' => 'magic-file-123',
    'remote_location'=> googledrive
); 
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
 
echo 'Sending request...' . PHP_EOL;
 
$output = curl_exec($ch);
curl_close($ch);
 
// Create an array from the data that is sent back from the API
// As the original content from server is in JSON format, you need to convert it to PHP array
$result = json_decode($output, true);
 
// Check if the data returned in the result is not empty
if (empty($result['data'])) {
    exit('Linking failed' . PHP_EOL);
}
 
// Check if file ID came back, if it did, print out success message
if (!empty($result['data']['id'])) {
    echo 'File linked successfully! ' . PHP_EOL;
}