Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

Invoicing app extension

This is a Beta feature!

For more info, help, and feedback, please feel free to contact us at [email protected].

Read this if: You want to develop or are developing integration with invoicing capability


What is Invoicing app extension?

Apps that provide an invoicing capability can now display their contents right inside the Pipedrive web-app within the Deal details view. These apps can provide more contextual information and let users create and maintain invoices directly inside the Deal view.

Invoice tab's location inside Deal details view in Pipedrive's web-app

Invoice tab's location inside Deal details view in Pipedrive's web-app

Once the app is installed, users can view and add necessary information about an invoice both directly from and to the installed invoicing app.

Data about the customer will be mapped together with the Invoice as well as the Invoice Details that are fetched from the endpoints that you provide in the manifest.

Data about the customer will be mapped together with the Invoice as well as the Invoice Details that are fetched from the endpoints that you provide in the manifest.


Development process


To extend your app's capabilities to the Invoice tab in Pipedrive, we've built a logic of reverse APIs, where Pipedrive will request information from the invoicing service's API. These requests will be done to endpoints that are defined in a manifest uploaded to the Marketplace Manager by the app creator.

Steps to take

To begin, you'll need access to the Marketplace Manager, where your app is maintained.

Next, the app needs to utilize OAuth 2.0 and have the invoice integration scope enabled. For the scope, please contact us at [email protected] and request access. For more info on how to connect an app to Pipedrive or to third party services when the app acts as an intermediary, see connecting the app.

Once the tokens necessary for OAuth 2.0 are stored, you should get acquainted with how to add the manifest.


Manifest for Invoicing app extension


The manifest describes, in a special contract format, the endpoints which Pipedrive API makes requests to. Based on the responses of those requests the invoicing information will display inside Pipedrive. The data will be displayed in a pre-defined format which you can see at the top of this page.

The manifest for your app will need the appropriate URLs of invoicing service's endpoints. Once the manifest for your invoicing app is submitted to Marketplace Manager, it will be validated against a pre-defined schema.

Template for Invoicing manifest

The file below defines the JSON schema for an app that wants to display its contents inside the Pipedrive Invoice tab, through the manifest.

This is a sample of the manifest you'd need to submit for the Invoicing app extension. For your own manifest just add your values for clientID, endpoints, and templates (if they’re being used). For a detailed explanation see the explanations table.

{
  "version": "v201949",
  "clientId": "dummyclientid123",
  "features": {
    "templates": true
  },
  "endpoints": {
    "getProviderAccount": "https://www.example.com/:linkId/providerAccount",
    "getProviderAccountConnectUrl": "https://www.example.com/:linkId/providerAccountConnectUrl",
    "postInvoice": "https://www.example.com/:linkId/invoice",
    "postInvoiceStatus": "https://www.example.com/:linkId/invoiceStatus/:invoiceId",
    "getInvoices": "https://www.example.com/:linkId/invoices",
    "getInvoiceShareUrl": "https://www.example.com/:linkId/invoiceShareUrl/:invoiceId",
    "getInvoicePDF": "https://www.example.com/:linkId/invoicePDF/:invoiceId",
    "getCurrencies": "https://www.example.com/:linkId/currencies",
    "getTaxRates": "https://www.example.com/:linkId/taxRates",
    "getItems": "https://www.example.com/:linkId/items",
    "getTemplates": "https://www.example.com/:linkId/templates"
  }
}

Manifest URL format

All endpoints' values in the manifest must be provided as strings. We support the following parameters in the URL strings which will be replaced.

  • linkId will be replaced with the unique identifier the vendor registers the connection with with that represents the connection between the app and the user. linkId must be in all endpoints' URLs.
  • invoiceId will be replaced by the unique identifier of the Invoice that is returned in getInvoice endpoint. invoiceId must be provided in the URLs of postInvoiceStatus , getInvoiceShareUrl, and getInvoicePDF.

A valid URL would be "https://www.example.com/:linkId/invoicePDF/:invoiceId" where linkId is the unique identifier of the connection and invoiceId unique identifier of the invoice.

Explanation of the manifest

The Invoicing app extension's manifest describes the following object (see table).
For the endpoints, you'll need to give valid URLs of invoice service's endpoints that Pipedrive will make requests to.

Object
Explanation
Required or optional

