Frequently Asked Questions

What is the best way to get started?

Fork the HelloPipefy sample app, deploy it to any static host, and register it in your developer settings. It already wires up a card tab, a pipe view, pipe buttons, card buttons, a modal and a sidebar, so you can delete what you don't need rather than build from nothing.

Introduction walks through the whole flow, and Sample Apps covers what's in the sample.

What do I need to do to let Pipefy access my App?

Your application needs to accept CORS requests from https://app.pipefy.com. You can find more info about CORS here: https://enable-cors.org

Your app also runs inside an iframe, so your server must not send headers that block framing:

• X-Frame-Options: DENY or SAMEORIGIN prevents Pipefy from rendering your app at all. Remove it, or set it to allow app.pipefy.com.
• If you use Content-Security-Policy, its frame-ancestors directive must include https://app.pipefy.com.

Everything — the manifest and every asset it references — must be served over HTTPS.

Is the Apps framework still supported?

Yes. The Client SDK is actively maintained and served from https://platform.staticpipefy.com/pipefy-app.js. These docs are kept in step with it.

A few older entries are being cleaned up as we go, and where a function is unreliable we say so on its page rather than leaving it undocumented — see the warnings on p.openCard() and p.render().

Why doesn't my .catch() ever fire?

Because the functions you are most likely to call first swallow their own failures. p.query() and p.mutation() catch everything internally and return the failure as errors on a resolved result. p.card(), p.pipe() and p.fields() log the error to the console and resolve to null.

For those five, error handling has to inspect the resolved value rather than rely on a rejection.

Everything else does reject normally — p.get(), p.set(), p.attach(), p.detach(), p.getAuthToken() and p.oAuthAuthorize() among them — so keep a real .catch() on those. When in doubt, attach one anyway: a .catch() that never fires costs nothing, while a missing one turns a failure into a silently broken app.

Do I need to be an admin?

To register an app, yes — app registration lives in organization settings. Ask an admin of your organization to add it once; after that you can iterate on your code freely, because Pipefy re-fetches your manifest on load.

To experiment on your own, create a free organization where you are the admin. Free and paid organizations can both run apps.

Why does my app throw an error when I open its URL directly?

Because Pipefy adds an appID query parameter when it builds your iframe, and the SDK needs it:

PipefyApp: no "appID" query parameter found on this page. This app must be opened from within Pipefy, not by navigating to the app URL directly.

Apps can only run inside Pipefy. Register your app against your development URL and open it from within the product. See Client SDK overview.

Why does nothing happen when I call a PipefyApp function?

Most likely you're calling it on a surface where it isn't available. PipefyApp.onCardDrop() only works in a sidebar, PipefyApp.registerListener() only in a pipe view, PipefyApp.initCall() only on your init_url page.

Where each function works has the full table.

Why is my card tab or pipe view blank?

Both must call PipefyApp.render() once the page has loaded. Pipefy waits for that signal before revealing your content — a card tab that never sends it doesn't display, and a pipe view that never sends it redirects the user back to the Kanban board.

Can my app read data outside the current card and pipe?

Yes. p.query() and p.mutation() give you the full Pipefy GraphQL API, running with the permissions of whoever is using the app. The context functions are shortcuts for the common case; anything else goes through GraphQL.

Where can I store an API token for a third-party service?

Use p.set() with private visibility, which scopes the value to a single user. Never store a token as public — every user who can reach that card, pipe or organization could read it through your app.

Where do I get help or report a bug?

• Post in the Pipefy Community for questions and app ideas.
• To submit an app for review, or to reach the apps team, use the app submission form. See Publishing your App.