What is Pitchly?

Pitchly is a data-driven work platform for business. At Pitchly's core is a human-friendly database. Apps can be plugged into Pitchly databases to do specific work tasks, like creating documents and pitches, online forms, and visualizations automatically from your data.

Pitchly's data-driven approach is unique and fundamentally different from other work platforms in that no work is repetitive. Documents, for example, can be created once and stay automatically up-to-date whenever your business data changes. It's a fundamentally different way of working.

Visit our website to learn more.

Who uses Pitchly?

Pitchly is popular among enterprise companies. Our clients include law firms, accounting firms, professional service firms, M&A advisors, corporate finance companies, banks, real estate, property management, construction firms, and many others. In many cases, clients have made Pitchly their "single source of truth" for all their company data and assets.

How can I develop on Pitchly?

There are two ways you can develop on Pitchly.

1. Our Client API allows you to interact with your own Pitchly account programmatically

2. Our App SDK allows you to build installable apps for yourself or others on the Pitchly platform to help do work

In order to get started, you will need App credentials that we can provide you. Contact us to receive these credentials.

The Pitchly Client API is meant for situations where you want to interact with your own Pitchly account programmatically, often to integrate with other systems.

We use GraphQL for our core API requests, but fret not - GraphQL is backwards compatible with REST. In the examples ahead, we will share the equivalent REST API calls for easy translation.

In the following sections, we will show you how to:

1. Generate API Keys to authorize requests to Pitchly's API

2. Make calls to Pitchly's API endpoints (with REST or GraphQL)

API Keys are token credentials that you will pass with every API request to prove who your application is, and to authorize its access to your Pitchly account's data.

To generate API Keys, all you need is a Pitchly account with admin access. These keys only need to be generated once and do not expire, however, you can rotate keys as you wish.

How to generate API Keys

First, go to your Company settings located in the Organization dropdown in the top right of the screen. Then click on API keys.

When the API Keys window appears, click Create new key set.

Give this integration a brief name, description, and the maximum permissions this integration should have with Pitchly. If you're only wanting to read data from a database to display on a website but aren't accepting data into the database via that website, for example, you would select only readData. When you're finished, click Create.

Right after you click Create, you will be shown a new App ID and App Secret. You will include at minimum the App Secret in all of your API calls.

Next: How to make API calls

Now that you have your App ID and App Secret, you can begin using them to make API calls! If you need to change the permissions or details of a Key Set, you can always return to these screens to modify an existing Key Set. You can also rotate your App Secret as often as you'd like.

Endpoints

dataRowsChanged

Listens to changes to rows in a database. Use in combination with a data query.

subscription dataRowsChanged($secretKey: String!, $databaseId: ID!) {
  dataRowsChanged(secretKey: $secretKey, databaseId: $databaseId) {
    _id
    cols {
      fieldId
      value
    }
  }
}

Variables:

{
  "secretKey": <SECRET_KEY>,
  "databaseId": <DATABASE_ID>
}

Initiating a subscription does not return data. Instead, it just starts listening for new data as it comes in. In this case, whenever rows change in a database, the new data for each changed row will be received instantly. The data returned by this subscription is identical to the data returned by the data query.

If you're using a GraphQL client, like Apollo, you can use this subscription in combination with the data query to create an always-up-to-date cache of data. See a code example.

databaseUpdated

Listens to changes to a database, including database fields. Use in combination with a database query.

subscription databaseUpdated($secretKey: String!, $id: ID!) {
  databaseUpdated(secretKey: $secretKey, id: $id) {
    _id
    name
    fields {
      _id
      name
      type
      primary
      required
      restrict
      database
    }
  }
}

Variables:

{
  "secretKey": <SECRET_KEY>,
  "id": <DATABASE_ID>
}

Triggers when a database is updated. This includes changes to information about the database itself or any of its fields. The data returned by this subscription is identical to the data returned by the database query.

See how to use this subscription in combination with the database query using Apollo.

While API Keys are a quick and convenient way to make API requests from your third-party application in a machine-to-machine setting, sometimes you may want to authorize each user individually with a unique access token for each. This allows you to get the user context for specific users and require each user to authenticate with Pitchly before using Pitchly data in your application.

To get user-specific access tokens, you can use Pitchly's OAuth authorization code flow. OAuth is a global authorization standard for sharing data from one application to another. You can find an example of how this flow generally works here.

Below is a description of each step in the OAuth authorization code flow (and refresh token flow).

Initialize OAuth flow

This endpoint is triggered by the user opening this page in their browser with the following query parameters in the URL. The user will be presented with the option to authorize your app access to the user's Pitchly account. If approved, your app will receive an authorization code in return. In the next request, you will exchange that code for an actual access token via a server-side call.

Initialize OAuth flow

GET https://v2.pitchly.net/oauth/authorize

