Preview existing recipient tags before replacement
Returns current tags/counts for selected tenant recipients without modifying them. Explicit ids are normalized; active foreign-program/denied recipients cause403 and missing ids are ignored at lookup. entity_ids=all resolves current worksheet selection with search/saved filters in250-row pages; program_id is required for a nonempty all selection. Proposed values.tags is checked for comma-containing array names but does not affect counts. Requires permission: one of manage_programs.
curl --request POST \
--url https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entity_ids": [
42
],
"program_id": 42,
"query": "Jane",
"savedFilterId": 42,
"filterGroups": [
{}
],
"fields": [
"name"
],
"filter": true,
"status": "current",
"values": {
"tags": [
"Education"
]
}
}
'import requests
url = "https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview"
payload = {
"entity_ids": [42],
"program_id": 42,
"query": "Jane",
"savedFilterId": 42,
"filterGroups": [{}],
"fields": ["name"],
"filter": True,
"status": "current",
"values": { "tags": ["Education"] }
}
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({
entity_ids: [42],
program_id: 42,
query: 'Jane',
savedFilterId: 42,
filterGroups: [{}],
fields: ['name'],
filter: true,
status: 'current',
values: {tags: ['Education']}
})
};
fetch('https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview', 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/program/entities/tags/replacement-preview",
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([
'entity_ids' => [
42
],
'program_id' => 42,
'query' => 'Jane',
'savedFilterId' => 42,
'filterGroups' => [
[
]
],
'fields' => [
'name'
],
'filter' => true,
'status' => 'current',
'values' => [
'tags' => [
'Education'
]
]
]),
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/program/entities/tags/replacement-preview"
payload := strings.NewReader("{\n \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\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/program/entities/tags/replacement-preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview")
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 \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"record_count": 1,
"records_with_tags": 1,
"records_without_tags": 1,
"tags": [
{
"name": "Education",
"count": 1
}
]
}
}{
"message": "Unauthorized",
"status": "error"
}{
"errors": {},
"status": "error",
"message": "The given data was invalid."
}Authorizations
Passport bearer token authentication for legacy admin sessions.
Body
Validated request fields for this operation.
Current program selection or all programs.
42
Current worksheet search for all selection.
"Jane"
42
Current worksheet filter groups passed to filtered all selection.
Show child attributes
Show child attributes
Current worksheet selected fields; also triggers filtered sponsorship resolution.
True for true, integer1 or case-insensitive1/true/on/yes; otherwise false.
true
current, due "current"
Show child attributes
Show child attributes
Response
Operation result.
Existing selected tags and occurrence counts, descending count then case-insensitive name. Proposed replacement values are not applied.
Show child attributes
Show child attributes
curl --request POST \
--url https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entity_ids": [
42
],
"program_id": 42,
"query": "Jane",
"savedFilterId": 42,
"filterGroups": [
{}
],
"fields": [
"name"
],
"filter": true,
"status": "current",
"values": {
"tags": [
"Education"
]
}
}
'import requests
url = "https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview"
payload = {
"entity_ids": [42],
"program_id": 42,
"query": "Jane",
"savedFilterId": 42,
"filterGroups": [{}],
"fields": ["name"],
"filter": True,
"status": "current",
"values": { "tags": ["Education"] }
}
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({
entity_ids: [42],
program_id: 42,
query: 'Jane',
savedFilterId: 42,
filterGroups: [{}],
fields: ['name'],
filter: true,
status: 'current',
values: {tags: ['Education']}
})
};
fetch('https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview', 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/program/entities/tags/replacement-preview",
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([
'entity_ids' => [
42
],
'program_id' => 42,
'query' => 'Jane',
'savedFilterId' => 42,
'filterGroups' => [
[
]
],
'fields' => [
'name'
],
'filter' => true,
'status' => 'current',
'values' => [
'tags' => [
'Education'
]
]
]),
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/program/entities/tags/replacement-preview"
payload := strings.NewReader("{\n \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\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/program/entities/tags/replacement-preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gratona.com/v1/admin/program/entities/tags/replacement-preview")
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 \"entity_ids\": [\n 42\n ],\n \"program_id\": 42,\n \"query\": \"Jane\",\n \"savedFilterId\": 42,\n \"filterGroups\": [\n {}\n ],\n \"fields\": [\n \"name\"\n ],\n \"filter\": true,\n \"status\": \"current\",\n \"values\": {\n \"tags\": [\n \"Education\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"record_count": 1,
"records_with_tags": 1,
"records_without_tags": 1,
"tags": [
{
"name": "Education",
"count": 1
}
]
}
}{
"message": "Unauthorized",
"status": "error"
}{
"errors": {},
"status": "error",
"message": "The given data was invalid."
}