Adding remote files via Pipedrive API
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.
Parameter | Examples and explanations |
(required) | Choose one of the following:
|
(required) | Title of the created file |
(required) | Choose one of the following items:
|
(required) | The ID of the specific item you wish to have the created file linked with. The file will appear in the details view of this specific item. |
(required) |
|
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.
Parameters | Examples and explanations |
(required) | Choose one of the following items:
|
(required) | The ID of the specific item you wish to have the created file linked with. The file will appear in the details view of this specific item. |
(required) |
|
(required) |
|
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;
}