GW Apps Records API

Records API Overview

The Records API is a REST API that can be accessed through explicit HTTP calls; the API exposes most of the record related features available in the GW Apps Web interface. This document describes how to use RESTful calls.

Note: The API does not support calls that modify the application design or configuration.

Note: This API documentation is intended to give the reader an overview of the APIs capabilities and how to access them. When trying to write API calls, we strongly recommend you use the API documentation directly associated with the specific API key you will be calling. That documentation includes examples with the actual IDs of the form and form elements, includes examples for each field available in the associated forms etc. This will allow direct copy-paste of the code snippets from the documentation into your code. If you were to try and use the examples in this documentation, you would have to modify them for the fields, form ID, etc.

Authentication

Before your application can access the endpoint to get private data, it must obtain an access_token that grants access to that API. A single access_token can grant varying degrees of access to multiple APIs.

It is generally a best practice to request only scopes required. For example, an app that wants access to search for the available entities should only enable “View and Search” scopes. You can always modify your scope access anytime your use case changes or generate other keys for other purposes.

After an application obtains an access token, it sends the token to a GW Apps API in an HTTP Authorization request header. Access tokens are valid only for the set of operations and resources described in the scope of the API Key created.

For example, if an access token is issued for Form A, it does not grant access to the Form B records API.

Authentication

Your application must use this API “/token” to authorize requests. Each generated access_token is valid for 1 hour.

HTTP request

POST https://api.gwapps.com/v1/token

Request Headers

Header	value
Content-Type	application/json

Request Body

Parameter	Description	Type
Required body parameters
key	The key generated by GWAPPS	string
email	The email to be used to impersonate the user account to make the api calls	string
customerId	The customerId citen_e0b70	string

Example Request

  {
      "key": apiKey,
      "email": email,
      "customerId": "citen_e0b70"
  }

Response

start

Note: The generated token is valid for 1 hour, you might need to implement a strategy to generate a new access_token accordingly.

  {
      "access_token": access_token,
      "expires_in": 3600,
      "token_type": "Bearer"
  }

start

Note: Every request your application sends to the Records API must include an authorization token. The token also identifies the user account you want to impersonate (which defines the level of access you have to given records).

Header	value
Authorization	Beareraccess_token
Content-Type	Application/json

Filters

The supported filters and operators when searching for records using the “Search Records” API.

Reference

Operator	Supported Fields	Value Type	Value Example
BLANK	All Fields	No value required
NOT_BLANK	All Fields	No value required
EQUALSNOT_EQUALS	Created On, Updated On	string	“2023-11-16T03:30:00”
	Currency, Number	number	100
	Date	string	“2023-11-16”
	Email	string	“john.doe@example.com”
	Phone Number	string	“3103101234”
	Record ID	string	“REQ#00001”
	Country, State, Text, Textarea	string	“United States”, “CA”, “John”
	Time	string	“17:30”
EQUALS_VALUE	Checkbox, Radio, Dropdown, Lookup	string	“Option 1”
NOT_EQUALS_VALUE
CONTAINSDOES_NOT_CONTAINS	Created By, Updated By, User, User List	string	“Jane”
	Email	string	“jane.doe”
	Country, State, Text, Textarea	string	“United”, “John”
	Record ID	string	“REQ#”
GREATER_THANLESS_THAN	Created On, Updated On	string	“2023-11-16T03:30:00”
	Currency, Number	number	100
	Date	string	“2023-11-16”
	Time	string	“17:30”
GREATER_THAN_EQ_TOLESS_THAN_EQ_TO	Currency, Number	number	100
LIKENOT_LIKE	Country, State, Phone Number	string	“United”, “310310”
LIKE_VALUENOT_LIKE_VALUE	Checkbox, Radio, Dropdown, Lookup Field	string	“Option 1”
IN	Stage	string [ ]	[“stg0”]

Notes:

• Dates are in UTC
• The accepted date value format is yyyy-MM-dd.
• The accepted date time value format is yyyy-MM-ddTHH:mm:ss.
• The accepted time value format is 24h, e.g. 13:30
• The accepted phone number value format does not contain country code, e.g. 3236397888

