Recipients

Queue a recipient worksheet CSV export

Creates an export artifact, queues CSV generation and records the request in Activity. Applies saved views, current program/surface filters, selected fields/order/labels and participation field access; all or0 exports the combined program context. Returns HTTP200 with queued status, not CSV content. Follow export_id through the export status workflow; the returned status_url is a versionless relative API path. Worker failures/delivery are reported asynchronously. Requires permission: one of programs_view, manage_programs, program-all.

POST

admin

entities

{program_id}

export

Queue a recipient worksheet CSV export

curl --request POST \
  --url https://api.gratona.com/v1/admin/entities/{program_id}/export \
  --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",
  "date_from": "2026-01-01",
  "date_to": "2026-10-20",
  "program_surface": "recipients",
  "export_delivery": "email",
  "column_labels": {}
}
'

import requests

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

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",
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "program_surface": "recipients",
    "export_delivery": "email",
    "column_labels": {}
}
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',
    date_from: '2026-01-01',
    date_to: '2026-10-20',
    program_surface: 'recipients',
    export_delivery: 'email',
    column_labels: {}
  })
};

fetch('https://api.gratona.com/v1/admin/entities/{program_id}/export', 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/{program_id}/export",
  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',
    'date_from' => '2026-01-01',
    'date_to' => '2026-10-20',
    'program_surface' => 'recipients',
    'export_delivery' => 'email',
    'column_labels' => [
        
    ]
  ]),
  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/{program_id}/export"

	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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\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/{program_id}/export")
  .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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\n}"

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

{
  "message": "Export initiated successfully. You will get a notification in Activity when the CSV is ready to download.",
  "status": "queued",
  "export_id": 42,
  "status_url": "/admin/entities/exports/42/status"
}

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

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

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

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"

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"

export_delivery

enum<string>

Use email to request email delivery; omitted/default uses Activity notification/download. Delivery also depends on worker and organization settings.

Available options:

email

Example:

"email"

column_labels

object

Optional field-key to CSV header-label override map.

Show child attributes

Response

Operation result.

message

string

required

Example:

"Export initiated successfully. You will get a notification in Activity when the CSV is ready to download."

status

enum<string>

required

Available options:

queued

Example:

"queued"

export_id

integer

required

Example:

42

status_url

string

required

Example:

"/admin/entities/exports/42/status"

Queue a recipient worksheet CSV export

curl --request POST \
  --url https://api.gratona.com/v1/admin/entities/{program_id}/export \
  --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",
  "date_from": "2026-01-01",
  "date_to": "2026-10-20",
  "program_surface": "recipients",
  "export_delivery": "email",
  "column_labels": {}
}
'

import requests

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

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",
    "date_from": "2026-01-01",
    "date_to": "2026-10-20",
    "program_surface": "recipients",
    "export_delivery": "email",
    "column_labels": {}
}
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',
    date_from: '2026-01-01',
    date_to: '2026-10-20',
    program_surface: 'recipients',
    export_delivery: 'email',
    column_labels: {}
  })
};

fetch('https://api.gratona.com/v1/admin/entities/{program_id}/export', 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/{program_id}/export",
  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',
    'date_from' => '2026-01-01',
    'date_to' => '2026-10-20',
    'program_surface' => 'recipients',
    'export_delivery' => 'email',
    'column_labels' => [
        
    ]
  ]),
  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/{program_id}/export"

	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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\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/{program_id}/export")
  .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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"date_from\": \"2026-01-01\",\n  \"date_to\": \"2026-10-20\",\n  \"program_surface\": \"recipients\",\n  \"export_delivery\": \"email\",\n  \"column_labels\": {}\n}"

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

{
  "message": "Export initiated successfully. You will get a notification in Activity when the CSV is ready to download.",
  "status": "queued",
  "export_id": 42,
  "status_url": "/admin/entities/exports/42/status"
}

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

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