Mutations (push)
For when you want to push data to Pitchly

Endpoints

Endpoint
Description
insertRow
Insert a row into a database.
updateRow
Update an existing row in a database.
deleteRow
Delete an existing row in a database.

insertRow

Inserts a row/record into a database. The row can have any number of cols for each column. Only a fieldId and value must be provided for each column. value could look different depending on the data type of the column.
GraphQL
REST
1
mutation insertRow($secretKey: String!, $databaseId: ID!, $row: DataRowInput!) {
2
insertRow(secretKey: $secretKey, databaseId: $databaseId, row: $row) {
3
_id
4
}
5
}
Copied!

Variables:

1
{
2
"secretKey": <SECRET_KEY>,
3
"databaseId": <DATABASE_ID>,
4
"row": {
5
"cols": [
6
{
7
"fieldId": <FIELD_ID>,
8
"value": {
9
"val": "Foo Bar"
10
}
11
}
12
]
13
}
14
}
Copied!
In the Body of the request:
1
{
2
"operationName": "insertRow",
3
"variables": {
4
"secretKey": <SECRET_KEY>,
5
"databaseId": <DATABASE_ID>,
6
"row": {
7
"cols": [
8
{
9
"fieldId": <FIELD_ID>,
10
"value": {
11
"val": "Foo Bar"
12
}
13
}
14
]
15
}
16
},
17
"query": "mutation insertRow($secretKey: String!, $databaseId: ID!, $row: DataRowInput!) {\n insertRow(secretKey: $secretKey, databaseId: $databaseId, row: $row) {\n _id\n }\n}\n"
18
}
Copied!

Example result

Returns the ID of the new row.
Success
Error
1
{
2
"data": {
3
"insertRow": {
4
"_id": "bHBSESizM5jEmiRRn"
5
}
6
}
7
}
Copied!
1
{
2
"errors": [
3
{
4
"message": "An error has occurred",
5
"name": "GQLError",
6
"time_thrown": "2019-11-03T20:26:12.651Z",
7
"data": {
8
"error": "not-authorized",
9
"reason": "This app does not have permission to perform this action."
10
}
11
}
12
],
13
"data": null
14
}
Copied!

updateRow

Updates a specific row/record in a database. The new row can have any number of cols for each updated column. Only a fieldId and value must be provided for each column. value could look different depending on the data type of the column.
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.
GraphQL
REST
1
mutation updateRow($secretKey: String!, $databaseId: ID!, $rowId: ID!, $row: DataRowInput!) {
2
updateRow(secretKey: $secretKey, databaseId: $databaseId, rowId: $rowId, row: $row) {
3
_id
4
}
5
}
Copied!

Variables:

1
{
2
"secretKey": <SECRET_KEY>,
3
"databaseId": <DATABASE_ID>,
4
"rowId": <ROW_ID>,
5
"row": {
6
"cols": [
7
{
8
"fieldId": <FIELD_ID>,
9
"value": {
10
"val": "Foo Bar"
11
}
12
}
13
]
14
}
15
}
Copied!
In the Body of the request:
1
{
2
"operationName": "updateRow",
3
"variables": {
4
"secretKey": <SECRET_KEY>,
5
"databaseId": <DATABASE_ID>,
6
"rowId": <ROW_ID>,
7
"row": {
8
"cols": [
9
{
10
"fieldId": <FIELD_ID>,
11
"value": {
12
"val": "Foo Bar"
13
}
14
}
15
]
16
}
17
},
18
"query": "mutation updateRow($secretKey: String!, $databaseId: ID!, $rowId: ID!, $row: DataRowInput!) {\n updateRow(secretKey: $secretKey, databaseId: $databaseId, rowId: $rowId, row: $row) {\n _id\n }\n}\n"
19
}
Copied!

Example result

Returns the ID of the updated row.
Success
Error
1
{
2
"data": {
3
"updateRow": {
4
"_id": "bHBSESizM5jEmiRRn"
5
}
6
}
7
}
Copied!
1
{
2
"errors": [
3
{
4
"message": "An error has occurred",
5
"name": "GQLError",
6
"time_thrown": "2019-11-03T20:26:12.651Z",
7
"data": {
8
"error": "not-authorized",
9
"reason": "This app does not have permission to perform this action."
10
}
11
}
12
],
13
"data": null
14
}
Copied!

deleteRow

