Donations

Create, link, or convert a giving institution

Requires daf_qcd_giving_v1 and donor-form mutation access. Supply at least one of existing_donor_id, catalog_key, organization_name; conversion takes priority, then catalog key, then manual name. New directory/manual organization records have no personal/login identity and email is suppressed. Reuses compatible accessible existing institutions; a deleted linked record is not restored. Conversion preserves history/contact details and disables portal eligibility; already-marked institutions are reused without changing role. Directory role must match; saved grant/advisor/custodian relationships can prevent conversion. Returns201 only for a new record, otherwise200 with created=false. Requires permission: one of donors_manage.

POST

admin

donors

{hysform_id}

giving-institutions

Create, link, or convert a giving institution

curl --request POST \
  --url https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "existing_donor_id": 1,
  "catalog_key": "example-foundation",
  "organization_name": "Example Giving Foundation",
  "role": "daf_sponsor",
  "street": "Street",
  "address_line2": "Address Line2",
  "city": "City",
  "state": "State",
  "zip": "Zip",
  "country": "Country"
}
'

import requests

url = "https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions"

payload = {
    "existing_donor_id": 1,
    "catalog_key": "example-foundation",
    "organization_name": "Example Giving Foundation",
    "role": "daf_sponsor",
    "street": "Street",
    "address_line2": "Address Line2",
    "city": "City",
    "state": "State",
    "zip": "Zip",
    "country": "Country"
}
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({
    existing_donor_id: 1,
    catalog_key: 'example-foundation',
    organization_name: 'Example Giving Foundation',
    role: 'daf_sponsor',
    street: 'Street',
    address_line2: 'Address Line2',
    city: 'City',
    state: 'State',
    zip: 'Zip',
    country: 'Country'
  })
};

fetch('https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions', 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/donors/{hysform_id}/giving-institutions",
  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([
    'existing_donor_id' => 1,
    'catalog_key' => 'example-foundation',
    'organization_name' => 'Example Giving Foundation',
    'role' => 'daf_sponsor',
    'street' => 'Street',
    'address_line2' => 'Address Line2',
    'city' => 'City',
    'state' => 'State',
    'zip' => 'Zip',
    'country' => 'Country'
  ]),
  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/donors/{hysform_id}/giving-institutions"

	payload := strings.NewReader("{\n  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\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/donors/{hysform_id}/giving-institutions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions")

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  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\n}"

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

{
  "data": {
    "id": 42,
    "name": "Example Giving Foundation",
    "legal_name": "Example",
    "former_names": [
      "Former Foundation Name"
    ],
    "aliases": [
      "Foundation Alias"
    ],
    "role": "daf_sponsor",
    "catalog_key": "example-foundation",
    "hysform_id": 42,
    "has_email": true,
    "city": "New York",
    "state": "NY",
    "is_financial_intermediary": true
  },
  "created": true
}

{
  "data": {
    "id": 42,
    "name": "Example Giving Foundation",
    "legal_name": "Example",
    "former_names": [
      "Former Foundation Name"
    ],
    "aliases": [
      "Foundation Alias"
    ],
    "role": "daf_sponsor",
    "catalog_key": "example-foundation",
    "hysform_id": 42,
    "has_email": true,
    "city": "New York",
    "state": "NY",
    "is_financial_intermediary": true
  },
  "created": true
}