Redirect the user to this URL with the following query parameters to start the OAuth flow. Once the user approves access (or if they have already approved), the user will be redirected to the appropriate redirect URI (specified in the app's configuration) with an authorization code that can be exchanged for an access token.

Query Parameters

https://example-app.com/cb?code=Yzk5ZDczMzRlNDEwY&state=5ca75bd30

Exchange auth code for access token

Call this from your application's server side to exchange the authorization code returned by the previous request for an access token. You can then provide this access token in GraphQL API requests in the accessToken variable. When using a user-specific access token, replace all instances of secretKey in your GraphQL requests with accessToken, and provide your access token within it.

Exchange authorization code for access token

POST https://v2.pitchly.net/api/oauth/access_token

Call this on your backend to exchange the authorization code acquired from the first step for an access token, which you can use to make GraphQL API requests.

Headers

Request Body

{
    access_token: "gRSgnFX1AhHTsCmkmE-SpRA3ViNYb8XN2-Kys1yfNZA",
    expires_in: 7200, // seconds until access token expiration
    refresh_token: "_Wv-VoCpm2rq3VsWnAMR3jZzkk-VimqLKEDiUujzjEn"
}

Refresh access token (optional)

This step is optional and only applies if you wish to continue making API calls to Pitchly while the user is offline, or if you would like to continue making API requests without sending the user back through the OAuth flow after the token expires in 2 hours.

Whenever you receive a token-invalid error from a GraphQL API request, call this endpoint to get a new access token and retry the request. You will need a refresh token either from the previous request or from the result following this request.

Refresh access token

POST https://v2.pitchly.net/api/oauth/access_token

Call this to exchange a refresh token for a new access token and refresh token.

Headers

Request Body

{
    access_token: "WE5vGFit3tkB1iU131_RPmQp6Z2OwR17jeyn2gfp3mn",
    expires_in: 7200, // seconds until access token expiration
    refresh_token: "bkdy8v6A3L_NetN_V5G3jYFNax4X9ljYVL-prGoz822"
}

Serverless flow

If you wish to use OAuth to acquire user-specific access tokens but don't have a sever side to exchange an authorization code for an access token, you can alternatively use the implicit flow to get an access token directly instead of an authorization code.

To initiate the implicit flow, send the user to this endpoint:

Initialize implicit OAuth flow

GET https://v2.pitchly.net/oauth/authorize

Redirect the user to this URL with the following query parameters to start the OAuth flow. Once the user approves access (or if they have already approved), the user will be redirected to the appropriate redirect URI (specified in the app's configuration) with an access token.

Query Parameters

https://example-app.com/cb?token_type=Bearer&access_token=_t9MkUKCnQxgYg1LsIrQuNT-TkKVY2kBCgWLPmGnF7D&expires_in=7200&state=5ca75bd30

In Pitchly, Apps are used to perform specific work tasks using data. You can either make an App for yourself or share it with others, in which case you will enable other companies on the Pitchly platform to be more successful and efficient using your App.

In general, Apps are installed on an organization in Pitchly and work with data inside the databases of that organization, up to the permissions allowed for that App.

The process to create an App on Pitchly is pretty straightforward. There are three main steps:

1. Register your App on Pitchly

2. Generate an access token over our REST API

3. Get resources, like data, from the user's account over our GraphQL API

If you are building a web app inside Pitchly, you can safely skip step #2 because we handle access token generation and renewal for you automatically via our JavaScript SDK. We will try to make the remaining steps as easy as possible.

The different kinds of Apps

There are conceptually three different kinds of Apps you can build in Pitchly, depending on where you want your App to live. The three are:

1. Inside Apps

2. Outside Apps (coming soon)

3. Hybrid Apps (coming soon)

Inside Apps "live" inside the Pitchly platform and are shown to the user via an iframe, side by side with their database, but your App is hosted elsewhere.

Outside Apps live primarily on your own website or web page but connect with users' Pitchly accounts via a Pitchly Connect button.

Hybrid Apps are simply a combination of both strategies, which gives you the ability to both enhance your existing web app or product with Pitchly support and have your App available at a moment's notice to users working inside their Pitchly account.

Registering your App

To create an App on Pitchly, you must first register your App with the Pitchly platform, so we know things like your App's name and where to look for your App. This will also generate a unique App ID and App Secret, which you can then use to communicate with Pitchly's APIs.

What is GraphQL?

GraphQL is a fairly new API framework that replaces the more common REST API. It was developed by Facebook to better handle data distribution at scale. We chose to use GraphQL for several of our own reasons:

1. Built-in subscription support enables Apps to get data in real time, a key design principle in Pitchly.

2. You can choose exactly the data you want to receive, spanning several possible data sets, in total fewer network requests.

3. It uses a single endpoint, creating less breaking changes, allowing for incremental adoptability and better version control.

4. Plays well with modern frontend frameworks, like React, Vue.js, and Meteor.

If you are developing your App using a modern web application framework, we recommend using Apollo Client to work with our GraphQL API.

If you are not developing your App using a modern web application framework, you can still make calls to our GraphQL API over REST. This is because, at its core, GraphQL is really an abstraction over HTTP calls. It is a structured query language that gets sent over an HTTP request, just like REST, except the query is put inside the body of the request. Without a framework, like Apollo Client, however, you won't have the added perks of a client-side cache or automatic subscription updates.

Using Apollo Client

Apollo Client is compatible with several major frontend web frameworks, including React, Vue.js, Meteor, Angular, Ember, as well as native mobile on iOS and Android. You can get real snazzy with it, but we're just going to show a dirt basic example to start. The examples below are compatible with any frontend JavaScript framework you choose.

Basic query

npm install --save apollo-client graphql-tag graphql apollo-link-http apollo-cache-inmemory

import { ApolloClient } from 'apollo-client';
import gql from 'graphql-tag';
import { HttpLink } from 'apollo-link-http';
import { InMemoryCache } from 'apollo-cache-inmemory';

const client = new ApolloClient({
  link: new HttpLink({
    uri: 'https://v2.pitchly.net/graphql'
  }),
  cache: new InMemoryCache()
});

Let's get information about the current database:

client.query({
  query: gql`
    query database($id: ID!, $accessToken: String!) {
      database(id: $id, accessToken: $accessToken) {
        _id
        organizationId
        name
        description
        color
        fields {
          _id
          name
          description
          type
          primary
          required
          restrict
          database
        }
      }
    }
  `,
  variables: {
    id: pitchly.getDatabaseId(), // gets the current database ID
    accessToken: "MY-ACCESS-TOKEN"
  }
})
.then(result => console.log("Result:", result.data))
.catch(error => console.log("Error:", error.graphQLErrors[0].data));

We will get back several properties of the database, including its name, description, color, and all of its fields, in the form of a Promise.

This is great for a one-time query, but it only gives us a snapshot into a particular database on Pitchly in that moment. What if I want to be notified whenever the database changes?

Real-time subscriptions

Subscriptions are a feature of GraphQL that allow you to receive notifications of data changes on Pitchly as soon as they happen, over websockets.

We'll need just a few more NPM packages (we've included the ones above again):

npm install --save apollo-client graphql-tag graphql apollo-link apollo-link-http apollo-link-ws apollo-utilities apollo-cache-inmemory subscriptions-transport-ws

We need to make some changes to the ApolloClient:

import { ApolloClient } from 'apollo-client';
import gql from 'graphql-tag';
import { split } from 'apollo-link';
import { HttpLink } from 'apollo-link-http';
import { WebSocketLink } from 'apollo-link-ws';
import { getMainDefinition } from 'apollo-utilities';
import { InMemoryCache } from 'apollo-cache-inmemory';

const client = new ApolloClient({
  link: split(
    ({ query }) => { // use WebSocket or HTTP, depending on the operation
      const { kind, operation } = getMainDefinition(query);
      return kind === 'OperationDefinition' && operation === 'subscription';
    },
    new WebSocketLink({
      uri: 'wss://v2.pitchly.net/subscriptions',
      options: {
        reconnect: true // automatically reconnect if disconnected
      }
    }),
    new HttpLink({
      uri: 'https://v2.pitchly.net/graphql'
    })
  ),
  cache: new InMemoryCache()
});

Next, we will re-use the same query we initially had, but this time, we want to watch it change as new data from the subscription comes in. This will require two calls: one to the query and one to a subscription.

// begin the query

const queryObserver = client.watchQuery({
  query: gql`
    query database($id: ID!, $accessToken: String!) {
      database(id: $id, accessToken: $accessToken) {
        _id
        organizationId
        name
        description
        color
        fields {
          _id
          name
          description
          type
          primary
          required
          restrict
          database
        }
      }
    }
  `,
  variables: {
    id: pitchly.getDatabaseId(), // gets the current database ID
    accessToken: "MY-ACCESS-TOKEN"
  }
});

// declare the GraphQL subscription

const subscriptionObserver = client.subscribe({
  query: gql`
    subscription databaseUpdated($id: ID!, $accessToken: String!) {
      databaseUpdated(id: $id, accessToken: $accessToken) {
        _id
        organizationId
        name
        description
        color
        fields {
          _id
          name
          description
          type
          primary
          required
          restrict
          database
        }
      }
    }
  `,
  variables: {
    id: pitchly.getDatabaseId(), // gets the current database ID
    accessToken: "MY-ACCESS-TOKEN"
  }
});

// get updates from the query as subscription updates come in

const querySub = queryObserver.subscribe({
  // next: ({ errors, data, loading, networkStatus, stale }) => {
  next: ({ loading, data }) => {
    if (!loading) {
      console.log(data); // runs whenever new data has come in
    }
  }
});

// this is necessary to listen to subscription updates

const subscriptionSub = subscriptionObserver.subscribe(); // seems counterintuitive, but subscribe returns an Observable to which we must also subscribe



// make sure to unsubscribe from all Observables when you no longer need the data

querySub.unsubscribe();
subscriptionSub.unsubscribe();

There are understandably a few confusing things here, so let's break it down.

There are two main differences between a query and a subscription:

• A query retrieves a particular set of data.

• A subscription is just a listener. It does not request any data when first connected, but only opens up a connection to get new data.

To make things even more interesting, there are also two different types of queries:

• A normal query makes a single request and gets back a single response.

• A watched query acts as a long-term "living" query, capable of long-term tasks like receiving subscription updates, refetches with updated variables, and continuous pagination.

The Apollo Cache

One important thing to know about Apollo is that queries do not hold the data they request in isolation. Under every query, subscription, and mutation is a single global cache that houses all requested data. The cache serves as a single source of truth for all requested API data, regardless of which query requested it.

Subscriptions are able to function because the call to the subscription automatically "pulls down" updates into the Apollo cache when updated data arrives. Every watched query which uses that same data will automatically "pull up" the update from the cache.

Observables

You may have noticed a lot of subscribes floating around. Well, they're not all related to subscriptions.

An unfortunate choice of the makers of Apollo was to use the same method name for both creating GraphQL subscriptions and subscribing to their results from the Apollo cache. The first is a client-server intraction, while the latter is a client-client cache interaction.

Both client.watchQuery and client.subscribe methods return an Observable, which represents that query or subscription and the data it uses in the cache. When something changes to the data that query or subscription represents, you can capture that update by subscribing to its Observable. For subscriptions, subscribing to the Observable is necessary to tell Apollo you are interested in that data.

In addition to querying data, you can also perform actions against the Observable, such as refetching with different variables, checking load status, and paginating.

Mutations

Mutations are used whenever you want to "post" data to Pitchly, such as when you want to insert a row to a database. Mutations are very similar to queries in that they run once and return a Promise, but they also have some additional options.

client.mutate({
  mutation: gql`
    mutation insertRow($databaseId: ID!, $row: DataRowInput!, $accessToken: String!) {
      insertRow(databaseId: $databaseId, row: $row, accessToken: $accessToken) {
        _id
        cols {
          fieldId
          value
        }
      }
    }
  `,
  variables: {
    databaseId: pitchly.getDatabaseId(), // gets the current database ID
    row: {
      cols: [
        {
          fieldId: nameFieldId,
          value: {
            val: "Foo Bar"
          }
        },
        {
          fieldId: dateFieldId,
          value: {
            val: "2018-1-23" //dates can take a JS Date object or a date string
          }
        },
        {
          fieldId: otherFieldId,
          value: {
            val: null //represents "empty" value
          }
        }
      ]
    },
    accessToken: "MY-ACCESS-TOKEN"
  }
})
.then(result => console.log("Result:", result.data))
.catch(error => console.log("Error:", error.graphQLErrors[0].data));

This example will return the new row's _id and cols.

Mutations can do some unique things, like Optimistic UI, to keep latency at a minimum. But if you are using subscriptions, all of your queries using the affected data will be updated at near real time automatically after your mutation affects the relevant data, resulting in a positive UI loop. This makes for a very quick and seamless real-time experience for not only the user updating the data, but also for all other users viewing the same data. And it ensures that no user ever acts on data that is out of date.

More tips & tricks

Detecting load status

If you would like to get the loading status of a query with Apollo, perhaps to show a loading indicator, you can use the next function in combination with notifyOnNetworkStatusChange: true.

const observer = client.watchQuery({
  ...,
  notifyOnNetworkStatusChange: true // add this to your query to trigger "next" when loading
});

const sub = observer.subscribe({
  // next: ({ errors, data, loading, networkStatus, stale }) => {
  next: ({ loading }) => {
    console.log(loading ? "Loading" : "Done Loading");
  }
});

// call this when you're no longer interested in the data
sub.unsubscribe();

In addition to detecting the load status of a watched query, next can also be used to capture subscription updates, depending on your use case. Learn more.

Re-run a query with new variables

You can forcibly re-run a query by using refetch.

const observer = client.watchQuery({...});

observer.refetch({
  // new variables...
  id: pitchly.getDatabaseId(), // gets the current database ID
  accessToken: "NEW-ACCESS-TOKEN"
});

This will make a new network request to Pitchly using the new variables for the query. The variables object that is passed to refetch is completely optional, and refetch can be called alone to simply re-run the query with the existing variables intact.

Common use cases for refetch are:

• You are not using subscriptions and would like to manually re-query on an event or interval (if you are refetching on an interval, consider using pollInterval instead.)

• The access token, or another parameter, has changed and you need to update it

• You need to re-capture a set of data for which there is no subscription

Change caching behavior

Caching in Apollo can be useful when dealing with repetitive queries against the same data. But sometimes it can make things difficult to debug, or Apollo may think you have all the data for an object because it already exists in the cache, when really you don't have all the data you need. If you're making a request for the same object but can't see the new data come in past the data you previously queried for, caching may be your issue.

There are several solutions, but a simple one is to change the caching behavior of a query by changing its fetchPolicy. Just add it as an additional parameter to the query.

client.query({
  query: gql`...`,
  variables: {...},
  fetchPolicy: "network-only",
})
.then(result => console.log("Result:", result.data))
.catch(error => console.log("Error:", error.graphQLErrors[0].data));

Possible options are:

• cache-first

• cache-and-network

• network-only

• cache-only

• no-cache

• standby

Read about each type of fetchPolicy here.

fetchPolicy can be applied to watchQuery, query, mutate, and subscribe operations.

Pagination

Pagination can be achieved without much manual effort using Apollo's fetchMore function. Call fetchMore the moment you would like to get more results.

const observer = client.watchQuery({...});

observer.fetchMore({
  variables: {
    skip: observer.currentResult().data.data.length // or something like this
  },
  updateQuery: (prev, { fetchMoreResult }) => {
    if (!fetchMoreResult) return prev;
    return Object.assign({}, prev, {
      data: [...prev.data, ...fetchMoreResult.data]
    });
  }
});

Merging subscription updates

Subscriptions in Apollo are, by default, pretty smart. In most cases, they will merge new data into Apollo's cache for you, giving all your existing queries access to the new data automatically. But there are a few cases where this won't work:

• The data coming from the subscription doesn't match the format of the data in the cache

• A range of data was queried and a new row of data was created. We've been told about the new row, but we don't know where it is in relation to other rows (does it fit inside the range?)

• Something new was created and we want to add it to our cache, but we didn't have a query for it previously because it didn't exist yet!

In these cases, either one of these two methods can help to update existing queries with new data:

1. refetch

2. subscribeToMore

refetch

Using refetch simply runs the entire query again whenever we get notice from the subscription that something has changed. This method has pros and cons.

const queryObserver = client.watchQuery({...});
const subscriptionObserver = client.subscribe({...});

const subscriptionSub = subscriptionObserver.subscribe({
  next: ({ data }) => {
    if (data && data.dataRowsChanged) {
      queryObserver.refetch(); // reload the query that's using this data
      // or see the changed data directly at data.dataRowsChanged
    }
  }
});

// call this when you're no longer interested in the data
subscriptionSub.unsubscribe();

subscribeToMore

subscribeToMore is similar to fetchMore for pagination, except it can run multiple times for each update instead of only once, and is triggered by receipt of an update versus when you call it. It, too, has advantages and disadvantages.

Below is a real-world example of code we used in our Documents App to update documents with data in real time while also having infinite scroll through the use of fetchMore. We additionally use Underscore.js and Meteor's client-side Collections here.

const queryObserver = client.watchQuery({...});

queryObserver.subscribeToMore({
  document: gql`
    subscription dataRowsChanged($databaseId: ID!, $accessToken: String!) {
      dataRowsChanged(databaseId: $databaseId, accessToken: $accessToken) {
        _id
        cols {
          fieldId
          value
        }
      }
    }
  `,
  variables: {
    databaseId: pitchly.getDatabaseId(), // gets the current database ID
    accessToken: "MY-ACCESS-TOKEN"
  },
  updateQuery: (prev, { subscriptionData }) => {
    // On subscription update, update the local cache (update and delete only; no insert yet)
    // TODO: We want to catch inserts ideally as well
    if (!subscriptionData.data) return prev;
    const dataRowsChanged = subscriptionData.data.dataRowsChanged;
    const deletedRowIds = _.pluck(_.filter(dataRowsChanged, (row) => !row.cols), "_id");
    const updatedRows = _.filter(dataRowsChanged, (row) => !!row.cols);
    let resultData = prev.data;
    if (deletedRowIds.length > 0) {
      // delete, and remove from selections if selected
      Selections.remove({ _id: { $in: deletedRowIds } });
      resultData = _.reject(resultData, (row) => _.contains(deletedRowIds, row._id));
    }
    if (updatedRows.length > 0) {
      // only update, don't insert because we don't know where it would go
      resultData = _.map(resultData, (row) => {
        const newRow = _.findWhere(updatedRows, { _id: row._id });
        if (newRow) return newRow;
        return row;
      });
    }
    return { data: resultData };
  }
});

Query Batching

Pitchly supports query batching on all GraphQL API calls. Query batching allows multiple queries to be sent in a single request if they are executed very close together, saving valuable load time. This means that if you render several components, for example a navbar, sidebar, and content, and each of those do their own GraphQL query, they will all be sent in one roundtrip. In Apollo, it is very easy to enable query batching.

In your ApolloClient setup, replace the following section of code:

...
new HttpLink({
  uri: 'https://v2.pitchly.net/graphql'
})
...

with:

import { BatchHttpLink } from 'apollo-link-batch-http';

...
new BatchHttpLink({
  uri: 'https://v2.pitchly.net/graphql',
  // batchMax: 10 // max number of items to batch (10 is default)
})
...

Also make sure to install the NPM package:

npm install --save apollo-link-batch-http

See the Apollo Guide for more options around query batching.

References

• Apollo Client: Introduction

• Apollo Client: Client Setup

• Apollo Client: Subscriptions

Whether you're creating an app on Pitchly for your own organization, other organizations, or you're wanting to work with your own organization's data programmatically using Pitchly's Client API, you will be using the same GraphQL endpoints to work with data.

Keep in mind that you can make calls to Pitchly's GraphQL API over REST if you choose, as GraphQL is only a specification, not a library. While tools like Apollo offer tooling to help developers make sophisticated web apps using GraphQL, no libraries or frameworks are required to work with Pitchly's GraphQL API. The only requirement is the ability to make HTTP requests using POST.

For your convenience, we've translated each GraphQL API call example into its REST counterpart so you can choose which technology you would like to use with Pitchly.

Click here for details on Pitchly's API endpoints.

Ground rules

Since Pitchly uses GraphQL for its API, every request is routed to a single URL endpoint.

https://v2.pitchly.net/graphql

Since REST is backwards compatible with GraphQL, if you would rather use REST, you can do so by:

• Sending all requests to the same URL above

• Using the POST method for all requests

• Setting the Content-Type header of the request to application/json

• Putting the REST-equivalent JSON from each example in the Body of the request

Each example provided in this documentation reference will show both a GraphQL version of the request and an equivalent REST version. The result that follows the request will be the same for each.

Authorization

For every request, you will include the App Secret you made in the previous section in the Body of your request as the parameter secretKey. The following sections will demonstrate where to include your secretKey.

Debugging tools

For our fellow developers, we've enabled GraphQL Playground on Pitchly so you can test and debug your API requests without writing any code.

https://v2.pitchly.net/graphql

Request types

At a high level, there are three types of requests you can make with Pitchly's API:

• Queries (for pulling data from Pitchly)

• Mutations (for pushing data to Pitchly)

• Subscriptions (for listening to changes to data in Pitchly)

Pitchly is a powerful platform for data management, collaboration, and workflow building. But in order for it to succeed at all three, it requires a set of common product principles on which not only our platform is built, but all Apps should adhere to as well while providing value to users.

Real-time everywhere

One of the biggest benefits of Pitchly over other software vendors is its real-time nature. We believe with the emergence of web technologies, like WebSockets, there is an opportunity to solve two problems that have been hard to solve for databases as long as they've existed:

• Keeping data in sync across an entire business, making sure no one acts on out-of-date information

• Preventing conflicting information from overwriting data someone else has entered

Making your App function in real time, where it makes sense, contributes to our mission of making business tools easier to use, and as a result, making those businesses more productive because they can trust the data in Pitchly (and your App) is always accurate.

Permissions

Pitchly, as a platform, covers the permissions that organizations can set to restrict who has access to what data in their databases. But it may not cover the permissions you want to give users in your App.

Our Documents App, for example, has a special "design" permission, specific to Documents, that allows Pitchly admins to choose who has the ability to create new document templates. But this permission only exists relative to that App. Other Apps will likely have their own permissions to enforce.

It is on you to examine the users in an organization (which can be done via our GraphQL API) to determine who should be able to do what inside your App. If you want, you can align your permissions with Pitchly user roles, to say for example, "only Pitchly admins should be able to do X." Or you can create your own logic, saving the individual userId with your App-related permission in your own database.

The choice is up to you, but we recommend making sure the users of your App are informed of the permissions they have selected. Controlling who has access to what company data is particularly important, and our clients trust us to do what's right with it.

Interface (UI/UX)

During mobile app development, you are often given standardized UI components with which you can build your app. They give your app a certain look and feel that is consistent with the rest of the operating system, resulting in an overall positive user experience as the user switches between your app and other apps or the home screen.

Web development doesn't really have that standard toolkit by default. Well, it does, but it sucks. Because of this, we have created a standard UI library that includes all the components you might want to use in your App, such as lightboxes, popups, tooltips, toasts, buttons, dropdowns, etc.

We highly recommend you use these components while building Pitchly-facing Apps inside our platform, to ensure users have a consistent and pleasant experience.

Endpoints

databases

Gets all the databases that belong to an organization. If docDbOnly is true, then only databases that have the Documents app installed will be returned.

query databases($secretKey: String!, $organizationId: ID!, $docDbOnly: Boolean) {
  databases(secretKey: $secretKey, organizationId: $organizationId, docDbOnly: $docDbOnly) {
    _id
    name
    fields {
      _id
      name
      type
      primary
      required
      restrict
      database
    }
    filters {
      _id
      name
      filter
    }
    templates {
      path
      name
    }
  }
}

{
  "secretKey": <SECRET_KEY>,
  "organizationId": <ORGANIZATION_ID>,
  "docDbOnly": Boolean
}

{
  "operationName": "databases",
  "variables": {
    "secretKey": <SECRET_KEY>,
    "organizationId": <ORGANIZATION_ID>,
    "docDbOnly": Boolean
  },
  "query": "query databases($secretKey: String!, $organizationId: ID!, $docDbOnly: Boolean) {\n  databases(secretKey: $secretKey, organizationId: $organizationId, docDbOnly: $docDbOnly) {\n    _id\n    name\n    fields {\n      _id\n      name\n      type\n      primary\n      required\n      restrict\n      database\n    }\n  }\n}\n"
}

With GraphQL, you can narrow down the properties you wish to receive in the result, such as only the fields in the tables, or even just the name and _id. filters and templates, however, may require some more explanation.

filters is an array of "Saved Filters" that have been saved in your Pitchly account in the left-hand pane to a database. It returns the name of the filter and the filter object that you can pass directly to the data query to load results matching that filter.

templates is an array of templates that live in the Documents app for this database. The path of the template is a string value containing the stringified path to the template in the directory structure in the Documents app, where each folder is separated by " > ". For example, a template called "Foo" in the folder "Bar" would read Bar > Foo. If the template is at the root directory, it would just read, Foo. The name property simply contains the name of the template, the equivalent of the last name shown in the path.

Example result

Returns an array of databases in the specified organization. Each database has an _id, name, and an array of fields. See the meaning of each field's properties here, and more information about field types.

{
  "data": {
    "databases": [
      {
        "_id": "uJL9XrebupC7eWvM3",
        "name": "Clients",
        "fields": [
          {
            "_id": "xEfek48BRpD3kAksh",
            "name": "Name",
            "type": "string",
            "primary": true,
            "required": null,
            "restrict": null,
            "database": null
          }
        ],
        "filters": [],
        "templates": [
          {
            "name": "(0) CloseDate Logo Counselto Description DealValue",
            "path": "Tombstones > (0) CloseDate Logo Counselto Description DealValue"
          }
        ]
      },
      {
        "_id": "LkfjQ9pq9f48K2vD8",
        "name": "Products",
        "fields": [
          {
            "_id": "ELHqkJAFiyRfzdMsP",
            "name": "Name",
            "type": "string",
            "primary": true,
            "required": null,
            "restrict": null,
            "database": null
          },
          {
            "_id": "MBadxhiHvf78yDpPS",
            "name": "In Stock",
            "type": "boolean",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": null
          }
        ],
        "filters": [],
        "templates": []
      },
      {
        "_id": "Ccx2Fzva28RshjFpr",
        "name": "Orders",
        "fields": [
          {
            "_id": "Nb6uqwKdxh3BFX3De",
            "name": "ID",
            "type": "string",
            "primary": true,
            "required": true,
            "restrict": null,
            "database": null
          },
          {
            "_id": "RyM8SyrYrceRsrLJd",
            "name": "Client",
            "type": "ref",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": "uJL9XrebupC7eWvM3"
          },
          {
            "_id": "g5WPqJugq9o3fQPXH",
            "name": "Products",
            "type": "refMultiple",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": "LkfjQ9pq9f48K2vD8"
          },
          {
            "_id": "Jex4vcwa9HZ4GipXg",
            "name": "Photo",
            "type": "attachment",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": null
          },
          {
            "_id": "pnR2Mnqfjdj9vQG8e",
            "name": "Amount",
            "type": "currency",
            "primary": null,
            "required": true,
            "restrict": null,
            "database": null
          },
          {
            "_id": "2ybyZfu6H6KNfGbBt",
            "name": "Location",
            "type": "enum",
            "primary": null,
            "required": null,
            "restrict": [
              "Houston",
              "Atlanta",
              "Las Vegas",
              "Minneapolis",
              "New York"
            ],
            "database": null
          },
          {
            "_id": "q6iD8LCHSjhJusLSd",
            "name": "Date",
            "type": "date",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": null
          },
          {
            "_id": "JYszfW2jpLeTck8mW",
            "name": "Department",
            "type": "enumTags",
            "primary": null,
            "required": null,
            "restrict": [
              "Electronics",
              "Cosmetics",
              "Cookware",
              "Hardware",
              "Home"
            ],
            "database": null
          },
          {
            "_id": "hMQKzyxRBxK4sGN5M",
            "name": "Quantity",
            "type": "number",
            "primary": null,
            "required": null,
            "restrict": null,
            "database": null
          }
        ],
        "filters": [],
        "templates": []
      }
    ]
  }
}

{
  "errors": [
    {
      "message": "An error has occurred",
      "name": "GQLError",
      "time_thrown": "2019-11-03T20:26:12.651Z",
      "data": {
        "error": "not-authorized",
        "reason": "This app does not have permission to perform this action."
      }
    }
  ],
  "data": null
}

database

Gets information about a specific database, including its fields.

query database($secretKey: String!, $id: ID!) {
  database(secretKey: $secretKey, id: $id) {
    _id
    name
    fields {
      _id
      name
      type
      primary
      required
      restrict
      database
    }
    filters {
      _id
      name
      filter
    }
    templates {
      path
      name
    }
  }
}

{
  "secretKey": <SECRET_KEY>,
  "id": <DATABASE_ID>
}

{
  "operationName": "database",
  "variables": {
    "secretKey": <SECRET_KEY>,
    "id": <DATABASE_ID>
  },
  "query": "query database($secretKey: String!, $id: ID!) {\n  database(secretKey: $secretKey, id: $id) {\n    _id\n    name\n    fields {\n      _id\n      name\n      type\n      primary\n      required\n      restrict\n      database\n    }\n  }\n}\n"
}

Example result

Returns the specified database. The database has an _id, name, and an array of fields. See the meaning of each field's properties here, and more information about field types.

{
  "data": {
    "database": {
      "_id": "Ccx2Fzva28RshjFpr",
      "name": "Orders",
      "fields": [
        {
          "_id": "Nb6uqwKdxh3BFX3De",
          "name": "ID",
          "type": "string",
          "primary": true,
          "required": true,
          "restrict": null,
          "database": null
        },
        {
          "_id": "RyM8SyrYrceRsrLJd",
          "name": "Client",
          "type": "ref",
          "primary": null,
          "required": null,
          "restrict": null,
          "database": "uJL9XrebupC7eWvM3"
        },
        {
          "_id": "g5WPqJugq9o3fQPXH",
          "name": "Products",
          "type": "refMultiple",
          "primary": null,
          "required": null,
          "restrict": null,
          "database": "LkfjQ9pq9f48K2vD8"
        },
        {
          "_id": "Jex4vcwa9HZ4GipXg",
          "name": "Photo",
          "type": "attachment",
          "primary": null,
          "required": null,
          "restrict": null,
          "database": null
        },
        {
          "_id": "pnR2Mnqfjdj9vQG8e",
          "name": "Amount",
          "type": "currency",
          "primary": null,
          "required": true,
          "restrict": null,
          "database": null
        },
        {
          "_id": "2ybyZfu6H6KNfGbBt",
          "name": "Location",
          "type": "enum",
          "primary": null,
          "required": null,
          "restrict": [
            "Houston",
            "Atlanta",
            "Las Vegas",
            "Minneapolis",
            "New York"
          ],
          "database": null
        },
        {
          "_id": "q6iD8LCHSjhJusLSd",
          "name": "Date",
          "type": "date",
          "primary": null,
          "required": null,
          "restrict": null,
          "database": null
        },
        {
          "_id": "JYszfW2jpLeTck8mW",
          "name": "Department",
          "type": "enumTags",
          "primary": null,
          "required": null,
          "restrict": [
            "Electronics",
            "Cosmetics",
            "Cookware",
            "Hardware",
            "Home"
          ],
          "database": null
        },
        {
          "_id": "hMQKzyxRBxK4sGN5M",
          "name": "Quantity",
          "type": "number",
          "primary": null,
          "required": null,
          "restrict": null,
          "database": null
        }
      ],
      "filters": [],
      "templates": []
    }
  }
}

{
  "errors": [
    {
      "message": "An error has occurred",
      "name": "GQLError",
      "time_thrown": "2019-11-03T20:26:12.651Z",
      "data": {
        "error": "not-authorized",
        "reason": "This app does not have permission to perform this action."
      }
    }
  ],
  "data": null
}

data

Gets data from a database.

query data($secretKey: String!, $databaseId: ID!, $filter: JSON, $sort: JSON, $limit: Int, $skip: Int, $in: [String], $fields: [String], $removedAt: Boolean, $search: String, $modifiedSince: String) {
  data(secretKey: $secretKey, databaseId: $databaseId, filter: $filter, sort: $sort, limit: $limit, skip: $skip, in: $in, fields: $fields, removedAt: $removedAt, search: $search, modifiedSince: $modifiedSince) {
    _id
    cols {
      fieldId
      value
      rows {
        _id
        cols {
          fieldId
          value
        }
      }      
    }
  }
}

{
  "secretKey": <SECRET_KEY>,
  "databaseId": <DATABASE_ID>
}

{
  "operationName": "data",
  "variables": {
    "secretKey": <SECRET_KEY>,
    "databaseId": <DATABASE_ID>
  },
  "query": "query data($secretKey: String!, $databaseId: ID!, $filter: JSON, $sort: JSON, $limit: Int, $skip: Int, $in: [String], $fields: [String], $removedAt: Boolean, $search: String, $modifiedSince: String) {\n  data(secretKey: $secretKey, databaseId: $databaseId, filter: $filter, sort: $sort, limit: $limit, skip: $skip, in: $in, fields: $fields, removedAt: $removedAt, search: $search, modifiedSince: $modifiedSince) {\n    _id\n    cols {\n      fieldId\n      value\n    }\n  }\n}\n"
}

Example result

Returns an array of rows. Each row has an _id and cols for each column/field of data in the row. The data in each column can differ based on field type, but generally those variations will take place within the value object. When value is an object, it is guaranteed to at least always have a val property.

When a value is empty, value may either be null (indicates "not set"), or value may be an object where val itself is null (indicates "intentionally empty"). Read more about empty values.

You can also find all of the expected value object formats for each data type here.

{
  "data": {
    "data": [
      {
        "_id": "a5hzm9xChLDKrxneG",
        "cols": [
          {
            "fieldId": "Nb6uqwKdxh3BFX3De",
            "value": {
              "val": "order-2883"
            }
          },
          {
            "fieldId": "RyM8SyrYrceRsrLJd",
            "value": {
              "val": "aobSkpbmx5mrpKc8Y",
              "_label": "Sam Arthur"
            }
          },
          {
            "fieldId": "g5WPqJugq9o3fQPXH",
            "value": {
              "val": [
                "cj659qeYY9LuXAJNB",
                "fHLNMGYyj46cRbFyg",
                "xRfACYg7QmBvTykqW"
              ],
              "_label": [
                "Ceramic Bowl",
                "Coffee Maker",
                "Coffee Mug"
              ]
            }
          },
          {
            "fieldId": "Jex4vcwa9HZ4GipXg",
            "value": {
              "val": "https://ply-files.s3.amazonaws.com/T2qgNJQBz6EZgxGc3i/d1a4189e-9389-4aaf-a62a-c475c278b77c.jpeg",
              "type": "image/jpeg",
              "size": 28813
            }
          },
          {
            "fieldId": "pnR2Mnqfjdj9vQG8e",
            "value": {
              "val": 57,
              "currency": "USD"
            }
          },
          {
            "fieldId": "2ybyZfu6H6KNfGbBt",
            "value": {
              "val": "New York"
            }
          },
          {
            "fieldId": "q6iD8LCHSjhJusLSd",
            "value": {
              "val": "2019-06-27T00:00:00.000Z"
            }
          },
          {
            "fieldId": "JYszfW2jpLeTck8mW",
            "value": {
              "val": [
                "Cookware",
                "Home"
              ]
            }
          },
          {
            "fieldId": "hMQKzyxRBxK4sGN5M",
            "value": {
              "val": 2
            }
          }
        ]
      }
    ]
  }
}

{
  "errors": [
    {
      "message": "An error has occurred",
      "name": "GQLError",
      "time_thrown": "2019-11-03T20:26:12.651Z",
      "data": {
        "error": "not-authorized",
        "reason": "This app does not have permission to perform this action."
      }
    }
  ],
  "data": null
}

Advanced data queries

The sample query above may work fine for very simple queries, but the data endpoint allows us to pass many more options to query very specific information. Below is a list of optional variables the data endpoint additionally accepts, beside a secretKey and databaseId.

Examples

{
  fields: {
    "Nb6uqwKdxh3BFX3De": { // ID field
      filters: [
        {
          by: "is",
          value: "order-2883"
        }
      ],
      conjunction: "and"
    }
  },
  conjunction: "and"
}

{
  fields: {
    "RyM8SyrYrceRsrLJd": { // Client field in "Orders"
      fields: {
        "xEfek48BRpD3kAksh": { // Name field in "Clients"
          filters: [
            {
              by: "contains",
              value: "Michael"
            },
            {
              by: "contains",
              value: "John"
            }
          ],
          conjunction: "or"
        }
      },
      conjunction: "and",
      include: {
        // Switch these to true to include rows where the Client
        // field itself is either empty, not set, or has any value.
        // This is different from filtering by a specific field in
        // the "Clients" database.
        "is-empty": false,
        "is-not-set": false,
        "has-any-value": false
      }
    }
  },
  conjunction: "and"
}

{ "pnR2Mnqfjdj9vQG8e": -1, "Nb6uqwKdxh3BFX3De": 1 }

["a5hzm9xChLDKrxneG", "Q42ggoNpiWzhJ9GDZ"]

["Nb6uqwKdxh3BFX3De", "RyM8SyrYrceRsrLJd"]

{ "search": "deal|money" }

content

Gets images and PPT assets for each row in a database.

query content($databaseId: ID!, $secretKey: String!, $filter: JSON, $limit: Int, $skip: Int, $in: [String], $sort: JSON, $search: String, $templatePaths: [String], $modifiedSince: String) {
  content (databaseId: $databaseId, secretKey: $secretKey, filter: $filter, limit: $limit, skip: $skip, in: $in, sort: $sort, search: $search, templatePaths: $templatePaths, modifiedSince: $modifiedSince) {
    _id
    templates {
      name
      path
      pptxUrl
      imageUrl  
      default          
    }
  }
}

{
  "secretKey": <SECRET_KEY>,
  "databaseId": <DATABASE_ID>
}

{
  "operationName": "content",
  "variables": {
    "secretKey": <SECRET_KEY>,
    "databaseId": <DATABASE_ID>
  },
  "query": "query content($databaseId: ID!, $secretKey: String!, $filter: JSON, $limit: Int, $skip: Int, $in: [String], $sort: JSON, $search: String, $templatePaths: [String], $modifiedSince: String) {\n  content(\n    databaseId: $databaseId\n    secretKey: $secretKey\n    filter: $filter\n    limit: $limit\n    skip: $skip\n    in: $in\n    sort: $sort\n    search: $search\n    templatePaths: $templatePaths\n    modifiedSince: $modifiedSince\n  ) {\n    _id\n    templates {\n      name\n      path\n      pptxUrl\n      imageUrl\n      default\n    }\n  }\n}\n"
}

Example result

Returns an array of rows. Each row has an _id and an array oftemplates for each row of data.

{
    "data": {
        "content": [
            {
                "_id": "6MMrY9Du9ShrFYwhb",
                "templates": [
                    {
                        "name": "test",
                        "path": "Folder 1 > Folder 1-1 > Folder 1-1 > Folder 1-1-2 > test",
                        "pptxUrl": "https://tombstones.pitchly.net/content/ppt?token=wmCYMQLs0cs_bx01rl2UkUrYTkG1R10y7WdmqYSUHOdR-K0PcpPJG9ZHPuhpkERlw89NH9Jfqob2Au82dJwC4eknDD_sc4znPNvw3_0Y-UqNCt2cFX65Crugp0vGbex5ICVXLvdgsAGK11vL7optqPK6HOtgb54NGcUoVz2iBJGQ9AlotyawaXMji2xylVh1m4OPgxsdXVzOE4eCnXdXUmNS5kEKa-gp7qSl5bqMHWM",
                        "imageUrl": "https://v2.pitchly.net/content/wmCYMQLs0cs_bx01rl2UkUrYTkG1R10y7WdmqYSUHOdR-K0PcpPJG9ZHPuhpkERlw89NH9Jfqob2Au82dJwC4eknDD_sc4znPNvw3_0Y-UqNCt2cFX65Crugp0vGbex5ICVXLvdgsAGK11vL7optqPK6HOtgb54NGcUoVz2iBJGQ9AlotyawaXMji2xylVh1m4OPgxsdXVzOE4eCnXdXUmNS5kEKa-gp7qSl5bqMHWM",
                        "default": false
                    },
                    {
                        "name": "really nested",
                        "path": "Folder 1 > Folder 1-1 > Folder 1-1 > really nested",
                        "pptxUrl": "https://tombstones.pitchly.net/content/ppt?token=wmCYMQLs0cs_bx01rl2UkUrYTkG1R10y7WdmqYSUHOdR-K0PcpPJG9ZHPuhpkERlw89NH9Jfqob2Au82dJwC4eknDD_sc4znPNvw3_0Y-UqNCt2cFX65Crugp0vGbex5ICVXLvdgsAGK11vL7optqPK6HOtgb54NGcUoVz2iBJGQ9AlotyawaXMji2xylVh1m4OPgxsdXVzOE4eCnXdXUmNS5kEKa-gp7qSl5bqMHWM",
                        "imageUrl": "https://v2.pitchly.net/content/wmCYMQLs0cs_bx01rl2UkUrYTkG1R10y7WdmqYSUHOdR-K0PcpPJG9ZHPuhpkERlw89NH9Jfqob2Au82dJwC4eknDD_sc4znPNvw3_0Y-UqNCt2cFX65Crugp0vGbex5ICVXLvdgsAGK11vL7optqPK6HOtgb54NGcUoVz2iBJGQ9AlotyawaXMji2xylVh1m4OPgxsdXVzOE4eCnXdXUmNS5kEKa-gp7qSl5bqMHWM",
                        "default": false
                    }
                ]
            }
        ]
    }
}

{
  "errors": [
    {
      "message": "An error has occurred",
      "name": "GQLError",
      "time_thrown": "2019-11-03T20:26:12.651Z",
      "data": {
        "error": "not-authorized",
        "reason": "This app does not have permission to perform this action."
      }
    }
  ],
  "data": null
}

Advanced content queries

The sample query above may work fine for very simple queries, but the content endpoint allows us to pass many more options to query very specific information. Below is a list of optional variables the content endpoint additionally accepts, beside a secretKey and databaseId.

Examples

{
  fields: {
    "Nb6uqwKdxh3BFX3De": { // ID field
      filters: [
        {
          by: "is",
          value: "order-2883"
        }
      ],
      conjunction: "and"
    }
  },
  conjunction: "and"
}

{
  fields: {
    "RyM8SyrYrceRsrLJd": { // Client field in "Orders"
      fields: {
        "xEfek48BRpD3kAksh": { // Name field in "Clients"
          filters: [
            {
              by: "contains",
              value: "Michael"
            },
            {
              by: "contains",
              value: "John"
            }
          ],
          conjunction: "or"
        }
      },
      conjunction: "and",
      include: {
        // Switch these to true to include rows where the Client
        // field itself is either empty, not set, or has any value.
        // This is different from filtering by a specific field in
        // the "Clients" database.
        "is-empty": false,
        "is-not-set": false,
        "has-any-value": false
      }
    }
  },
  conjunction: "and"
}

{ "pnR2Mnqfjdj9vQG8e": -1, "Nb6uqwKdxh3BFX3De": 1 }

["a5hzm9xChLDKrxneG", "Q42ggoNpiWzhJ9GDZ"]

{ "search": "deal|money" }

dataCount

Gets the total number of rows in a database, optionally filtered.

query dataCount($secretKey: String!, $databaseId: ID!, $filter: JSON, $in: [String], $removedAt: Boolean, $search: String, $modifiedSince: String) {
  dataCount(secretKey: $secretKey, databaseId: $databaseId, filter: $filter, in: $in, removedAt: $removedAt, search: $search, modifiedSince: $modifiedSince) {
    count
  }
}

{
  "secretKey": <SECRET_KEY>,
  "databaseId": <DATABASE_ID>
}

{
  "operationName": "dataCount",
  "variables": {
    "secretKey": <SECRET_KEY>,
    "databaseId": <DATABASE_ID>
  },
  "query": "query dataCount($secretKey: String!, $databaseId: ID!, $filter: JSON, $in: [String], $removedAt: Boolean, $search: String, $modifiedSince: String) {\n  dataCount(secretKey: $secretKey, databaseId: $databaseId, filter: $filter, in: $in, removedAt: $removedAt, search: $search, modifiedSince: $modifiedSince) {\n    count\n  }\n}\n"
}

Example result

Returns the number of rows in the database, or if filter or in are specified, the number of rows in the result, not subject to a limit.

{
  "data": {
    "dataCount": {
      "count": 1011
    }
  }
}

{
  "errors": [
    {
      "message": "An error has occurred",
      "name": "GQLError",
      "time_thrown": "2019-11-03T20:26:12.651Z",
      "data": {
        "error": "not-authorized",
        "reason": "This app does not have permission to perform this action."
      }
    }
  ],
  "data": null
}

Reference

Field properties

When getting information about the fields in a database using either the database or databases endpoints, the following properties will be returned for each field. A description of each property can be found below.

Data types

Each field in a database can be one of the following types. Note that the programmatic name is different than the user-facing name for each type. The programmatic name is used throughout Pitchly's APIs, while the user-facing name is what the user sees through Pitchly's interface. Examples are representative of the value object returned for each field in each row when getting data via the data endpoint.

Filter parameters

Depending on the data type of a field, different filter options are available. At a filter's core is an object usually consisting of a by property, and usually a value or a slight varation thereof. Below is a list of possible filters for each data type.

string / textBlock

• { by: "is", value: "foo" }

• { by: "is-not", value: "foo" }

• { by: "starts-with", value: "foo" }

• { by: "ends-with", value: "foo" }

• { by: "contains", value: "foo" }

• { by: "does-not-contain", value: "foo" }

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

number

• { by: "is", value: 5 }

• { by: "is-not", value: 5 }

• { by: "is-more-than", value: 5 }

• { by: "is-less-than", value: 5 }

• { by: "is-between", value: { val1: 5, val2: 10 } }

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

boolean

• { by: "is-true" }

• { by: "is-false" }

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

date

• { by: "on", value: "2020-01-23T00:00:00.000Z" }

• { by: "after", value: "2020-01-23T00:00:00.000Z" }

• { by: "before", value: "2020-01-23T00:00:00.000Z" }

• { by: "between", value: { val1: "2020-01-23T00:00:00.000Z", val2: "2020-02-23T00:00:00.000Z" } }

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

currency

• { by: "is", value: 5, currency: "USD" }

• { by: "is-not", value: 5, currency: "USD" }

• { by: "is-more-than", value: 5, currency: "USD" }

• { by: "is-less-than", value: 5, currency: "USD" }

• { by: "is-between", value: { val1: 5, val2: 10 }, currency: "USD" }

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

See all currency types

attachment

• { by: "has-any-value" }

• { by: "is-empty" }

• { by: "is-not-set" }

enum / enumTags

• { values: ["Houston", "Atlanta"], otherValues: ["is-empty", "is-not-set"] }

Every app on Pitchly has a set of permissions that allow it to perform certain actions, no matter whether the app is made to do work on your own organization or on behalf of another. Requesting only the permissions your app needs is a great way to prevent accidental damage if your app tries to do something unintended, or if your app becomes compromised.

Below is a list of all the possible permissions an app can have in Pitchly. If you are building an app that is installable by other organizations, keep in mind that admins of those organizations will be prompted to accept your requested permissions before installing your app. More permissions could lessen the chances that an organization uses your app.

Where to find Permissions

If you are using the Client API to interact with your own data using Pitchly's API, you can specify the maximum permissions that belong to your Key Set (or App). This allows you to restrict what applications using your App Secret can do in Pitchly.

This can be found in in the top right corner of your Pitchly account in the Organization menu > Company settings > API keys > Create new key set or by editing an existing Key Set.

If you have any questions about permissions, how your data can be used by apps, or how to provision the appropriate permissions to access your own data using Pitchly's API, give us a shout.

Pitchly's JavaScript SDK makes it easy to generate access tokens when accessing data on behalf of another organization, but when using the SDK isn't possible, you can still generate access tokens through direct HTTP requests instead.

For certain applications, continual access to data is necessary, even when its users are offline or not logged into Pitchly. One example of this is Pitchly's own Forms app. Forms, for example, must have access to a database's fields even when all users are logged out of the Pitchly platform in order to continue serving forms to outside visitors. To make this possible, particular tokens can be used to generate new access tokens after old ones have expired, without the need for user involvement.

Endpoints

insertRow

Example result

Returns the ID of the new row.

updateRow

Note that only the cols included in the request will be updated. Any others not included in the request will stay the same and not be updated.

Example result

Returns the ID of the updated row.

upsertRow

Conditionally insert or update a row in a database, depending on whether the row already exists. Unlike insert and update operations, this endpoint requires a matchFields parameter, which is an array of field IDs you wish to match against.

If you provide row data that matches an existing row in the fields specified in matchFields, the row will be updated. If no rows match the values in the fields specified in matchFields, the row provided will be inserted into the database.

Note that matchFields must contain the IDs of the fields you wish to match against, and not their names.

Also note that any fields specified in matchFields must be present in the data and also cannot be empty.

Example result

Returns the ID of the new row (if inserted), or the ID of the existing row that was updated.

deleteRow

Deletes a specific row/record from a database.

Example result

Returns true if deletion was successful.

Reference

Data types

Empty values

To make a value "intentionally empty," set val in the value object to null:

When inserting a row, you can also make a value "not set" by simply excluding that field from the row. When updating a row, any field that is not included will not be updated. And empty strings or empty arrays (for fields that accept strings or arrays) will automatically be converted to null.

Required fields

Any data type can be set to empty, except fields that are "required." Fields can be made required via the Pitchly interface when editing a database. Required fields must have a non-empty value and are enforced whenever inserting or updating rows. Required fields are only enforced on fields specified in an insert or update. Fields that are not included in the request will not be enforced.

Note that there are still several situations where a row may contain an empty value in a field that is required. Here are some scenarios:

• The value was empty prior to the field becoming required

• The value was inserted during a bulk CSV import (to prevent partial failures)

• The field was not specified during insertion

• The field was created after the rows were already inserted

• A row that is referenced by another field is deleted, causing the referencing field to turn empty

For these reasons, it is not completely safe to assume that all values in a field will not be empty if the field is required, since required fields must strike a balance between utility and ease-of-use. We think of "required" as a flag that informs users and apps when a field should have a non-empty value. The field will be reasonably validated to ensure the value isn't intentionally empty at time of input, but it should be used more as a visual cue than a strict persistent enforcement scheme.

Accepted date formats

Date values in the following formats will be accepted:

• 2020-01-23T00:00:00.000Z (ISO 8601 format - time will be stripped)

• M-D-YYYY

• M-D-YY

• YYYY-M-D

• M/D/YYYY

• M/D/YY

• YYYY/M/D

• M.D.YYYY

• M.D.YY

• YYYY.M.D

Accepted currency types

Pitchly currently supports the following currency types by code.

For certain applications, continual access to data is necessary, even when its users are offline or not logged into Pitchly. One example of this is Pitchly's own Forms app. Forms, for example, must have access to a database's fields even when all users are logged out of the Pitchly platform in order to continue serving forms to outside visitors. To make this possible, particular tokens can be used to generate new access tokens after old ones have expired, without the need for user involvement.

Despite the name "Long-lived tokens," Pitchly actually uses the Refresh Token grant specified in the OAuth 2.0 standard to continuously generate new access tokens without user involvement. The advantage of refresh tokens over actual long-lived tokens is that they still expire, in the rare event one happens to leak.

Acquiring a refresh token

To get a refresh token, a regular access token must first be obtained via a user of your app (the Client) via the Pitchly platform. Once a regular access token is obtained, it can be sent to your server to attach a client_secret and client_id before making another server-side request to Pitchly to generate a new access token and refresh token. Save the new access token and refresh token on your server. Use the new access token on the client or server side, but keep the refresh token on the server side only. Do not reveal the refresh token to the client or any services besides your server and Pitchly's servers!

Using the refresh token

To generate a new access token once the old one expires without user involvement, you will use the refresh token stored on your server. Once you've determined that your current access token is no longer valid and you need a new one, send a request to Pitchly with the refresh token. Pitchly will return a new access token and a new refresh token, invalidating the old refresh token. Store the new refresh token on your server - without revealing it to the Client or any other party! - and continue to use the new access token normally until it expires again.

This is a high level overview of Pitchly Refresh Tokens for use in applications that require continuous data access on behalf of another organization, even when the application's users are not actively using Pitchly or your app. For specific details on Pitchly's OAuth endpoints, please contact us.

Generating access tokens with Pitchly is not as scary as it sounds. Access tokens are essentially a unique string of jumbled characters and numbers that acts as a key to a particular organization's data. With one, you can do whatever your App has been authorized to do against the organization, limited to the scope and resources your App was given access.

Installation

If you are building a web app that has a frontend interface through which users will use your App, you don't need to handle the process of generating access tokens yourself. You can instead use our JavaScript SDK, which will generate and renew access tokens automatically for you.

To use the Pitchly JavaScript SDK, just embed the following into your <head> tag:

<script src="https://use.pitchly.com/sdk.js"></script>

Initialization & Callbacks

Initialize Pitchly wherever you're ready to start using Pitchly, probably after your page is loaded:

pitchly = new Pitchly({
  appId: "YOUR-APP-ID",
  onConnect: function(response) {
    if (response.error) { // error
      console.log(response.error);
      return;
    }
    // got access token, do stuff here...
    console.log(response.accessToken);
  }
});

The Pitchly function accepts several more optional parameters:

The onConnect callback will return a response object. Below is an example of a successful response:

{
  accessToken: "8KCYeiBx6idE9eXauYLeOnnDR2ySWmsm4uztyq0PGeX",
  accessTokenExpiresAt: "Sat Nov 24 2018 19:36:41 GMT-0600 (Central Standard Time)",
  organizationId: "fjzw5XGzqcXTH7PX7"
}

On error, the response will look something like:

{
  error: {
    name: "could-not-connect",
    reason: "Could not connect to Pitchly server.",
    code: 0 // the HTTP status code (will be 0 if network error)
  }
}

Methods

You can also perform certain actions against the instantiated Pitchly object:

To hide the filter when your App is initialized, for example, you would simply call:

pitchly.hideFilter()

To get the current organization and database, you would call:

pitchly.getOrganizationId();
pitchly.getDatabaseId();

You shouldn't normally need to call the latter methods to request information, since changes to the filter, row selections, etc. will automatically be pushed to you as they change via the onFilter, onSelection, etc. callbacks. The exception is requestUserId.

Any of the "request" type methods also accept an optional callback as an argument. When a callback is given, the callback will receive the result of the request after it has completed. It will be executed after any on___ callbacks.

Things to know about access tokens

We wouldn't feel right unless we let you know about a few things you should know about access tokens:

1. They expire after two hours (Luckily the SDK renews them automatically for you within 2-5 minutes of expiration. If internet connection is lost, it will retry every 5 seconds until a connection is made or until Pitchly returns an error. If a permanent error is returned, it's on you to call pitchly.generateAccessToken() to try again after the problem is resolved.)

2. Because access tokens renew automatically, you may get multiple calls to onConnect after a user has had your App open for more than two hours. If you cache the token anywhere, make sure you update it whenever you receive a new one.

3. Access tokens are scoped to the organization, not the database. We made it this way because it allows Apps to be more flexible when using data that spans across multiple databases, and it allows Apps to be presented to users in a variety of ways. Keep this in mind when designing your App's backend data structures, if you store any access tokens.

4. Even though access tokens are scoped to an organization, your App might not necessarily be. Often times, users install Apps on a specific database. Depending on your App, users may expect to see different saved information in your App, depending on which database they're in. Also keep this in mind when designing your data structures. (We recommend in this scenario centering information around "installs" instead of users or organizations.)

5. Access tokens may not always be new. They will often be re-used up to 10 minutes before their expiration.

Security checklist

Access tokens are very powerful, but with great power comes great responsibility. You should take the following factors into consideration when dealing with access tokens.

• Always use HTTPS (not necessary for development, but this is necessary for any Apps in production)

• If you store access tokens in a backend database, make sure access rights prevent anyone from being able to access other users' access tokens.

• Make sure to request only the permissions you need for your App. This will limit potential harm if, for any reason, an access token becomes compromised.

• To satisfy legal requirements, you must have a process in place to delete any and all user or company data you have received from Pitchly at the request of Pitchly. Please respect our clients.

Clients trust Pitchly to keep their data secure. For that reason, we have additional stringency requirements. These points simply serve as a reminder to follow best security practices and is by no means an exhaustive checklist. We will be adding more tips and pointers to this list over time.

Troubleshooting

If you're having any of the below issues, we may have possible solutions.

Q: Pitchly is telling me my access token is invalid or expired.

A: You may be using an old access token. Check whether your access token is coming from storage or a cache. You may also benefit from clearing your browser's history or trying to run your App in Incognito Mode in your browser.

Q: Pitchly is telling me I don't have permission to perform an action.

A: Every App is given permission to only do certain things on an organization in Pitchly. You may not have the permission to do that particular task. If you really do need this extra permission, contact us to request special permissions.

Q: Pitchly is telling me my App doesn't exist.

A: You probably haven't set the appId parameter to the correct value when initiating the Pitchly SDK. Make sure this is the same value you received when you registered your App with Pitchly. Also make sure it is your App ID and not your App's Secret. (Never put your App Secret in client-side code!)

Do you have a problem not listed here? Contact us and we'll try to help.

What if I'm not building a web app?

This guide covers how to generate access tokens using the Pitchly JavaScript SDK. However, if you can't use our SDK for any reason (such as because your App will not be user-facing or built on the web), you can still generate access tokens by using our REST API directly. In the big picture, our SDK is simply an abstraction that makes the process of working with our OAuth endpoints easier.

Our advanced guide will tell you what you need to know to work with our OAuth endpoints directly.