Searching and Getting Entries with the REST API v2

Introduction

The /entries, /forms/[FORM_ID]/entries, and /entries/[ENTRY_ID] endpoints are used to search and get entries.

Authentication

The capability gravityforms_view_entries is required to use GET requests at these endpoints.
This can be filtered using gform_rest_api_capability_get_entries.

Getting a Specific Entry

The /entries/[ENTRY_ID] endpoint is used to get an entry by it’s ID.

Method

This endpoint accepts GET requests in order to retrieve an entry.

Path

/gf/v2/entries/1

Required Properties

There are no required properties.

Optional Properties

The request URL can also include the following parameters.

Key	Type	Description
_field_ids	string	A comma separated list of fields to include in the response. When including this property, only the explicitly requested entry properties will be included in the response.
_labels	integer	Default is `0`. Indicates whether to enable the inclusion of field labels in the results.

Response

Success

A successful response will contain a JSON object with the entry details.

Key	Type	Description
[entry_property]	mixed	Entry properties of the Entry Object.
[input_id]	string	Submission values of each form field input for the entry.
_labels	JSON object	Only present when `_labels` is `1` in request. Contains field input and labels pairing for the form.

Failure

A failed response will provide a JSON string of the error code and message.

Key	Type	Description
code	string	Error code. `gf_entry_invalid_id`
message	string	Human-readable error message.
data[status]	integer	HTTP response status code

Usage Examples

cURL Request

curl "https://rocket.test/wp-json/gf/v2/entries/159?_labels=1" \
     -u 'ck_5f86565df60696c43af25f9194e106800770b8e9:cs_be0190310fefc061c564168670d0a96d68873c29'

Response

{
  "id": "159",
  "form_id": "30",
  "post_id": null,
  "date_created": "2023-09-01 19:30:44",
  "date_updated": "2023-09-01 19:30:44",
  "is_starred": "0",
  "is_read": "1",
  "ip": "50.104.76.242",
  "source_url": "https:\/\/rocket.twhl.dev\/wp-json\/gf\/v2\/entries",
  "user_agent": "API",
  "currency": "USD",
  "payment_status": null,
  "payment_date": null,
  "payment_amount": null,
  "payment_method": "",
  "transaction_id": null,
  "is_fulfilled": null,
  "created_by": "4",
  "transaction_type": null,
  "status": "active",
  "1.3": "Neil",
  "1.6": "Armstrong",
  "3": "[email protected]",
  "4": "To the moon!",
  "1.2": "",
  "1.4": "",
  "1.8": "",
  "_labels": {
    "1": {
      "1": "Name",
      "1.2": "Prefix",
      "1.3": "First",
      "1.4": "Middle",
      "1.6": "Last",
      "1.8": "Suffix"
    },
    "3": "Email",
    "4": "Message"
  }
}

cURL Request

curl "https://rocket.test/wp-json/gf/v2/entries/159?_field_ids=1.6,4" \
     -u 'ck_5f86565df60696c43af25f9194e106800770b8e9:cs_be0190310fefc061c564168670d0a96d68873c29'

Response

{
  "date_created": "2023-09-01 19:30:44",
  "1.6": "Armstrong",
  "4": "To the moon!"
}

Searching Entries

The /entries endpoint is used to get all entries or all entries matching specific search parameters

Method

These endpoints accept GET requests in order to retrieve entries.

Path

/gf/v2/entries

/gf/v2/forms/[FORM_ID]/entries

Required Properties

There are no required properties.

Optional Properties

The request URL can also include the following parameters.

Key	Type	Description
_field_ids	string	A comma separated list of fields to include in the response. When including this property, only the explicitly requested entry properties will be included in the response.
_labels	integer	Default is `0`. Indicates whether to enable the inclusion of field labels in the results.
form_ids	array	An array of forms for which entries should be included. Only available when using the endpoint `/gf/v2/entries`.
include	array	An array of entries to include in the response. If an included entry id is not found in the database, no error is thrown.
search	array	Optional. An associative array containing the search arguments. It is expected that `search` will be provided as JSON.
sorting	array	Optional. An associative array containing the sorting arguments.
paging	null\|array	Optional. An associative array containing the paging arguments. IMPORTANT TIP: use paging to limit the number of entries otherwise you may find the database times out.

Search Arguments

An associative array supporting the following properties. Must be provided in request as JSON.

Prop	Type	Description
status	string	Default is active. The status of the entry. Possible values are active, spam, trash.
field_filters	array	See Field Filters

Field Filters

