Skip to content
CommonGrants

Organization

OrganizationBase

Section titled “OrganizationBase”

An organization that can apply to or host funding opportunities.

Table

Section titled “Table”
Property Type Required Description
id uuid Yes The organization’s unique identifier.
name string Yes The name this organization is known by; for a legal entity, its legal name.
orgType PCSOrgType No The organization’s type within the Philanthropy Classification System (PCS).
status OrgStatus No Whether the organization exists and operates, or has dissolved or ceased operating.
identifiers OrgIds No Identifiers associated with the organization, keyed by registry code.
addresses AddressCollection No Collection of physical addresses associated with the organization.
phones PhoneCollection No Collection of phone numbers associated with the organization.
emails EmailCollection No Collection of email addresses associated with the organization.
mission string No The organization’s mission statement.
yearFounded calendarYear No The calendar year the organization was founded.
socials OrgSocialLinks No The organization’s social media and web presence links.
aliases array<nonEmptyString> No Other names this organization goes by, without repeats. Added in v0.5.0.
relationships OrgRelationships No The organization’s relationships to other organizations. Added in v0.5.0.
customFields Record<CustomField> No Custom fields for the organization.

aliases lists other names the same organization goes by, such as a trading name or a short form of its legal name, like “Agile Six” or “Agile6” for “Agile Six Applications, Inc.”. It isn’t a history of former names. Some systems instead keep a separate record for each trading name, which points at the legal entity with a dba entry in parents (see OrgHierarchyKindOptions). Don’t list a name in aliases that has its own live trading-name record linked to this organization by a dba entry in either record, parents on the trading-name record or children on this one, so a reader doesn’t count the same name twice. A name can go in aliases when no live dba record for it remains, for example when that record was replaced, as a duplicate or merged record, by the legal entity’s own record. The schema doesn’t check this.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "id": "083b4567-e89d-42c8-a439-6c1234567890",
  "name": "Example Organization",
  "orgType": {
    "term": "Nonprofit",
    "class": "Organization types",
    "code": "UC000000",
    "description": "Nonprofit organization"
  },
  "status": {
    "value": "active",
    "description": "The organization exists and operates"
  },
  "identifiers": {
    "org:us:ein": {
      "registry": {
        "code": "org:us:ein",
        "url": "https://commongrants.org/registries/org-us-ein"
      },
      "id": "191234567"
    },
    "org:us:uei": {
      "registry": {
        "code": "org:us:uei",
        "url": "https://commongrants.org/registries/org-us-uei"
      },
      "id": "ABCD12345678"
    },
    "org:xi:duns": {
      "registry": {
        "code": "org:xi:duns",
        "url": "https://commongrants.org/registries/org-xi-duns"
      },
      "id": "123456789"
    }
  },
  "addresses": {
    "primary": {
      "street1": "456 Main St",
      "street2": "Suite 100",
      "city": "Anytown",
      "stateOrProvince": "CA",
      "country": "US",
      "postalCode": "12345"
    },
    "otherAddresses": {
      "satellite": {
        "street1": "456 Main St",
        "street2": "Suite 100",
        "city": "Anytown",
        "stateOrProvince": "CA",
        "country": "US",
        "postalCode": "12345"
      },
      "international": {
        "street1": "123 Rue Principale",
        "city": "Montreal",
        "stateOrProvince": "QC",
        "country": "CA",
        "postalCode": "H2Y 1C6"
      }
    }
  },
  "phones": {
    "primary": {
      "countryCode": "+1",
      "number": "444-456-1230",
      "isMobile": true
    },
    "fax": {
      "countryCode": "+1",
      "number": "555-123-4567",
      "extension": "123",
      "isMobile": false
    },
    "otherPhones": {
      "support": {
        "countryCode": "+1",
        "number": "333-456-1230",
        "isMobile": false
      },
      "marketing": {
        "countryCode": "+1",
        "number": "444-456-1230",
        "isMobile": true
      }
    }
  },
  "emails": {
    "primary": "info@example.com",
    "otherEmails": {
      "support": "support@example.com",
      "marketing": "marketing@example.com"
    }
  },
  "mission": "To provide support and resources to the community.",
  "yearFounded": "2024",
  "socials": {
    "website": "https://www.example.com",
    "facebook": "https://www.facebook.com/example",
    "twitterOrX": "https://x.com/example",
    "instagram": "https://www.instagram.com/example",
    "linkedin": "https://www.linkedin.com/company/example",
    "otherSocials": {
      "youtube": "https://www.youtube.com/example"
    }
  },
  "aliases": ["Example Org"],
  "relationships": {
    "parents": [
      {
        "org": {
          "id": "01912a8b-7c3d-7891-abcd-ef1234567891",
          "name": "National Reading Network"
        },
        "kind": { "value": "chapter" }
      }
    ]
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added status field
  • Added aliases field
  • Added relationships field
OrganizationBase.yaml
0.4.0
  • Added identifiers field
  • Removed ein field
  • Removed uei field
  • Removed duns field
OrganizationBase.yaml
0.2.0
  • Added OrganizationBase model
OrganizationBase.yaml

OrgIds

Section titled “OrgIds”

A collection of identifiers associated with an organization, keyed by registry code. It extends the generic IdentifierCollection collection with the base identifiers CommonGrants defines for organizations. Additional registries can be published under otherIds.

Table

Section titled “Table”
PropertyTypeRequiredDescription
systemIdSystemIdNoThe hosting system's own identifier for this record.
otherIdsrecord<Identifier>NoAdditional identifiers keyed by their registry code, for registries the protocol does not define as a base identifier on the model.
org:us:einOrgIdEinNoThe organization's Employer Identification Number (EIN), assigned by the IRS.
org:us:ueiOrgIdUeiNoThe organization's Unique Entity Identifier (UEI) from SAM.gov.
org:xi:dunsOrgIdDunsNoThe organization's Data Universal Numbering System (DUNS) number.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "org:us:ein": {
    "registry": {
      "code": "org:us:ein",
      "url": "https://commongrants.org/registries/org-us-ein"
    },
    "id": "123456789"
  },
  "org:us:uei": {
    "registry": {
      "code": "org:us:uei",
      "url": "https://commongrants.org/registries/org-us-uei"
    },
    "id": "AB0123456789"
  },
  "org:xi:duns": {
    "registry": {
      "code": "org:xi:duns",
      "url": "https://commongrants.org/registries/org-xi-duns"
    },
    "id": "123456789"
  },
  "systemId": {
    "registry": {
      "code": "org:grants.gov:system",
      "url": "https://commongrants.org/registries/org-grants-gov-system"
    },
    "id": "01912a8b-7c3d-7890-abcd-ef1234567890"
  },
  "otherIds": {
    "org:candid:bridge": {
      "registry": {
        "code": "org:candid:bridge"
      },
      "id": "1234567"
    }
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgIds model
OrgIds.yaml

OrgIdEin

Section titled “OrgIdEin”

An organization’s Employer Identification Number (EIN), assigned by the IRS. It pins registry.code to org:us:ein and constrains the identifier value to the employerTaxId format.

Table

Section titled “Table”
PropertyTypeRequiredDescription
registryrecordNoRegistry-level facts shared by every record in this registry.
idemployerTaxIdNoThe primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIdsarray<object>NoEvery known identifier for this record in this registry, including archived values.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "registry": {
    "code": "org:us:ein",
    "url": "https://commongrants.org/registries/org-us-ein"
  },
  "id": "123456789"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgIdEin model
OrgIdEin.yaml

OrgIdUei

Section titled “OrgIdUei”

An organization’s Unique Entity Identifier (UEI) from SAM.gov. It pins registry.code to org:us:uei and constrains the identifier value to the samUEI format.

Table

Section titled “Table”
PropertyTypeRequiredDescription
registryrecordNoRegistry-level facts shared by every record in this registry.
idsamUEINoThe primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIdsarray<object>NoEvery known identifier for this record in this registry, including archived values.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "registry": {
    "code": "org:us:uei",
    "url": "https://commongrants.org/registries/org-us-uei"
  },
  "id": "AB0123456789"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgIdUei model
OrgIdUei.yaml

OrgIdDuns

Section titled “OrgIdDuns”

An organization’s Data Universal Numbering System (DUNS) number. It pins registry.code to org:xi:duns and constrains the identifier value to the duns format.

Table

Section titled “Table”
PropertyTypeRequiredDescription
registryrecordNoRegistry-level facts shared by every record in this registry.
iddunsNoThe primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIdsarray<object>NoEvery known identifier for this record in this registry, including archived values.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "registry": {
    "code": "org:xi:duns",
    "url": "https://commongrants.org/registries/org-xi-duns"
  },
  "id": "123456789"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgIdDuns model
OrgIdDuns.yaml

OrgRef

Section titled “OrgRef”

A reference to an organization, previewing the key fields a consumer needs to identify it and look it up or join it to another response. Appears wherever another record points to an organization, such as an award’s or an opportunity’s funder or recipient.

Table

Section titled “Table”
PropertyTypeRequiredDescription
iduuidYesThe organization's unique identifier.
namestringYesThe name this organization is known by; for a legal entity, its legal name.
identifiersOrgIdsNoIdentifiers associated with the organization, keyed by registry code.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "id": "018f2e77-4b5c-7d2e-9f3a-bcdef1234567",
  "name": "Health Resources and Services Administration",
  "identifiers": {
    "otherIds": {
      "org:grants.gov:agency": {
        "registry": {
          "code": "org:grants.gov:agency"
        },
        "id": "HRSA"
      }
    }
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added identifiers field
OrgRef.yaml
0.2.0
  • Added OrgRef model
OrgRef.yaml

OrgRefCollection

Section titled “OrgRefCollection”

A group of organization references, with a primary organization and optional others. Appears wherever several organizations share a role on a record, such as an award’s or opportunity’s funders, or an award’s recipient organizations.

Table

Section titled “Table”
PropertyTypeRequiredDescription
primaryOrgRefYesThe primary organization in the collection.
otherOrgsrecord<OrgRef>NoOther organizations in the collection, keyed by an implementation-defined role.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "primary": {
    "id": "018f2e77-4b5c-7d2e-9f3a-bcdef1234567",
    "name": "Health Resources and Services Administration",
    "identifiers": {
      "otherIds": {
        "org:grants.gov:agency": {
          "registry": {
            "code": "org:grants.gov:agency"
          },
          "id": "HRSA"
        }
      }
    }
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgRefCollection model
OrgRefCollection.yaml

OrgRelationships

Section titled “OrgRelationships”

An organization’s relationships to other organizations, added in v0.5.0 per ADR 0030. Each named list holds relationships of one category and direction, and otherRelationships holds connections outside those categories, which need not have a direction. Every list is optional, list order carries no meaning, and a provider can state a relationship from whichever organization’s record it maintains. The protocol doesn’t require reverse entries, complete lists, or agreement between the two sides. A relationship confers no authority over the other organization. See Organization relationships for worked examples.

List Entry Each entry says
parents OrgHierarchyRelationship org is above this organization
children OrgHierarchyRelationship org is below this organization
succeededBy OrgSuccessionRelationship org carries on all or part of this organization
succeeds OrgSuccessionRelationship This organization carries on all or part of org
recordReplacedBy OrgRecordRelationship org’s record should be used instead of this record
recordReplaces OrgRecordRelationship This record should be used instead of org’s record
otherRelationships OrgOtherRelationship This organization is connected to org, possibly with no direction

On reads, relationships, each list, aliases, and an entry’s optional members are omitted when not provided; none accepts null. An empty array is a present, empty list. The schema validates shape only: it doesn’t check whether the other organization exists or whether two records agree.

Table

Section titled “Table”
PropertyTypeRequiredDescription
parentsarray<OrgHierarchyRelationship>NoOrganizations above this one, such as a containing organization or a fiscal sponsor.
childrenarray<OrgHierarchyRelationship>NoOrganizations below this one, such as its chapters or sponsored projects.
succeededByarray<OrgSuccessionRelationship>NoOrganizations that carry on all or part of this one.
succeedsarray<OrgSuccessionRelationship>NoOrganizations whose work this one carries on in whole or in part.
recordReplacedByarray<OrgRecordRelationship>NoRecords to use instead of this record.
recordReplacesarray<OrgRecordRelationship>NoRecords that this record is used instead of.
otherRelationshipsarray<OrgOtherRelationship>NoConnections outside the categories above, which need not have a direction.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "parents": [
    {
      "org": {
        "id": "01912a8b-7c3d-7891-abcd-ef1234567891",
        "name": "National Reading Network"
      },
      "kind": {
        "value": "chapter"
      }
    },
    {
      "org": {
        "id": "01912a8b-7c3d-7892-abcd-ef1234567892",
        "name": "Riverside Community Foundation",
        "identifiers": {
          "org:us:ein": {
            "registry": {
              "code": "org:us:ein"
            },
            "id": "472345678"
          }
        }
      },
      "kind": {
        "value": "fiscalSponsor"
      },
      "startDate": "2024-07-01",
      "status": "active"
    }
  ]
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgRelationships model
OrgRelationships.yaml

OrgHierarchyRelationship

Section titled “OrgHierarchyRelationship”

A parent or child relationship, added in v0.5.0. Every relationship list uses the same entry shape, defined once as a template; the entries differ only in the standard subtypes kind accepts.

  • org is required and is an OrgRef. In a patch, org.id is writable and the rest is optional, so a writer can name the other organization by id alone. The receiver rejects an id it doesn’t recognize, ignores a supplied name or identifiers, and fills both in from its own record on reads and revision snapshots. Validation doesn’t look up or fill in the target.
  • kind is optional. It is an extensible enum whose value is one of OrgHierarchyKindOptions, or custom with the subtype in customValue. description is optional.
  • startDate and endDate are optional YYYY-MM-DD dates.
  • None of these members accepts null; an unstated member is omitted.
  • status is optional and is one of OrgRelationshipStatus. It describes the relationship, not either organization. It has no default and isn’t derived from the dates, and the protocol requires no particular combination of dates and status.

An entry with only org is valid. Parents and children cover more than containment: a fiscal sponsor is a parent of kind fiscalSponsor, so not every parent owns or contains its child.

Table

Section titled “Table”
PropertyTypeRequiredDescription
orgOrgRefYesThe other organization.
kindrecordNoThe relationship's subtype within the category its list names.
startDateisoDateNoWhen the relationship started, in ISO 8601 format: YYYY-MM-DD
endDateisoDateNoWhen the relationship ended, in ISO 8601 format: YYYY-MM-DD
statusOrgRelationshipStatusNoWhether the relationship is in effect, as stated by the provider.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "org": {
    "id": "01912a8b-7c3d-7892-abcd-ef1234567892",
    "name": "Riverside Community Foundation",
    "identifiers": {
      "org:us:ein": {
        "registry": {
          "code": "org:us:ein"
        },
        "id": "472345678"
      }
    }
  },
  "kind": {
    "value": "fiscalSponsor"
  },
  "startDate": "2024-07-01",
  "status": "active"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgHierarchyRelationship model
OrgHierarchyRelationship.yaml

OrgSuccessionRelationship

Section titled “OrgSuccessionRelationship”

A succession relationship, added in v0.5.0, with the same shape as OrgHierarchyRelationship. kind.value is one of OrgSuccessionKindOptions or custom. Succession is about organizations; a rename is not succession.

Table

Section titled “Table”
PropertyTypeRequiredDescription
orgOrgRefYesThe other organization.
kindrecordNoThe relationship's subtype within the category its list names.
startDateisoDateNoWhen the relationship started, in ISO 8601 format: YYYY-MM-DD
endDateisoDateNoWhen the relationship ended, in ISO 8601 format: YYYY-MM-DD
statusOrgRelationshipStatusNoWhether the relationship is in effect, as stated by the provider.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "org": {
    "id": "01912a8b-7c3d-7893-abcd-ef1234567893",
    "name": "Riverside Reading East"
  },
  "kind": {
    "value": "split"
  },
  "startDate": "2026-01-01"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgSuccessionRelationship model
OrgSuccessionRelationship.yaml

OrgRecordRelationship

Section titled “OrgRecordRelationship”

A record replacement relationship, added in v0.5.0, with the same shape as OrgHierarchyRelationship. kind.value is one of OrgRecordKindOptions or custom. Record replacement is about records in a provider’s system, not organizations; the protocol doesn’t prescribe how a provider merges, deletes, or redirects records.

Table

Section titled “Table”
PropertyTypeRequiredDescription
orgOrgRefYesThe other organization.
kindrecordNoThe relationship's subtype within the category its list names.
startDateisoDateNoWhen the relationship started, in ISO 8601 format: YYYY-MM-DD
endDateisoDateNoWhen the relationship ended, in ISO 8601 format: YYYY-MM-DD
statusOrgRelationshipStatusNoWhether the relationship is in effect, as stated by the provider.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "org": {
    "id": "01912a8b-7c3d-7894-abcd-ef1234567894",
    "name": "Riverside Reading Project"
  },
  "kind": {
    "value": "duplicate"
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgRecordRelationship model
OrgRecordRelationship.yaml

OrgOtherRelationship

Section titled “OrgOtherRelationship”

A relationship outside the named categories, added in v0.5.0, with the same shape as OrgHierarchyRelationship. It need not have a direction. It defines no standard subtypes, so a stated kind is always custom, and an entry with only org is valid.

Table

Section titled “Table”
PropertyTypeRequiredDescription
orgOrgRefYesThe other organization.
kindrecordNoThe relationship's subtype within the category its list names.
startDateisoDateNoWhen the relationship started, in ISO 8601 format: YYYY-MM-DD
endDateisoDateNoWhen the relationship ended, in ISO 8601 format: YYYY-MM-DD
statusOrgRelationshipStatusNoWhether the relationship is in effect, as stated by the provider.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "org": {
    "id": "01912a8b-7c3d-7895-abcd-ef1234567895",
    "name": "Riverside Literacy Coalition"
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgOtherRelationship model
OrgOtherRelationship.yaml

OrgHierarchyKindOptions

Section titled “OrgHierarchyKindOptions”

The standard subtypes of a parent or child relationship, added in v0.5.0. dba is for systems that keep a separate record per trading name: in parents, it means this record is a name the referenced legal entity does business under, and in children, that the referenced record is a trading-name record of this one. Most systems list trading names in the legal entity’s aliases instead. Don’t list a name in aliases that has its own live trading-name record linked to this organization by a dba entry in either record, parents on the trading-name record or children on this one, so a reader doesn’t count the same name twice. A name can go in aliases when no live dba record for it remains, for example when that record was replaced, as a duplicate or merged record, by the legal entity’s own record. The schema doesn’t check this. department names an internal unit; it isn’t defined to cover every internal level, such as a division or agency, which a provider can name with a custom kind. There is no generic parent value: an entry without kind already states a parent or child relationship.

Table

Section titled “Table”
ValueDescription
chapterThe child is a chapter of the parent
departmentThe child is an internal unit of the parent
branchThe child is a branch of the parent
subsidiaryThe child is a subsidiary of the parent
fiscalSponsorThe parent fiscally sponsors the child
dbaThe child is a record for a name the parent, a legal entity, does business under
customAnother subtype, named in `customValue`

Formats

Section titled “Formats”

A JSON example of this model.

"chapter"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgHierarchyKindOptions enum
OrgHierarchyKindOptions.yaml

OrgSuccessionKindOptions

Section titled “OrgSuccessionKindOptions”

The standard subtypes of organizational succession, added in v0.5.0.

Table

Section titled “Table”
ValueDescription
mergerSuccession through a merger
acquisitionSuccession through an acquisition
divestitureSuccession through a divestiture
splitSuccession through a split into several organizations
customAnother subtype, named in `customValue`

Formats

Section titled “Formats”

A JSON example of this model.

"merger"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgSuccessionKindOptions enum
OrgSuccessionKindOptions.yaml

OrgRecordKindOptions

Section titled “OrgRecordKindOptions”

The standard subtypes of record replacement, added in v0.5.0. A provider’s workflow may treat duplicate and merged alike; they need not be exclusive.

Table

Section titled “Table”
ValueDescription
duplicateThe records duplicate each other
mergedThe provider combined the records
customAnother subtype, named in `customValue`

Formats

Section titled “Formats”

A JSON example of this model.

"duplicate"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgRecordKindOptions enum
OrgRecordKindOptions.yaml

OrgOtherKindOptions

Section titled “OrgOtherKindOptions”

The subtypes of an OrgOtherRelationship, added in v0.5.0. Only custom is defined, so a stated subtype is given in customValue.

Table

Section titled “Table”
ValueDescription
custom

Formats

Section titled “Formats”

A JSON example of this model.

"custom"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgOtherKindOptions enum
OrgOtherKindOptions.yaml

OrgRelationshipStatus

Section titled “OrgRelationshipStatus”

Whether a relationship is in effect, as stated by the provider, added in v0.5.0. It describes the relationship, not either organization, and isn’t derived from the relationship’s dates.

Table

Section titled “Table”
ValueDescription
active
inactive

Formats

Section titled “Formats”

A JSON example of this model.

"active"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgRelationshipStatus enum
OrgRelationshipStatus.yaml
Section titled “OrgSocialLinks”

A collection of social media and web presence links for an organization.

Table

Section titled “Table”
Property Type Required Description
website url No The organization’s primary website URL.
facebook url No The organization’s Facebook profile URL.
twitterOrX url No The organization’s Twitter/X profile URL.
bluesky url No The organization’s Bluesky profile URL.
instagram url No The organization’s Instagram profile URL.
linkedin url No The organization’s LinkedIn profile URL.
otherSocials Record<url> No Additional social media profiles not covered by the standard fields.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "website": "https://www.example.com",
  "facebook": "https://www.facebook.com/example",
  "twitterOrX": "https://x.com/example",
  "bluesky": "https://bsky.app/profile/example",
  "instagram": "https://www.instagram.com/example",
  "linkedin": "https://www.linkedin.com/company/example",
  "otherSocials": {
    "youtube": "https://www.youtube.com/example",
    "tiktok": "https://tiktok.com/example"
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgSocialLinks model
OrgSocialLinks.yaml

OrgStatus

Section titled “OrgStatus”

The status of an organization:

  • active: The organization exists and operates.
  • inactive: The organization has dissolved or ceased operating. Loss of tax-exempt status alone does not make an organization inactive.
  • custom: A status not covered by the other options, described in customValue.

Table

Section titled “Table”
PropertyTypeRequiredDescription
valueOrgStatusOptionsYesThe selected value, from a predefined set of options
customValuestringNoA custom value, used when the selected value is the `custom` option
descriptionstringNoA human-readable description of the value

Formats

Section titled “Formats”

A JSON example of this model.

{
  "value": "active",
  "description": "The organization exists and operates"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgStatus model
OrgStatus.yaml

OrgStatusOptions

Section titled “OrgStatusOptions”

The set of values accepted for organization status.

Table

Section titled “Table”
ValueDescription
activeThe organization exists and operates
inactiveThe organization has dissolved or ceased operating; loss of tax-exempt status alone does not make an organization inactive
customA status not covered by the other options, described in `customValue`

Formats

Section titled “Formats”

A JSON example of this model.

"active"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added OrgStatusOptions enum
OrgStatusOptions.yaml

OrgPatchData

Section titled “OrgPatchData”

A JSON Merge Patch body for updating an organization profile, used by the PATCH /orgs/{orgId} and POST /orgs/{orgId}/changes routes. It is derived from OrganizationBase: every field is optional, so a client sends only the fields it wants to change, clearable fields accept null to remove them, and read-only fields like id are excluded. Nested objects are themselves partial, so { "socials": { "website": null } } clears just the website and leaves the other links untouched. Sent with a Content-Type of application/merge-patch+json.

From v0.5.0, relationships follows the same rules. Each relationship list is an array that a patch replaces whole, so { "relationships": { "parents": [...] } } replaces only parents and leaves the other lists unchanged. null removes the addressed list, or every list when sent for relationships, and [] leaves a present, empty list. There is no append, merge by ID, single-entry change, or automatic reverse entry, so a writer changes one entry by sending its whole list with whole entries. In a patch, an entry’s org has a writable id and an optional name and identifiers, so it can name the other organization by id alone. The receiver rejects an id it doesn’t recognize, ignores a supplied name or identifiers, and fills both in from its own record on reads and revision snapshots, so a writer can also resend entries copied from a read. A revision’s patch is recorded as received, so a target name or identifiers there isn’t authoritative; reads and the revision’s snapshot carry the filled-in values. Validation doesn’t look up or fill in the target. aliases is an array and is also replaced whole, and null removes it. Apart from the target’s name and identifiers, a replaced list’s entries are stored as written, so an entry’s optional kind, dates, and status are omitted rather than set to null.

Table

Section titled “Table”
PropertyTypeRequiredDescription
namestringNoThe name this organization is known by; for a legal entity, its legal name.
statusOrgPatchOrgStatusOrCreate or nullNoWhether the organization exists and operates, or has dissolved or ceased operating.
missionstring or nullNoThe organization's mission statement.
yearFoundedcalendarYear or nullNoThe calendar year the organization was founded.
aliasesarray<nonEmptyString> or nullNoOther names this organization goes by, such as a trading name or a short form of its legal name. Not a history of former names. Don't list a name that has its own live trading-name record linked to this organization by a `dba` entry in either record; see the organization relationships guide.
identifiersrecord or nullNoIdentifiers associated with the organization, keyed by registry code.
orgTyperecord or nullNoThe organization's type within the Philanthropy Classification System (PCS).
addressesrecord or nullNoCollection of physical addresses associated with the organization.
phonesrecord or nullNoCollection of phone numbers associated with the organization.
emailsrecord or nullNoCollection of email addresses associated with the organization.
socialsrecord or nullNoCollection of the organization's social media and web presence links.
relationshipsrecord or nullNoThe organization's relationships to other organizations.
customFieldsrecord or nullNoCustom fields for the organization.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "name": "Example Nonprofit (Renamed)",
  "mission": "To expand access to community health resources.",
  "yearFounded": null,
  "socials": {
    "website": null
  },
  "emails": {
    "primary": "info@example.org"
  },
  "customFields": {
    "legacyCode": null
  }
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.5.0
  • Added status field
  • Added aliases field
  • Added relationships field
OrgPatchData.yaml
0.4.0
  • Added OrgPatchData model
OrgPatchData.yaml