Recipients

Filter recipient worksheet rows

Returns configurable recipient rows for an accessible program or all programs, including title fields and selected custom/system columns. Requires filter even without advanced groups. All-program views can choose recipients/campaigns surface; program preferences and saved views determine defaults. Participation columns require their workflow permission. The result is JSON with total matching length; custom values and dates retain their worksheet display shape. Requires permission: one of manage_programs.

POST

admin

entities

filter

{program_id}

Filter recipient worksheet rows

curl --request POST \
  --url https://api.gratona.com/v1/admin/entities/filter/{program_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": "false",
  "filterGroups": [
    {
      "field": "display_name",
      "operator": "contains",
      "value": "<unknown>",
      "logicalOperator": "AND"
    }
  ],
  "query": "Jane",
  "keysArray": [
    "display_name"
  ],
  "comparisonOperator": "contains",
  "savedFilterId": 42,
  "saved_filter_id": 42,
  "fields": [
    "display_name"
  ],
  "column_order": [
    "display_name"
  ],
  "sortKey": "display_name",
  "sortOrder": "asc",
  "pageIndex": 1,
  "pageSize": 25,
  "date_from": "2026-01-01",
  "date_to": "2026-10-20",
  "program_surface": "recipients"
}
'

import requests

url = "https://api.gratona.com/v1/admin/entities/filter/{program_id}"

payload = {
    "filter": "false",
    "filterGroups": [
        {
            "field": "display_name",
            "operator": "contains",
            "value": "<unknown>",
            "logicalOperator": "AND"
        }
    ],
    "query": "Jane",
    "keysArray": ["display_name"],
    "comparisonOperator": "contains",
    "savedFilterId": 42,
    "saved_filter_id": 42,
    "fields": ["display_name"],
    "column_order": ["display_name"],
    "sortKey": "display_name",
    "sortOrder": "asc",
    "pageIndex": 1,
    "pageSize": 25,
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "program_surface": "recipients"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filter: 'false',
    filterGroups: [
      {
        field: 'display_name',
        operator: 'contains',
        value: '<unknown>',
        logicalOperator: 'AND'
      }
    ],
    query: 'Jane',
    keysArray: ['display_name'],
    comparisonOperator: 'contains',
    savedFilterId: 42,
    saved_filter_id: 42,
    fields: ['display_name'],
    column_order: ['display_name'],
    sortKey: 'display_name',
    sortOrder: 'asc',
    pageIndex: 1,
    pageSize: 25,
    date_from: '2026-01-01',
    date_to: '2026-10-20',
    program_surface: 'recipients'
  })
};

fetch('https://api.gratona.com/v1/admin/entities/filter/{program_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/entities/filter/{program_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => 'false',
    'filterGroups' => [
        [
                'field' => 'display_name',
                'operator' => 'contains',
                'value' => '<unknown>',
                'logicalOperator' => 'AND'
        ]
    ],
    'query' => 'Jane',
    'keysArray' => [
        'display_name'
    ],
    'comparisonOperator' => 'contains',
    'savedFilterId' => 42,
    'saved_filter_id' => 42,
    'fields' => [
        'display_name'
    ],
    'column_order' => [
        'display_name'
    ],
    'sortKey' => 'display_name',
    'sortOrder' => 'asc',
    'pageIndex' => 1,
    'pageSize' => 25,
    'date_from' => '2026-01-01',
    'date_to' => '2026-10-20',
    'program_surface' => 'recipients'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/entities/filter/{program_id}"

	payload := strings.NewReader("{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/entities/filter/{program_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/entities/filter/{program_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": 42,
      "display_name": "Jane Recipient",
      "name": "Jane Recipient",
      "files_count": 42,
      "date_added": "Oct 20, 2026",
      "date_updated": "Oct 20, 2026",
      "thumbnail": "https://example.org/thumb.jpg",
      "is_visible": true,
      "is_featured": false,
      "status": "Sponsored",
      "tags": "<unknown>"
    }
  ],
  "length": 42,
  "filter": "<unknown>",
  "applied_filters": {
    "saved_filter_id": 42,
    "saved_filter_name": "Active monthly supporters",
    "filter_groups": [
      {
        "field": "display_name",
        "operator": "contains",
        "value": "<unknown>",
        "logicalOperator": "AND"
      }
    ],
    "fields": [
      "<unknown>"
    ],
    "column_order": [
      "display_name"
    ],
    "page_index": 42,
    "page_size": 42,
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "query": "Jane",
    "sort_key": "display_name",
    "sort_order": "asc",
    "sort": {
      "key": "display_name",
      "order": "asc"
    },
    "footer_calculations": [
      {}
    ]
  }
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

