Build the next big thing for process and workflows

Welcome to the Pipefy Developer hub. You'll find comprehensive guides and documentation to help you start working with pipefy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Suggest Edits

What is GraphQL?

 

The GraphQL data query language is:

  • A specification. The spec determines the validity of the schema on the API server. The schema determines the validity of client calls.

  • Strongly typed. The schema defines an API's type system and all object relationships.

  • Introspective. A client can query the schema for details about the schema.

  • Hierarchical. The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip.

  • An application layer. GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.

It allows for reading and writing through queries and mutations (see GraphQL documentation).

Suggest Edits

Authentication

 

For authentication against Pipefy GraphQL endpoints, you will need an OAuth2 Bearer token. To get one:

  • Goto https://app.pipefy.com/tokens
  • Click on 'Generate new token'
  • Give the token a description
  • Click 'Save'
  • Reference the token as you need when authenticating against Pipefy
 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.pipefy.com/graphql
curl --request POST \
  --url https://api.pipefy.com/graphql \
  --header 'authorization: Authorization' \
  --header 'content-type: Content-Type'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.pipefy.com/graphql',
  headers:
   { 'content-type': 'Content-Type',
     authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.pipefy.com/graphql")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'
request["content-type"] = 'Content-Type'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.pipefy.com/graphql");
xhr.setRequestHeader("authorization", "Authorization");
xhr.setRequestHeader("content-type", "Content-Type");

xhr.send(data);
import requests

url = "https://api.pipefy.com/graphql"

headers = {
    'authorization': "Authorization",
    'content-type': "Content-Type"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "data": {
    "me": [
      {
        "name": "Your Name"
      }
    ]
  }
}

Body Params

query
string
required

{ me { name } }

Headers

Authorization
string
required

Bearer YOUR_TOKEN

Content-Type
string
required

application/json

 

This example allows you to interact with the /queries endpoint. For more information, see the documentation.

Suggest Edits

Importing

Create cards or records from a xlsx spreadsheet.

 

If you have a spreadsheet with important information and wish to create cards or records with that data, it is possible with our API. Each line of the sheet will be converted to a card/record.

This mutation copy the data from your sheet and creates multiple cards in a pipe or records in a database table.

Permission

You MUST be the pipe or table Admin!

Spreadsheet

Make sure the sheet is Public!

To send the information to Pipefy, the XSLX's URL file must be public.

How to set up the sheet?

The column represent a field on Pipefy and the line represent a card/record. Example:

First line

We ignore the first line of the sheet, so use it as a place to put the title of each column.

Short Text field
Email field
Phone field
Short Text field
Long Text field

Card/Record #1

email1@email.com

+1 202 555-0123

shot text from card/record #1

long text from card/record #1

Card/Record #2

email2@email.com

+1 202 555-4567

shot text from card/record #2

long text from card/record #2

Card/Record #3

email3@email.com

+1 202 555-8901

shot text from card/record #3

long text from card/record #3

How should I configure the information of each column regarding the field type?

The information sent to pipefy must follow a pattern. The content should match exactly the fields configuration on Pipefy!

Field
Detail

Assignee

The users' emails or the users' names separated by commas and formatted as Plain Text.

Attachment

Not supported.

Vertical/Horizontal Checklist

The text of the checklist options separated by commas and formatted as Plain Text.

CPF

Eleven numbers following the pattern 000.000.000-00 formatted as Plain Text.

CNPJ

Fourteen numbers following the pattern 000.000.00/0000-00 formatted as Plain Text.

Date

The value formatted as a date.

Date Time and Due Date

The value formatted as a Date time.

Currency

The value formatted as Currency.

Label Select

The text of the labels' names separated by commas and formatted as Plain Text.

Email

The email formatted as Plain Text.

Number

The number formatted as Plain Text.

Short/Long Text

The text formatted as Plain Text.

Vertical/Horizontal Radio

The text of the selected option formatted as Plain Text.

Phone

Numbers in the format of phone numbers of the country you want. Brazil: + 55 41 1234-5678.
(use a single quotation mark before the plus sign)

Statement

Not supported.

Select

The text of the selected option formatted as Plain Text.

Time

The value formatted as Time.

ID

Not supported.

Connection Field

The card's ID or record's ID formatted as Plain Text.

Suggest Edits

Cards Importer

Mutation to create multiple cards in a pipe from a xlsx spreadsheet.

 

In the tab cardsImporter (bellow) you can see an example mutation. Once you change the query to your variables, send it to https://api.pipefy.com/graphql and cards will be created with the information of your spreadsheet.
In the tab Structure you can have a better view of the query and you can use this format in our IDE: pipefy.com/graphiql

{
	"query": "mutation { cardsImporter(input: {pipeId: \"219739\", url: \"https://docs.google.com/spreadsheets/d/13sohSO0eGjgZYqQSFyp0LUFwZhktiU9t3BX6Sgnb_yk/export?format=xlsx\", assigneesColumn: \"a\", labelsColumn: \"b\", dueDateColumn: \"c\", currentPhaseColumn: \"d\", fieldValuesColumns: [{column: \"e\", fieldId: \"company_name\"}, {column: \"f\", fieldId: \"contact_email\"}, {column: \"g\", fieldId: \"deal_value\"}]}) { cardsImportation { id } } }"
}
{
	mutation { 
    cardsImporter(
      input: {
        pipeId: "219739",
        url: "https://docs.google.com/spreadsheets/d/13sohSO0eGjgZYqQSFyp0LUFwZhktiU9t3BX6Sgnb_yk/export?format=xlsx",
        assigneesColumn: "a",
        labelsColumn: "b",
        dueDateColumn: "c",
        currentPhaseColumn: "d",
        fieldValuesColumns: [
          {column: "e", fieldId: "company_name"},
          {column: "f", fieldId: "contact_email"}, 
          {column: "g", fieldId: "deal_value"}
        ]
      }) { 
      cardsImportation { 
        id 
      } 
    } 
  }
}
Input fields
Description
Details

pipeId (required)

Represents the pipe ID.

You can find the pipe ID in the URL of the pipe.

url (required)

Represents the spreadsheet URL.

Sheet file must be public.

assigneesColumn (optional)

Represents column's letter or number where the assignee are represented.

In the sheet, the cell should contain the user's full name or the user's email. Each assignee must be separated by commas.

labelsColumn (optional)

Represents column's letter or number where the labels are represented.

In the sheet, the cell should contain the label's title. Each label must be separated by commas.

dueDateColumn (optional)

Represents column's letter or number where the due date is represented.

In the sheet, this column must be formatted as date time.

currentPhaseColumn (optional)

Represents column's letter or number where the current phase is represented.

In the sheet, the cell should contain the phase's name. Use this field if you need to create a card in different phase. If not supplied, the cards will be created in the first phase.

fieldValuesColumns (optional)

Represents column's letter or number where the field's value are represented and the field ID where it should be sent to.

To get the fields IDs of a pipe, you can use this query:

{ "query": "query { pipe(id: your_pipe_id) { table_fields { id } } } " }

URL

If you are using google spreadsheet, change the end of the URL from /edit#gid=1144534632 to /export?format=xlsx.

Response

After sending the query to Pipefy, you will recieve a response in your email when the importation proccess its done!

Case
Details

Success

In case of success, an email will be sent to let you know the pipe and how many cards were created.

Partially Imported

In this case, not all cards were created. In the email, will be attached a file with the inconsistent lines and the details about the errors (in the last column). Update the lines and use this file to send another mutation to create the remaining cards.

Error 1

Selected fields couldn’t be found. Maybe you type the wrong column position or field ID.

Error 2

File format was invalid. Spreadsheet is not Public or the file is not .xlsx format.

Error 3

File format was invalid. Spreadsheet is not Public, the file is not .xlsx format or the cell input was not in the demanded format (in this documentation you can find how you should
configure the information of each column regarding the field type.)

Suggest Edits

Records Importer

Mutation to create multiple records in a database table from a xlsx spreadsheet.

 

In the tab recordsImporter (bellow) you can see an example mutation. Once you change the query to your variables, send it to https://api.pipefy.com/graphql and records will be created with the information of your spreadsheet.
In the tab Structure you can have a better view of the query and you can use this format in our IDE: pipefy.com/graphiql

{
	"query": "mutation { recordsImporter(input: {tableId: \"p0A_JWST\", url: \"https://docs.google.com/spreadsheets/d/13sohSO0eGjgZYqQSFyp0LUFwZhktiU9t3BX6Sgnb_yk/export?format=xlsx\", statusColumn: \"d\", fieldValuesColumns: [{column: \"e\", fieldId: \"company_name\"}, {column: \"f\", fieldId: \"contact_email\"}]}) { recordsImportation { id } } }"
}
mutation { 
  recordsImporter(input: {
    tableId: "p0A_JWST", 
    url: "https://docs.google.com/spreadsheets/d/13sohSO0eGjgZYqQSFyp0LUFwZhktiU9t3BX6Sgnb_yk/export?format=xlsx",
    statusColumn: "d",
    fieldValuesColumns: [
      {column: "e", fieldId: "company_name"},
      {column: "f", fieldId: "contact_email"}
    ]}) 
  { 
    recordsImportation { 
      id 
    } 
  } 
}

tableId (required)

Represents the table ID.

You can find the table ID in the URL of the table.

url (required)

Represents the spreadsheet URL.

Sheet file must be public.

statusColumn (optional)

Represents column's letter or number where the status phase is represented.

In the sheet, the cell should contain the status of the record.

fieldValuesColumns (optional)

Represents column's letter or number where the field's value are represented and the field ID where it should be sent to.

To get the fields IDs of a table, you can use this query:

{ "query": "query { table(id: your_table_id) { table_fields { id } } }" }

URL

If you are using google spreadsheet, change the end of the URL from /edit#gid=1144534632 to /export?format=xlsx

Response

After sending the query to Pipefy, you will recieve a response in your email when the importation proccess its done!

Success

In case of success, an email will be sent to let you know the pipe and how many records were created.

Partially Imported

In this case, not all records were created. In the email, will be attached a file with the inconsistent lines and the details about the errors (in the last column). Update the lines and use this file to send another mutation to create the remaining records.

Error 1

Selected fields couldn’t be found. Maybe you type the wrong column position or field ID.

Error 2

File format was invalid. Spreadsheet is not Public or the file is not .xlsx format.

Error 3

File format was invalid. Spreadsheet is not Public, the file is not .xlsx format or the cell input was not in the demanded format (in this documentation you can find how you should
configure the information of each column regarding the field type.)

Suggest Edits

Integrations

 

Integrations

Suggest Edits

Sample payloads

 

card.move

{
  "data": {
    "action": "card.move",
    "from": {
      "id": 4519174,
      "name": "Prospect"
    },
    "to": {
      "id": 4519175,
      "name": "Discovery"
    },
    "moved_by": {
      "id": 205,
      "name": "Raphael Costa",
      "username": "raphael",
      "email": "raphael@pipefy.com",
      "avatar_url": "https://gravatar.com/avatar/e79c43564cc0e23ae4899ec0ef5e0fe4.png?s=128&d=https://d39k3r5odlh0df.cloudfront.net/images/user-avatar-default.png"
    },
    "card": {
      "id": 16561887,
      "title": "Acme Corporation",
      "pipe_id": "G_CtcRV_"
    }
  }
}

card.done

{
  "data": {
    "action": "card.done",
    "done_by": {
      "id": 205,
      "name": "Raphael Costa",
      "username": "raphael",
      "email": "raphael@pipefy.com",
      "avatar_url": "https://gravatar.com/avatar/e79c43564cc0e23ae4899ec0ef5e0fe4.png?s=128&d=https://d39k3r5odlh0df.cloudfront.net/images/user-avatar-default.png"
    },
    "card": {
      "id": 16561890,
      "pipe_id": "G_CtcRV_"
    }
  }
}

card.field_update

{
  "data": {
    "action": "card.field_update",
    "field": {
      "id": "first_contact",
      "label": "First contact",
      "internal_id": 9002840
    },
    "new_value": "2018-12-03",
    "card": {
      "id": 16561887,
      "pipe_id": "G_CtcRV_"
    }
  }
}

card.create

{
  "data": {
    "action": "card.create",
    "card": {
      "id": 16562010,
      "pipe_id": "G_CtcRV_"
    }
  }
}