Prop	Type	Description
	array	One or more associative arrays. See Field Filter.
mode	string	Optional. Defaults to `all`. Possible values: `all` or `any`. Determines if the found entries have to match all the field filters or any.

Field Filter

An associative array supporting the following properties.

Prop	Type	Description
key	string	The field ID, entry property, or entry meta key.
value	string\|integer\|float\|array	The value to find for the specified `key`.
operator	string	Optional. Defaults to `=`. Possible values: `=`, `IS`, `CONTAINS`, `IS NOT`, `ISNOT`, `<>`, `LIKE`, `NOT IN`, `NOTIN`, or `IN`. Lowercase is also supported.
is_numeric	boolean	Optional. Indicates if the values of the specified `key` are numeric.

Sorting Arguments

An associative array supporting the following properties.

Prop	Type	Description
key	string\|integer	Default is entry id. The database field by which to sort. See the database structure for the wp_gf_entry table for fields that may be used.
direction	string	Default is DESC. The direction of sorting. Either ASC, DESC, or RAND (random order).
is_numeric	boolean	Default is false when `sorting[key]` is specified. Indicates if the key is numeric.

Paging Arguments

An associative array supporting the following properties.

Prop	Type	Description
page_size	integer	The number of results per page.
current_page	integer	The current page from which to pull details.
offset	integer	The record number on which to start retrieving data. It is zero-based. If the `current_page` property is specified, then `offset` is not used.

Response [json]

A successful response will contain a JSON object with matching entries.

Key	Type	Description
total_count	integer	A count of all matching entries.
entries	array	An array of matching entry objects.

Usage Examples

Retrieve specific entry

curl --location --request GET 'https://example.com/wp-json/gf/v2/entries/112' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json'

Retrieve specific fields

This example shows how to retrieve values of field IDs 1, 6.1, 6.2, 6.3 and date_created for entries on Form ID 112 while including field labels.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/forms/112/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode '_field_ids=1,6.1,6.2,6.3,date_created' \
--data-urlencode '_labels=1'

Include specific forms

This example shows how to get all entries from Form ID 1 and Form ID 30.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'form_ids[]=1' \
--data-urlencode 'form_ids[]=30'

Include specific entries

This example shows how to get multiple specific entries by entry ID using the include property.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'include[]=12' \
--data-urlencode 'include[]=45' \
--data-urlencode 'include[]=51'

Use paging

This example shows how to retrieve 20 results per page.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'paging[page_size]=20'

This example shows how to retrieve 20 results per page.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'paging[page_size]=20'

This example shows how to retrieve 20 results per page starting with the 16th row (offset starts at 0)

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'paging[page_size]=20' \
--data-urlencode 'paging[offset]=15'

This example shows how to retrieve 5 results per page starting with the second page

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'paging[page_size]=5' \
--data-urlencode 'paging[current_page]=2'

Use sorting

This example shows how to sort results ASCending by id

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'sorting[key]=id' \
--data-urlencode 'sorting[direction]=ASC' \
--data-urlencode 'sorting[is_numeric]=true'

This example shows how to sort results DESCending by date_created

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'sorting[key]=date_created' \
--data-urlencode 'sorting[direction]=DESC'

This example shows how to sort results randomly when retrieving all enries for Form ID 19

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/forms/19/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'sorting[direction]=RAND'

This example shows how to sort results by Field ID 2

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'sorting[key]=2'

Search entries

This example shows how to retrieve entries where Field ID 2 contains the text test.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'search={"field_filters":[{"key":2,"value":"test","operator":"contains"}]}'

This example shows how to retrieve entries where Field ID 2 and Field ID 1.3 contains the text squiffy. Note that since search mode is not specified all is used for the mode.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'search={"field_filters":[{"key":2,"value":"squiffy","operator":"contains"},{"key":1.3,"value":"squiffy","operator":"contains"}]}'

This example performs the same search as above, but sets mode to match against any of the provided field filters.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'search={"field_filters":["mode":"any","0":{"key":2,"value":"squiffy","operator":"contains"},"1":{"key":1.3,"value":"squiffy","operator":"contains"}]}'

This example retrieve entries created on a specific day (i.e. September 10, 2019) by filtering on the date_created property of the entry.

curl --location --request GET -G 'https://example.com/wp-json/gf/v2/entries' \

--user 'alisha:XnVO ccCg lt3X W3Wa AlQQ mf0R' \
--header 'Content-Type: application/json' \
--data-urlencode 'search={"field_filters":[{"key":"date_created","value":"09/10/2019","operator":"is"}]}'