Create household
curl --request POST \
--url https://api.grainledger.com/api/v1/households \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Johnson Family"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Johnson Family'})
};
fetch('https://api.grainledger.com/api/v1/households', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.grainledger.com/api/v1/households"
payload = { "name": "Johnson Family" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"name": "<string>",
"primaryContactId": "<string>",
"primaryContact": {
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"organizationName": "<string>",
"donorType": "INDIVIDUAL",
"email": "<string>",
"phone": "<string>",
"householdRef": "<string>",
"householdName": "<string>",
"householdPosition": "PRIMARY",
"isPrimaryContact": true,
"membershipStatus": "VISITOR",
"isActive": true,
"totalGiving": 123,
"givingTrend": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"externalIds": [
{
"platform": "<string>",
"externalId": "<string>"
}
],
"members": [
{
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"organizationName": "<string>",
"donorType": "INDIVIDUAL",
"email": "<string>",
"phone": "<string>",
"householdRef": "<string>",
"householdName": "<string>",
"householdPosition": "PRIMARY",
"isPrimaryContact": true,
"membershipStatus": "VISITOR",
"isActive": true,
"totalGiving": 123,
"givingTrend": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"aggregates": {
"memberCount": 123,
"lifetimeGiving": 123,
"lastGiftDate": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}Households
Create household
POST
https://api.grainledger.com
/
api
/
v1
/
households
Create household
curl --request POST \
--url https://api.grainledger.com/api/v1/households \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Johnson Family"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Johnson Family'})
};
fetch('https://api.grainledger.com/api/v1/households', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.grainledger.com/api/v1/households"
payload = { "name": "Johnson Family" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"name": "<string>",
"primaryContactId": "<string>",
"primaryContact": {
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"organizationName": "<string>",
"donorType": "INDIVIDUAL",
"email": "<string>",
"phone": "<string>",
"householdRef": "<string>",
"householdName": "<string>",
"householdPosition": "PRIMARY",
"isPrimaryContact": true,
"membershipStatus": "VISITOR",
"isActive": true,
"totalGiving": 123,
"givingTrend": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"externalIds": [
{
"platform": "<string>",
"externalId": "<string>"
}
],
"members": [
{
"id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"organizationName": "<string>",
"donorType": "INDIVIDUAL",
"email": "<string>",
"phone": "<string>",
"householdRef": "<string>",
"householdName": "<string>",
"householdPosition": "PRIMARY",
"isPrimaryContact": true,
"membershipStatus": "VISITOR",
"isActive": true,
"totalGiving": 123,
"givingTrend": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"aggregates": {
"memberCount": 123,
"lifetimeGiving": 123,
"lastGiftDate": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}{
"code": "forbidden",
"message": "You do not have access to this organization.",
"error": "You do not have access to this organization."
}Authorizations
ApiKeyAuthGrainOAuth2BearerAuth
Organization API key created in Grain Settings → API. The key determines the organization and is limited to its assigned resource scopes. Write scopes imply the corresponding read scope.
Headers
Required with OAuth access tokens. Optional with organization API keys; if supplied, it must match the key's organization.
Body
application/json
Response
Created household
Household detail with a compact member collection, normalized external IDs, primary contact, and live giving aggregates.
Compact donor identity, household, membership, and giving summary used in list and relationship responses.
Hide child attributes
Hide child attributes
Available options:
INDIVIDUAL, HOUSEHOLD, ORGANIZATION, DAF_CUSTODIAN, FOUNDATION, ESTATE Available options:
PRIMARY, SPOUSE, CHILD, OTHER Available options:
VISITOR, REGULAR_ATTENDER, MEMBER, INACTIVE, FORMER Hide child attributes
Hide child attributes
Available options:
INDIVIDUAL, HOUSEHOLD, ORGANIZATION, DAF_CUSTODIAN, FOUNDATION, ESTATE Available options:
PRIMARY, SPOUSE, CHILD, OTHER Available options:
VISITOR, REGULAR_ATTENDER, MEMBER, INACTIVE, FORMER Last modified on August 23, 2026
⌘I