Authorizations

Authorization

string

header

required

Passport bearer token authentication for legacy admin sessions.

Path Parameters

program_id

required

Accessible program id or all programs. Footer/export also accept0 for the combined context.

Example:

42

Body

application/json

Validated request fields for this operation.

Recipient worksheet state. filter is always required, including legacy requests. A supplied filterGroups array must be nonempty. Presence operators isUnknown, hasAnyValue and isEmpty omit value; other groups require it.

filter

string

required

Archived-view selector. Use string false for active and true for archived. Recipient views also support available, sponsored and unsponsored.

Example:

"false"

filterGroups

object[]

Multiple typed comparisons. Requires filter when present; value is required except supported presence/empty operators. Saved-view filters are sanitized to current allowed fields.

Show child attributes

query

string

Worksheet search text; recipient search defaults to title/id fields when keysArray is absent.

Example:

"Jane"

keysArray

string[]

Legacy comparison/search field keys.

comparisonOperator

string

Legacy single comparison operator.

Example:

"contains"

savedFilterId

integer

Saved view/report from this organization and worksheet module; missing/unmatched ids are ignored.

Example:

42

saved_filter_id

integer

Compatibility alias for savedFilterId.

Example:

42

fields

string[]

Selected column keys; defaults to saved/current form preferences.

column_order

string[]

Preferred allowed column ordering.

sortKey

string

Allowed selected/system/custom sort key.

Example:

"display_name"

sortOrder

enum<string>

Sort direction; unsupported directions normalize to asc where validated.

Available options:

asc,

desc

Example:

"asc"

pageIndex

integer

One-based worksheet page. Supply with pageSize for predictable bounded pagination.

Example:

1

pageSize

integer

Requested worksheet page length; donor lists default to10 and clamp to at least1.

Example:

25

date_from

string<date>

Lower date bound, interpreted with module/saved report date semantics.

Example:

"2026-01-01"

date_to

string<date>

Upper date bound; donor created-at range applies when both bounds are supplied and no advanced date override exists.

Example:

"2026-10-20"

program_surface

enum<string>

Combined all-program scope; defaults recipients. Campaigns selects campaign programs.

Available options:

recipients,

campaigns

Example:

"recipients"

Response

Operation result.

length is total matching rows, not this page length. Row shape follows the current form and selected columns.

data

object[]

required

Show child attributes

length

integer

required

Required range: x >= 0

Example:

42

filter

any

required

Echoed active/archive selector; string, boolean or null depending on request/defaults.

applied_filters

object | null

required

Resolved saved/manual filter or column-order metadata; null when no applicable configuration exists. Additional fields include saved date range, selected tab and form-specific context. Recipient views can include general column preferences even without a saved filter.

Show child attributes

Filter recipient worksheet rows

curl --request POST \
  --url https://api.gratona.com/v1/admin/entities/filter/{program_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": "false",
  "filterGroups": [
    {
      "field": "display_name",
      "operator": "contains",
      "value": "<unknown>",
      "logicalOperator": "AND"
    }
  ],
  "query": "Jane",
  "keysArray": [
    "display_name"
  ],
  "comparisonOperator": "contains",
  "savedFilterId": 42,
  "saved_filter_id": 42,
  "fields": [
    "display_name"
  ],
  "column_order": [
    "display_name"
  ],
  "sortKey": "display_name",
  "sortOrder": "asc",
  "pageIndex": 1,
  "pageSize": 25,
  "date_from": "2026-01-01",
  "date_to": "2026-10-20",
  "program_surface": "recipients"
}
'

import requests

url = "https://api.gratona.com/v1/admin/entities/filter/{program_id}"