Filters with OR condition

The records will be returned based on the criteria if at least one of the conditions is true.

{
  "filters": [
    [
      {
        "fieldCode": "company1",
        "operator": "CONTAINS",
        "value": "vip"
      },
      {
        "fieldCode": "name1",
        "operator": "CONTAINS",
        "value": "john"
      }
    ]
  ]
}

Filters with AND condition

The records will be returned based on the criteria if all conditions are true.

{
  "filters": [
    {
      "fieldCode": "company1",
      "operator": "EQUALS",
      "value": "Vipe"
    },
    {
      "fieldCode": "stage",
      "operator": "IN",
      "value": [
        "stg0"
      ]
    }
  ]
}

Once you have entered the new API key’s name, and optionally added a description, and clicked ‘Create’, you will see the API Key Editor with your new key loaded so that you can complete it’s configuration:

API Methods

All Field Types

Parameters

Parameter	Value	Description
formId	?????????????????????????	The form identifier of the current selected form, this value it’s required as a query parameter on each endpoint

Stages

All records have a stage attribute which defines the status of the record. The “All Field Types” has the following stages defined, you would need to reference the stage.id for creating and updated records.

Status / Stage Name	Stage Id
Draft	stg0
Published	stg1

Example Request

  {
      "stage": "stg0"
  }

OR

  {
      "stage": {
        "id": "stg0"
        "status": "Draft"
      }
  }

Record Definition for form “All Field Types”

This is the record representation including all fields and the expected value types.

Short Code	Field Name	Type	Accepted Values
text_field1	Text	Text	string
date_field2	Date	Date	ISODate
user1	User	Directory Lookup	{ “_id”: “string”, “name”: “string”, “email”: “string” }
dropdown1	Dropdown Lookup	List	{ “code”: “string”, “value”: “string” }
text_area1	Text Area	Textarea	string
time1	Time	Time	string
user_list1	User List	Directory List	[ { “_id”: “string”, “name”: “string”, “email”: “string” } ]
lookup2	Lookup	Multi Lookup	{ “code”: “string”, “value”: “string” }
number_field1	Number	Number	number
radio_button1	Radio Button	Radio	{ “code”: “string”, “value”: “string” }
department1	Department	Text	string
checkbox1	Checkbox	Checkbox	[ { “code”: “string”, “value”: “string” } ]
phone1	Phone	Phone Number	{ “code”: “string”, “phone”: “string” }
city1	City Clear	Text	string
state1	State Clear	State	string
zip1	Zip Clear	Text	string
country1	Country Clear	Country	string
attachment1	Attachment	File Picker	[ { “name”: “string”, “mimeType”: “string”, “fileId”: “string” } ]
drive_picker1	Drive Picker	Drive Picker	[ { “id”: “string”, “mimeType”: “string”, “name”: “string”, “url”: “string” } ]
signature1	Signature	Signature	{ “data”: “string”, “date”: “ISODate” }
table1	Table	Dynamic Table	Array
table1.new_column-ta1	New Column-[table]	Text	string
table1.new_columntab1	New Column[table]	Currency	{ “code”: “string”, “value”: “number” }
table1.new_columntab2	New Column[table]	Currency	{ “code”: “string”, “value”: “number” }
stage	Status	Stage	{ “id”: “string”, “status”: “string” }
Readonly Fields
createdBy	Created By	Created By	{ “name”: “string”, “email”: “string”, “_id”: “string” }
createdOn	Created On	Created On	ISODate
updatedBy	Updated By	Updated By	{ “name”: “string”, “email”: “string”, “_id”: “string” }
updatedOn	Updated On	Updated On	ISODate
recordId	Record Id	Record Id	{ “inc”: “number”, “value”: “string” }
approvers	Approvers	Approvers

Related API Articles

This article covers the overall Records API structure and calls/endpoints. Details for the specific calls/endpoints are covered in individual articles. Additional options for API Keys can be found within the API section of the Platform Settings, and in the Security > API Keys section of Edit App within each application.