1. Home
  2. Integrations
  3. API
  4. GW Apps Records API

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

Headervalue
Content-Typeapplication/json

Request Body

ParameterDescriptionType
Required body parameters
keyThe key generated by GWAPPSstring
emailThe email to be used to impersonate the user account to make the api callsstring
customerIdThe customerId citen_e0b70string

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).

Headervalue
AuthorizationBeareraccess_token
Content-TypeApplication/json

Filters

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

Reference

OperatorSupported FieldsValue TypeValue Example
BLANKAll FieldsNo value required
NOT_BLANKAll FieldsNo value required
EQUALSNOT_EQUALSCreated On, Updated Onstring“2023-11-16T03:30:00”
Currency, Numbernumber100
Datestring“2023-11-16”
Emailstring[email protected]
Phone Numberstring“3103101234”
Record IDstring“REQ#00001”
Country, State, Text, Textareastring“United States”, “CA”, “John”
Timestring“17:30”
EQUALS_VALUECheckbox, Radio, Dropdown, Lookupstring“Option 1”
NOT_EQUALS_VALUE
CONTAINSDOES_NOT_CONTAINSCreated By, Updated By, User, User Liststring“Jane”
Emailstring“jane.doe”
Country, State, Text, Textareastring“United”, “John”
Record IDstring“REQ#”
GREATER_THANLESS_THANCreated On, Updated Onstring“2023-11-16T03:30:00”
Currency, Numbernumber100
Datestring“2023-11-16”
Timestring“17:30”
GREATER_THAN_EQ_TOLESS_THAN_EQ_TOCurrency, Numbernumber100
LIKENOT_LIKECountry, State, Phone Numberstring“United”, “310310”
LIKE_VALUENOT_LIKE_VALUECheckbox, Radio, Dropdown, Lookup Fieldstring“Option 1”
INStagestring [ ][“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

ParameterValueDescription
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 NameStage Id
Draftstg0
Publishedstg1

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 CodeField NameTypeAccepted Values
text_field1TextTextstring
date_field2DateDateISODate
user1UserDirectory Lookup{ “_id”: “string”, “name”: “string”, “email”: “string” }
dropdown1Dropdown LookupList{ “code”: “string”, “value”: “string” }
text_area1Text AreaTextareastring
time1TimeTimestring
user_list1User ListDirectory List[ { “_id”: “string”, “name”: “string”, “email”: “string” } ]
lookup2LookupMulti Lookup{ “code”: “string”, “value”: “string” }
number_field1NumberNumbernumber
radio_button1Radio ButtonRadio{ “code”: “string”, “value”: “string” }
department1DepartmentTextstring
checkbox1CheckboxCheckbox[ { “code”: “string”, “value”: “string” } ]
phone1PhonePhone Number{ “code”: “string”, “phone”: “string” }
city1City ClearTextstring
state1State ClearStatestring
zip1Zip ClearTextstring
country1Country ClearCountrystring
attachment1AttachmentFile Picker[ { “name”: “string”, “mimeType”: “string”, “fileId”: “string” } ]
drive_picker1Drive PickerDrive Picker[ { “id”: “string”, “mimeType”: “string”, “name”: “string”, “url”: “string” } ]
signature1SignatureSignature{ “data”: “string”, “date”: “ISODate” }
table1TableDynamic TableArray
table1.new_column-ta1New Column-[table]Textstring
table1.new_columntab1New Column[table]Currency{ “code”: “string”, “value”: “number” }
table1.new_columntab2New Column[table]Currency{ “code”: “string”, “value”: “number” }
stageStatusStage{ “id”: “string”, “status”: “string” }
Readonly Fields
createdByCreated ByCreated By{ “name”: “string”, “email”: “string”, “_id”: “string” }
createdOnCreated OnCreated OnISODate
updatedByUpdated ByUpdated By{ “name”: “string”, “email”: “string”, “_id”: “string” }
updatedOnUpdated OnUpdated OnISODate
recordIdRecord IdRecord Id{ “inc”: “number”, “value”: “string” }
approversApproversApprovers

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.

Updated on August 27, 2024
Was this article helpful?

Related Articles