Deletes a specific row/record from a database.
GraphQL
REST
1
mutation deleteRow($secretKey: String!, $databaseId: ID!, $rowId: ID!) {
2
deleteRow(secretKey: $secretKey, databaseId: $databaseId, rowId: $rowId)
3
}
Copied!

Variables:

1
{
2
"secretKey": <SECRET_KEY>,
3
"databaseId": <DATABASE_ID>,
4
"rowId": <ROW_ID>
5
}
Copied!
In the Body of the request:
1
{
2
"operationName": "deleteRow",
3
"variables": {
4
"secretKey": <SECRET_KEY>,
5
"databaseId": <DATABASE_ID>,
6
"rowId": <ROW_ID>
7
},
8
"query": "mutation deleteRow($secretKey: String!, $databaseId: ID!, $rowId: ID!) {\n deleteRow(secretKey: $secretKey, databaseId: $databaseId, rowId: $rowId)\n}\n"
9
}
Copied!

Example result

Returns true if deletion was successful.
Success
Error
1
{
2
"data": {
3
"deleteRow": true
4
}
5
}
Copied!
1
{
2
"errors": [
3
{
4
"message": "An error has occurred",
5
"name": "GQLError",
6
"time_thrown": "2019-11-03T20:26:12.651Z",
7
"data": {
8
"error": "not-authorized",
9
"reason": "This app does not have permission to perform this action."
10
}
11
}
12
],
13
"data": null
14
}
Copied!

Reference

Data types

When inserting or updating data rows, the value object that you will set for each column of data will largely be the same as the output you receive when querying rows of data. But there are some minor differences, mostly with attachment, ref, and refMultiple fields. Below is a list of all field types and their equivalent expected value object examples when inserting or updating row values.
Field type
User-facing name
Description & example
string
Single-line text
Short single-line text
{ val: "foo" }
textBlock
Multi-line text
Long multi-line text
{ val: "foo\nbar" }
number
Number
Number w/ possible decimal
{ val: 12.5 }
boolean
Yes/No
Binary true/false value
{ val: false }
date
Date
Date in one of these acceptable formats
{ val: "2020-01-23" }
currency
Currency
Currency amount & 3-char currency code (see list)
{ val: 50, currency: "USD" }
attachment
Attachment
File of any type. Pass in the URL path to any file on the Internet. This file will be copied to Pitchly's file storage system, and subsequent queries will return the path to our hosted version.
{ val: "https://pitchly.com/images/pitchly-logo.png" }
enum
Dropdown
A single value selected from a dropdown of predefined values. This value must be present in the field's restrict array.
{ val: "Las Vegas" }
enumTags
Dropdown multiple
Multiple values selected from a dropdown of predefined values. Each value must be present in the field's restrict array.
{ val: ["Los Angeles", "Las Vegas", "San Francisco"] }
ref
Reference
Refers to a row from another database, by row ID
{ val: "TG9PmpmHFiWhe7qDE" }
refMultiple
Reference multiple
Refers to multiple rows from another database, by row ID
{ val: ["FhGmrYNGxjB8JnjJr", "L6QqTQv5JbJ4aQMLB"] }

Empty values

To make a value "intentionally empty," set val in the value object to null:
1
{ val: null }
Copied!
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.
String values are also trimmed of excess whitespace at the beginning and end of the string.

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
Single M and D represent month and day, respectively, with or without leading zeros.
Regardless of the date format entered, dates will always be returned in ISO 8601 format with a zeroed out UTC time when queried.

Accepted currency types

Pitchly currently supports the following currency types by code.
Code
Symbol
Name
USD
$
U.S. Dollars
GBP
£
British Pounds
EUR
Euros
AUD
$
Australian Dollars
BRL
R$
Brazilian Real
CAD
$
Canadian Dollars
CZK
Czech koruny
DKK
kr
Danish Kroner
HKD
$
Hong Kong Dollars
HUF
Ft
Hungarian Forints
ILS
Israeli Shekels
INR
Indian Rupee
JPY
¥
Japanese Yen
MYR
RM
Malaysian Ringgits
MXN
$
Mexican Pesos
NZD
$
New Zealand Dollars
NOK
kr
Norwegian Kroner
PHP
Php
Philippine Pesos
PLN
Polish zloty
SGD
$
Singapore Dollars
SEK
kr
Swedish Kronor
CHF
CHF
Swiss Francs
TWD
$
Taiwan New Dollars
THB
฿
Thai Baht
TRY
TL
Turkish Liras
If you see a mistake in this list or would like to request additional currencies, please contact us.
Last modified 1yr ago