"version"

Defines the version of the manifest. Currently, the only supported version is "v201949".

required

"clientId"

Your app's Client ID. You can get it from the app listing form -> OAuth and Access scopes in Marketplace Manager.

required

"features"

Here you can define the optional features that your app can also provide. Currently, only templates are supported.

If your app supports invoice templates then pass the following object to the "features" array:


"templates": true


Please note that when "templates": true, getTemplates endpoint must also be provided.
Send empty if you don't support templates.

required

"endpoints"

Defines a set of invoice service endpoints' URLs which Pipedrive will make requests to.

"getProviderAccount"

required

"getProviderAccountConnectUrl"

required

"postInvoice"

required

"postInvoiceStatus"

required

"getInvoices"

required

"getInvoiceShareUrl"

required

"getInvoicePDF"

required

"getCurrencies"

required

"getTaxRates"

required

"getItems"

required

"getTemplates"

optional


Connecting the app


Connecting the app to Pipedrive

The application is installed by clicking install in the Pipedrive Marketplace. Once the user has agreed to the scopes , the browser gets redirected to the app's registered callback URL (Step 3 of OAuth authorization). At this moment, the app needs to fetch and permanently store the OAuth tokens it receives from Pipedrive (Step 4 of the OAuth authorization). For invoicing apps, we require generating a unique identifier string (for example a UUID) for each connection/link which will be used by Pipedrive for all API calls executed against the app (also see Finalizing the connection).

Connecting the app to an invoicing provider

If the app is an intermediate between a service provider, it needs to authenticate against the provider according to that service specification. You’ll very likely need to authenticate against their OAuth and store the required tokens along with Pipedrive tokens.

Finalizing the connection

After the unique identifier has been generated and the OAuth tokens stored, the app needs to register itself as a data provider by calling the Pipedrive API https://app.pipedrive.com/api/v1/invoice/user/provider with RegisterProviderLink payload. To finalize everything, the app should redirect the user to the redirectUrl that was received as the response for the registration call against Pipedrive API. On that page, the user will see if both the installation and connecting process succeeded, and can then configure their preferences.

Sample of expected RegisterProviderLink payload structure:

{
   "data":{
      "linkId":"string", 
      "orgId":"string", 
      "marketplaceClientId":"string"
   }
}

Explanation of attributes:

Name
Type
Description

linkId

string
required

The unique identifier of the user in the Invoice app.

orgId

string
required

ID of the user company in the Invoice service, not the app.

marketplaceClientId

string
required

clientId of the app in Pipedrive Marketplace.


Invoicing API reference


Authentication

All requests from Pipedrive to the app will be supplemented with an authentication header using the same client ID and secret solution used for the OAuth token exchange in OAuth authorization.
E.g. Authorization: Basic <base64(client_id:client_secret)>


API payloads

All API responses from the endpoints defined in the manifest are expected to be JSON where data depends on the endpoint.

{ 
  "success": boolean,
  "data": "depends on the endpoint"
}


Invoicing API endpoints


getProviderAccount

required

Gives the status of the app, whether or not it is correctly installed and connected for the user. This endpoint returns a JSON payload with the provider account setup status.
Must return LinkStatus as data in the payload.

Sample of expected response structure:

{
   "success": boolean,
   "data":{
      "authorized": true, 
      "name":"string",
      "orgId":"string",
      "features":"LinkFeatures"
   }
}

Explanation of attributes:

Name
Type
Description

authorized

boolean
required

Displays the status of the app. Returns true or false based on the success of the authorization. If the authorization was a success, additional attributes will be sent in the response body.

name

string
optional

The name of the user’s company or organization in the invoice service.

orgId

string
optional

The ID of the user’s company or organization in the invoice service.

features

object
optional

LinkFeatures

The structure of LinkFeatures:

{
    "invoiceNumberInput": integer, 
    "documentTaxRateInput": integer,
    "lineItemTaxRateInput": integer
}

Explanation of the attributes:

documentTaxRateInput and lineItemTaxRateInput set how the tax rate will be displayed for the invoice.

Name
Type
Description/Values

invoiceNumberInput

integer
required

0 (i.e. None)- Invoice number can be auto-generated.

1 (i.e Input) - Invoice number cannot be auto-generated or the user can set it manually.