{
  "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

hysform_id

integer

required

Hysform id in the current organization.

Body

application/json

Validated request fields for this operation.

Option 1
Option 2
Option 3

At least one organization selection is required. Additional fields are used only for a new manual record.

existing_donor_id

integer

required

Existing donor id. Validation: nullable, integer, required_without_all:catalog_key,organization_name.

Example:

1

catalog_key

string | null

Catalog key. Validation: nullable, string, max:64, required_without_all:organization_name,existing_donor_id.

Maximum string length: 64

Example:

"example-foundation"

organization_name

string | null

Organization name. Validation: nullable, string, max:255, required_without_all:catalog_key,existing_donor_id.

Maximum string length: 255

Example:

"Example Giving Foundation"

role

enum<string> | null

Role. Validation: nullable; allowed values: daf_sponsor, ira_custodian.

Available options:

daf_sponsor,

ira_custodian,

null

Example:

"daf_sponsor"

street

string | null

Street. Validation: nullable, string, max:255.

Maximum string length: 255

Example:

"Street"

address_line2

string | null

Address line2. Validation: nullable, string, max:255.

Maximum string length: 255

Example:

"Address Line2"

city

string | null

City. Validation: nullable, string, max:255.

Maximum string length: 255

Example:

"City"

state

string | null

State. Validation: nullable, string, max:255.

Maximum string length: 255

Example:

"State"

zip

string | null

Zip. Validation: nullable, string, max:50.

Maximum string length: 50

Example:

"Zip"

country

string | null

Country. Validation: nullable, string, max:255.

Maximum string length: 255

Example:

"Country"

Response

Existing institution reused or converted.

data

object

Show child attributes

created

boolean

Example:

true

Create, link, or convert a giving institution

curl --request POST \
  --url https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "existing_donor_id": 1,
  "catalog_key": "example-foundation",
  "organization_name": "Example Giving Foundation",
  "role": "daf_sponsor",
  "street": "Street",
  "address_line2": "Address Line2",
  "city": "City",
  "state": "State",
  "zip": "Zip",
  "country": "Country"
}
'

import requests

url = "https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions"

payload = {
    "existing_donor_id": 1,
    "catalog_key": "example-foundation",
    "organization_name": "Example Giving Foundation",
    "role": "daf_sponsor",
    "street": "Street",
    "address_line2": "Address Line2",
    "city": "City",
    "state": "State",
    "zip": "Zip",
    "country": "Country"
}
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({
    existing_donor_id: 1,
    catalog_key: 'example-foundation',
    organization_name: 'Example Giving Foundation',
    role: 'daf_sponsor',
    street: 'Street',
    address_line2: 'Address Line2',
    city: 'City',
    state: 'State',
    zip: 'Zip',
    country: 'Country'
  })
};

fetch('https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions', 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/donors/{hysform_id}/giving-institutions",
  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([
    'existing_donor_id' => 1,
    'catalog_key' => 'example-foundation',
    'organization_name' => 'Example Giving Foundation',
    'role' => 'daf_sponsor',
    'street' => 'Street',
    'address_line2' => 'Address Line2',
    'city' => 'City',
    'state' => 'State',
    'zip' => 'Zip',
    'country' => 'Country'
  ]),
  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/donors/{hysform_id}/giving-institutions"

	payload := strings.NewReader("{\n  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\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/donors/{hysform_id}/giving-institutions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/donors/{hysform_id}/giving-institutions")

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  \"existing_donor_id\": 1,\n  \"catalog_key\": \"example-foundation\",\n  \"organization_name\": \"Example Giving Foundation\",\n  \"role\": \"daf_sponsor\",\n  \"street\": \"Street\",\n  \"address_line2\": \"Address Line2\",\n  \"city\": \"City\",\n  \"state\": \"State\",\n  \"zip\": \"Zip\",\n  \"country\": \"Country\"\n}"

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

{
  "data": {
    "id": 42,
    "name": "Example Giving Foundation",
    "legal_name": "Example",
    "former_names": [
      "Former Foundation Name"
    ],
    "aliases": [
      "Foundation Alias"
    ],
    "role": "daf_sponsor",
    "catalog_key": "example-foundation",
    "hysform_id": 42,
    "has_email": true,
    "city": "New York",
    "state": "NY",
    "is_financial_intermediary": true
  },
  "created": true
}

{
  "data": {
    "id": 42,
    "name": "Example Giving Foundation",
    "legal_name": "Example",
    "former_names": [
      "Former Foundation Name"
    ],
    "aliases": [
      "Foundation Alias"
    ],
    "role": "daf_sponsor",
    "catalog_key": "example-foundation",
    "hysform_id": 42,
    "has_email": true,
    "city": "New York",
    "state": "NY",
    "is_financial_intermediary": true
  },
  "created": true
}

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

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

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