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 |
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” | |
string | “[email protected]” | ||
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” |
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.