Registering a private app

Private apps, aka internal apps, enable you to share your integration with any user/company in Pipedrive via a direct, unlisted installation link. To do so, you must fill out the parts of the app registration form that cover app creation and make your private app live.


How to find Developer Hub


First, go to Settings by clicking on your profile name in the upper right corner of the top navigation bar. Find the company name of your sandbox account and choose Developer Hub from the drop-down menu:

2576

You must have a developer sandbox account for app creation to see Developer Hub.



Register a new private app


🚧

NB: Do pick your app type carefully, as it cannot be changed later on Developer Hub.

To register a new app, click on the green “Create an app” button (or “+ Create an app” if you have existing apps) followed by “Create private app”. This is also where you’d see a list of your public and private apps if you have any.

2560

App registration form


The app registration form for private apps contains three different tabs.

You can save your app anytime by clicking the green “Save” button and exiting the form by clicking the white “Close app settings” button. This will take you back to your Developer Hub dashboard.

Read on to find out how and what to fill in each tab.

Basic info

Developer Hub > private apps - basic info

This tab has two required fields – App name and OAuth Callback URL. Once you’ve filled this in, click the green “Save” button to save the form. You’ll then be brought to the second tab, “OAuth & access scopes”, where you’ll get your client_id and client_secret and the option to make your app live via the “Change to live” button.

FieldDescription
App name (required)Insert your app’s name by what it’s going to be recognized by in the Marketplace.

Example: Car Services App
Callback URL (required, one URL per app)Insert a link where an authorization code will be sent if the user approves or declines the installation of your app. This link is also where we return the user after successful authentication. Technically, a callback URL is the same thing as an OAuth redirect_uri.

It’s okay to insert a non-functioning URL when creating a new app as long as you can update this field with a proper URL after implementing the logic needed to accept user authorization in your code. Please keep in mind that we allow only one callback URL per app.

Example: https://www.carservicesapp.com/API/v2/callback

OAuth & Access scopes

Developer Hub > private apps - OAuth & access scopes
FieldDescription
Access scopes (required)Using scopes, you can specify precisely what data access your application needs. Your selection will depend significantly on the endpoints you use in your app.You can also select the respective scope in this section if you are building a manifest-based app extension.

Example:
:white-check-mark: Read users data
:white-check-mark: See recent account activity
Installation URLThis is where you can add an optional OAuth authorization link with the state parameter. Find out more about the state parameter here.
Client IDThis is where you will get your app’s unique client_id and client_secret for OAuth authorization.

👍

Once you’ve completed filling up the Basic info and OAuth & access scopes, we advise you to start installing your app and testing it to see how it works. You can do so by clicking on the green “Install & test” button in the bottom left of the tab.


App extensions

Developer Hub - private apps > app extensions

App extensions let you extend Pipedrive’s user interface with your app’s functionality and content to let users do more in one place. Find out more about them here.

Within Developer Hub, the App extensions tab is where you can add new app extensions and manage the ones you’ve added before. A modal with an app extension creation form will open when you click the button to add the respective app extension.

You can also make your app live via this tab's “Change to live” button.

Link actions

Learn more here.

FieldDescription
Action name (required)Insert your app action’s name that will be displayed in the Pipedrive UI. The name should be short, descriptive of the app action, and be in a sentence case format.Example: Send quote - Car Services
Action descriptionTo showcase the interactive features of your app, your action’s name and description will appear in the Features section of your Marketplace app listing.

Use the description field to let users know what they can do with this action.

Optional; max 150 characters.
URL link (required)Add the URL that will redirect the user to the correct app page when an action is clicked. The URL must handle both scenarios of the user being logged into your app and not being logged in.

Example: https://www.carservicesapp.com/handle_action
JWT secretIf left empty, client_secret will be used by default.
Locations (one required)Specify in which views the app action will be displayed. There can be a maximum of 3 app actions per app or custom modals in one view, altogether 21 (7 different views x 3 actions per view).

Example:
:white-check-mark: Activities list
:white-check-mark: Person details

JSON modals

Learn more here.

FieldDescription
Action name (required)The name of the JSON modal. The name should be short (max 30 characters), actionable, and sentence-cased (only capitalize the first word).

Example: + Prod. details - Car Services
Action descriptionTo showcase the interactive features of your app, your action’s name and description will appear in the Features section of your Marketplace app listing.

Use the description field to let users know what they can do with this action.

Optional; max 150 characters.
API endpoint (required)All API requests related to this action will be sent to this URL.

Example: https://www.carservicesapp.com/handle_action
JWT secretIf left empty, client_secret will be used by default.
JSON schema (required)The JSON schema for your JSON modal.
Locations (one required)There can be a maximum of 3 app actions or custom modals per location. Each app can have a total of 21 app actions. See more about available locations in app actions' visibility.

Example: Deal details

JSON panels

Learn more here.

FieldDescription
Panel name (required)Insert your JSON panel’s name that will be displayed in the Pipedrive UI. The JSON panel’s name should be descriptive and have a maximum of 30 characters.

Example: Car PM – Car Services
Panel descriptionTo showcase the interactive features of your app, your panel’s name and description will appear in the Features section of your Marketplace app listing.

Use the description field to let users know what they can do within this panel.

Optional; max 150 characters.
API Endpoint (required)The URL of the endpoint which we'll use to fetch the data of the object properties

Example: www.api.pipedrive.com/deal-view/visits
HTTP Auth username (required) and HTTP Auth password (required)Our service will send the HTTP request with these credentials as the Basic Authentication header to protect your data. To protect your data, we strongly recommend using authenticated HTTPS requests. Note that we do not support self-signed certificates.
JWT secretJWT is required if HTTP Auth is not provided.
JSON data structure (required)A JSON file that describes the structure of your JSON panel as seen in the Pipedrive UI. See here for more information.
Panel locations (one required)Choose where the panel will be displayed:
– Deal details
– Person details
– Organization details