documentTaxRateInput

integer
required

0 (i.e None) - Tax rate can be applied per invoice item.
1 (i.e Select) - Tax rate can be applied only to the whole invoice. It is required to set lineItemTaxRateInput: 1 when this option is selected.

lineItemTaxRateInput

integer
required

1 (i.e Checkbox) - When the tax rate can be applied to the whole invoice then this flag shows if this tax rate can be applied to the line item.

2 (i.e Select) - Tax rate can be applied per invoice item.

For example, see the image below, where the tax rate can be applied on the line item level with each line item having a separate tax rate.

Structure of LinkFeatures for the format in the above image:

{
  "documentTaxRateInput": 0,
  "invoiceNumberInput": 1,
  "lineItemTaxRateInput": 2
}

Another example of LinkFeatures can be seen in the second image in the what is invoicing app extension section where the tax rate is selected for the whole invoice and can be applied per invoice item e.g. documentTaxRateInput: 1 and lineItemTaxRateInput: 1.


getProviderAccountConnectUrl

required

Returns a JSON payload with a URL where the user will be redirected to when the provider account connection has expired or failed for any reason.

Must return LinkAuthURL as data in the payload.

Sample of expected response structure for LinkAuthURL:

{
   "success": boolean,
   "data":{
      "url":"URL" 
   }
}

Explanation of attributes:

Name
Type
Description

url

string
required

The URL of the connection.


postInvoice

required

Creates an invoice in the provided invoice service from the payload object InvoiceCreateData. Must return Invoice as data.

Sample of InvoiceCreateData structure:

{
   "success": boolean,
   "data":{
      "contactName":"string",
      "address":"string",
      "email":"string",
      "taxNumber":"string",
      "taxModeId":"string",
      "taxRateId":"string" | null,  
      "invoiceNumber":"string" | null,
      "issueDate":"string",
      "dueDate":"string" | null,
      "currencyId":"string" | null,
      "templateId":"string" | null,
      "lineItems":[
      ]
   }
}

Explanations of attributes:

Name
Type
Explanation/Value

contactName

string
required

The name of the contact person or organization for the invoice.

address

string
required

The address of the contact person or organization for the invoice.

email

string
required

The email of the contact person for the invoice.

taxNumber

string
required

The amount of tax set per item/product.

taxModeId

string
required

The type of tax set on products/items.
Possible values:

'Inclusive'
'Exclusive'
'NoTax'

taxRateId

string
optional

The ID of the tax rate that is available in InvoiceTaxRate[].
Can be null.

invoiceNumber

string
optional

Can be null.

issueDate

string
required

The date on the invoice indicating when the invoice was created.

dueDate

string
optional

The date on the invoice indicating when payment is due.
Can be null.

currencyId

string
optional

ID of the currency type that is used.
Can be null.

templateId

string
optional

The ID of the template that is used for the invoice.
Can be null.

lineItems

array
required

CreateInvoiceLineItem[]

Sample of CreateInvoiceLineItem structure:

{
    "itemId": "string"  | null,
    "description": "string",
    "quantity": number  | null, 
    "unitPrice": number | null,
    "discountRate": number | null,
    "taxRateId": "string" | null
}

Explanations of attributes:

Name
Type
Description/Value

itemId

string
optional

Can be null.
ID of the item associated with the invoice.

description

string
required

The description of the item.

quantity

number
optional

Can be null.
The quantity of the item

unitPrice

number
optional

Can be null.
The price per item's unit.

discountRate

number
optional

Can be null.

taxRateId

string

Can be null.
Mandatory when "lineItemTaxRateInput":2

Sample of expected response structure for postInvoice endpoint:

{
    "id": "string",
    "invoiceNumber": "string",
    "contactName": "string",
    "statusCode": "string",
    "statusLabel": "string",
    "pipedriveStatusCode": "string",
    "total": number,
    "currencyCode": "string",
    "dueDate": "string (optional)",
    "paidDate": "string (optional)",
    "actions": [],
    "providerInvoiceUrl": "string",
    "isShareable": boolean
}

Explanations of attributes:

Name
Type
Description/Values

id

string
required

Unique identifier of the invoice.

invoiceNumber

string
required

The serial number of the invoice.

contactName

string
required

Name of the contact person for the invoice.