payload = {
    "filter": "false",
    "filterGroups": [
        {
            "field": "display_name",
            "operator": "contains",
            "value": "<unknown>",
            "logicalOperator": "AND"
        }
    ],
    "query": "Jane",
    "keysArray": ["display_name"],
    "comparisonOperator": "contains",
    "savedFilterId": 42,
    "saved_filter_id": 42,
    "fields": ["display_name"],
    "column_order": ["display_name"],
    "sortKey": "display_name",
    "sortOrder": "asc",
    "pageIndex": 1,
    "pageSize": 25,
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "program_surface": "recipients"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filter: 'false',
    filterGroups: [
      {
        field: 'display_name',
        operator: 'contains',
        value: '<unknown>',
        logicalOperator: 'AND'
      }
    ],
    query: 'Jane',
    keysArray: ['display_name'],
    comparisonOperator: 'contains',
    savedFilterId: 42,
    saved_filter_id: 42,
    fields: ['display_name'],
    column_order: ['display_name'],
    sortKey: 'display_name',
    sortOrder: 'asc',
    pageIndex: 1,
    pageSize: 25,
    date_from: '2026-01-01',
    date_to: '2026-10-20',
    program_surface: 'recipients'
  })
};

fetch('https://api.gratona.com/v1/admin/entities/filter/{program_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/entities/filter/{program_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filter' => 'false',
    'filterGroups' => [
        [
                'field' => 'display_name',
                'operator' => 'contains',
                'value' => '<unknown>',
                'logicalOperator' => 'AND'
        ]
    ],
    'query' => 'Jane',
    'keysArray' => [
        'display_name'
    ],
    'comparisonOperator' => 'contains',
    'savedFilterId' => 42,
    'saved_filter_id' => 42,
    'fields' => [
        'display_name'
    ],
    'column_order' => [
        'display_name'
    ],
    'sortKey' => 'display_name',
    'sortOrder' => 'asc',
    'pageIndex' => 1,
    'pageSize' => 25,
    'date_from' => '2026-01-01',
    'date_to' => '2026-10-20',
    'program_surface' => 'recipients'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/entities/filter/{program_id}"

	payload := strings.NewReader("{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gratona.com/v1/admin/entities/filter/{program_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/entities/filter/{program_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filter\": \"false\",\n  \"filterGroups\": [\n    {\n      \"field\": \"display_name\",\n      \"operator\": \"contains\",\n      \"value\": \"<unknown>\",\n      \"logicalOperator\": \"AND\"\n    }\n  ],\n  \"query\": \"Jane\",\n  \"keysArray\": [\n    \"display_name\"\n  ],\n  \"comparisonOperator\": \"contains\",\n  \"savedFilterId\": 42,\n  \"saved_filter_id\": 42,\n  \"fields\": [\n    \"display_name\"\n  ],\n  \"column_order\": [\n    \"display_name\"\n  ],\n  \"sortKey\": \"display_name\",\n  \"sortOrder\": \"asc\",\n  \"pageIndex\": 1,\n  \"pageSize\": 25,\n  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": 42,
      "display_name": "Jane Recipient",
      "name": "Jane Recipient",
      "files_count": 42,
      "date_added": "Oct 20, 2026",
      "date_updated": "Oct 20, 2026",
      "thumbnail": "https://example.org/thumb.jpg",
      "is_visible": true,
      "is_featured": false,
      "status": "Sponsored",
      "tags": "<unknown>"
    }
  ],
  "length": 42,
  "filter": "<unknown>",
  "applied_filters": {
    "saved_filter_id": 42,
    "saved_filter_name": "Active monthly supporters",
    "filter_groups": [
      {
        "field": "display_name",
        "operator": "contains",
        "value": "<unknown>",
        "logicalOperator": "AND"
      }
    ],
    "fields": [
      "<unknown>"
    ],
    "column_order": [
      "display_name"
    ],
    "page_index": 42,
    "page_size": 42,
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "query": "Jane",
    "sort_key": "display_name",
    "sort_order": "asc",
    "sort": {
      "key": "display_name",
      "order": "asc"
    },
    "footer_calculations": [
      {}
    ]
  }
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}