Each app can have one JSON or custom panel in each location.

Custom modals

Learn more here.

FieldDescription
Modal name (required)The name of your custom modal. Descriptive, max 30 characters and should be sentence-cased (only capitalize the first word).
Modal descriptionTo showcase the interactive features of your app, your modal’s name and description will appear in the Features section of your Marketplace app listing.

Use the description field to let users know what they can do within this modal.

Optional; max 150 characters.
Iframe URL (required)URL of the web content to be shown within the iframe
– Please ensure your iframe URL uses HTTPS
JWT secretOptional. Defaults to client secret
Entry pointsThe custom modal will be shown as a link in the actions menu of the chosen entry point(s).

Choose the location(s) your custom modal can be triggered from:
– Activities list
– Deal details
– Deals list
– Person details
– People list
– Organization details
– Organizations list

If no entry points are selected, the only way to open a modal is via the SDK. Maximum 3 app extensions per location.

Each app can have a total of 21 custom modals or app actions.

Custom panels

Learn more here.

FieldDescription
Panel name (required)The name of your custom panel. Descriptive, max 30 characters and should be sentence-cased (only capitalize the first word).
Panel descriptionTo showcase the interactive features of your app, your modal’s name and description will appear in the Features section of your Marketplace app listing.

Use the description field to let users know what they can do within this panl.

Optional; max 150 characters.
Iframe URL (required)URL of the web content to be shown within the iframe
– Please ensure your iframe URL uses HTTPS
JWT secretOptional. Defaults to client secret
Panel locations (one required)Choose where the custom panel will be displayed:
– Deals details view
– People details view
– Organizations details view

Each app can have one custom or JSON panel in each location.

Custom floating window

Learn more here.

FieldDescription
Floating window name (required)The name of your custom floating window.

Short and precise, max 30 characters.

The name will appear in the window header and Interactive Features section of your Marketplace app listing.
Floating window description (required)Clearly state what users can do within the window so they know how this feature benefits them (max 150 chars).

It will appear in the Interactive Features section of your Marketplace app listing.

Max 150 characters.
Iframe URL (required)URL of the web content to be shown within the iframe
– Please ensure your iframe URL uses HTTPS
JWT secretOptional. Defaults to client secret
Entry pointsA custom floating window has two entry points:
– Top bar (apps dock) – default
– Phone number and Calls tab – for communication apps

Limited to 1 floating window per app regardless of the entry point.

App settings page

Learn more here.

FieldDescription
TypeChoose how you want your app’s user to access their app settings
– External link
– Custom UI
URL (required) – for external linkAdd the URL that will redirect the user to your app settings page
Iframe URL (required) – for ustom UIURL of the web content to be shown within the iframe
– Please ensure your iframe URL uses HTTPS
JWT Secret – for Custom UIOptional. Defaults toclient secret.

👍

Do install and test your app after you add app extensions to see how it works for your users.



Install and test your draft app


Installing and testing your draft app is an important step before making your private app live. It enables you to ensure everything in your app runs smoothly and identify and address potential issues early on.

NB: app testing only works for users in your sandbox account and cannot be shared with external users.

To install and test your app, click the “Install and test” notification above your app’s name or the “Install & test” option from the three-dot menu.

Developer Hub > private app - install & test

You can also click the green “Install & test” button at the bottom left of the OAuth & access scopes and App extensions tabs.

Developer Hub > private app - install & test from the OAuth & access scopes tab

You will then be brought to the OAuth confirmation dialog where you can allow and install your app to begin testing it.



How to share your private app


There are two steps to sharing your private app with any user/company in Pipedrive:

  1. Make your private app live
  2. Get your installation link

Make your private app live

You have to make your private app live before you can share it. You can do this by clicking the “Change to live” button in the app registration form or the “Change to live” option in the three-dot menu next to your private app’s name.

As we will validate your callback URL when you click “Change to live”, please ensure your OAuth callback URL is a functioning one.

Note that live private apps cannot be reverted to draft status. Any changes you make to your live private app will be immediately available for all users once you click ‘Save’.

Change to live – app registration form

For new private apps

Developer Hub > private app - new app "change to live"

After you fill in your app name and callback URL in the Basic info tab and click “Save”, you will be brought to the OAuth & access scopes with the “Change to live” button enabled. Once the “Change to live” button is enabled, you can make your private app live anytime by clicking on it in any tab.

For draft private apps

Developer Hub > private app - draft app "change to live"

The “Change to live” button will be enabled once you open your draft private app, as you’ve previously filled in and saved your app name and callback URL. You can make your private app live anytime by clicking “Change to live” in any tab of the app registration form.

Change to live – three-dot menu

Private app - three-dot menu

When you click on the three-dot menu next to your private app’s name, you will find the “Change to live” option. Clicking on this will take you to the Basic info tab of your private app, where you must click “Change to live” again to share your app.

Get your installation link

Once your private app is live, you can share it via its installation link. The installation link can be found in the three-dot menu next to your private app’s name in your Developer Hub dashboard.

Developer Hub > private app - share install link

You can also find the installation link through the “Share app” button at the bottom left of your app’s OAuth & access scopes tab.

Developer Hub > private app - share install link from OAuth & access scopes tab

App status


Developer Hub - apps list

Private apps can have two statuses:

App statusDescription
App status - draftYour app is in a draft state. It can be shared with users in the same Pipedrive company.
App status - draftYour app is live and can be shared with any company in Pipedrive via its direct, unlisted installation link.