statusCode

string
required

The code of the status for the invoice.

statusLabel

string
required

The label of the status of the invoice.

pipedriveStatusCode

string
required

The status of the invoice set by Pipedrive.
Possible values:

'draft'
'created'
'issued'
'paid'
'voided'
'deleted'

total

number
required

Total numeric sum of payment.

currencyCode

string
required

Reference code indicating the type of currency payment sum is displayed in.

dueDate

string
optional

The date on the invoice indicating when payment is due.

paidDate

string
optional

The date when payment for a service was done.

actions

array
required

InvoiceAction[]
See here the expected array structure.

providerInvoiceUrl

string
required

Invoice's URL inside the invoice service.

isShareable

boolean
required

Shows if the invoice can be shared.


postInvoiceStatus

required
Updates the status of the invoice after an action has been done. We will send InvoiceAction and the endpoint must respond with Invoice as data.
See a sample of the expected Invoice structure here.
The URL, described in the manifest for this endpoint, must include invoiceId. invoiceId represents the unique identifier of an invoice, see the example URL here.

Sample of InvoiceAction structure:

{
    "id": "string",
    "label": "string",
    "requireConfirmation": "string"
}

Explanations of attributes:

Name
Type
Description/values

id

string
required

ID of the action

label

string
required

Label of the action

requireConfirmation

string
optional

'regular', 'destructive' or null


getInvoices

required

Returns invoice objects for all invoices from the provider by the list of IDs. ids is passed as a query parameter and is a comma-separated list.

Must return Invoice as data. See a sample of the expected response structure here.


getInvoiceShareUrl

required

Get a shareable link of the invoice that can be sent to the customers. The URL, described in the manifest for this endpoint, must include invoiceId. invoiceId represents the unique identifier of an invoice, see the example URL here.
Must return LinkAuthURL as data.
See a sample of expected LinkAuthURL structure here.


getInvoicePDF

required
Download the invoice as a file. Must respond with a file download stream. The URL, described in the manifest for this endpoint, must include invoiceId. invoiceId represents the unique identifier of an invoice, see the example URL here.


getCurrencies

required

Get all currencies that the invoicing service supports. Must return InvoiceCurrency[] as data.

Sample of expected response structure:

{ 
"success": boolean;
  "data": [ {    
    "id": "string required", 
    "name": "string required" 
      },
      {    
    "id": "string required", 
    "name": "string required" 
      }
     ...
    ]
}


getTaxRates

required
Get all tax rates that can be applied to the invoice. Depending on the LinkFeatures, the tax rate will apply either for the whole invoice or to an invoice line item.
Must return InvoiceTaxRate[] as data.

Sample of expected response structure:

{
   "success":"boolean",
   "data":[
      {
         "id":"string - required",
         "name":"string - required",
         "rate":"number - required"
      },
      {
         "id":"string - required",
         "name":"string - required",
         "rate":"number - required"
      },
      ...
   ]
}


getItems

required

Get a list of items that can be added as line items for the invoice. The query parameter contains the string that was entered into the search box on the form.
Must return InvoiceItem[] as data.

Sample of expected response structure:

{
   "success": boolean,
   "data":[
      {
         "id":"string",
         "label":"string",
         "description":"string",
         "unitPrice":"number",
         "taxRateId":"string"
      },
      {
         "id":"string",
         "label":"string",
         "description":"string",
         "unitPrice":"number",
         "taxRateId":"string"
      },
      ...
   ]
}

Explanations of attributes:

Name
Type
Description/Values

id

string
required

The ID of the item.

label

string
required

The label of the item.

description

string
optional

The description of the item.

unitPrice

number
optional

The unit price for the item.

taxRateId

string
optional

The ID of the tax rate assigned to an item inside an invoice.


getTemplates

optional

Get all templates that the invoice can use. Templates are used by some providers to change the invoice’s visual appearance, payment details, etc. It can be disabled via the manifest and in that case, this endpoint is not required.
Must return InvoiceTemplate[] as data.

Sample of expected response structure:

{
   "success": boolean,
   "data":[
      {
         "name":"string - required",
         "id":"string - required"
      },
      {
         "name":"string - required",
         "id":"string - required"
      },
      ...
   ]
}

Updated 15 days ago

Invoicing app extension


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.