Organization

OrganizationBase

An organization that can apply to or host funding opportunities.

Table

Property	Type	Required	Description
id	uuid	Yes	The organization’s unique identifier.
name	string	Yes	The organization’s legal name as registered with relevant authorities.
orgType	PCSOrgType	No	The organization’s type within the Philanthropy Classification System (PCS).
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.
customFields	Record<CustomField>	No	Custom fields for the organization.

Formats

Example

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"
  },
  "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"
    }
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrganizationBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The organization's unique identifier.
  name:
    type: string
    description: The organization's legal name as registered with relevant authorities.
  identifiers:
    $ref: OrgIds.yaml
    description: Identifiers associated with the organization, keyed by registry code.
  orgType:
    $ref: PCSOrgType.yaml
    description: The organization's type within the Philanthropy Classification System (PCS).
  ein:
    $ref: employerTaxId.yaml
    description: The organization's Employer Identification Number (EIN), a unique identifier assigned by the IRS.
  uei:
    $ref: samUEI.yaml
    description: The organization's Unique Entity Identifier (UEI) from SAM.gov, used for federal contracting.
  duns:
    $ref: duns.yaml
    description: The organization's Data Universal Numbering System (DUNS) number, a unique identifier for businesses.
  addresses:
    $ref: AddressCollection.yaml
    description: Collection of physical addresses associated with the organization.
  phones:
    $ref: PhoneCollection.yaml
    description: Collection of phone numbers associated with the organization.
  emails:
    $ref: EmailCollection.yaml
    description: Collection of email addresses associated with the organization.
  mission:
    type: string
    description: The organization's mission statement.
  yearFounded:
    $ref: calendarYear.yaml
    description: The calendar year the organization was founded.
  socials:
    $ref: OrgSocialLinks.yaml
    description: Collection of the organization's social media and web presence links.
  customFields:
    $ref: "#/$defs/RecordCustomField"
    description: Custom fields for the organization.
required:
  - id
  - name
unevaluatedProperties:
  not: {}
examples:
  - id: 083b4567-e89d-42c8-a439-6c1234567890
    name: Example Organization
    orgType:
      term: Hospital
      class: Organization types
      description: Institutions with the primary purpose of providing in-patient physical and mental health services...
      code: EO000000
    identifiers:
      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
    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
description: An organization that can apply for grants.
$defs:
  RecordCustomField:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: CustomField.yaml

TypeSpec

The TypeSpec code for this model.

/** An organization that can apply for grants. */
@example(Examples.Organization.exampleOrg)
@Versioning.added(CommonGrants.Versions.v0_2)
model OrganizationBase {
  // Identity fields shared with the OrgRef reference model
  ...OrgRef;

  /** The organization's type within the Philanthropy Classification System (PCS). */
  orgType?: Fields.PCSOrgType;

  /** The organization's Employer Identification Number (EIN), a unique identifier assigned by the IRS. */
  @Versioning.removed(CommonGrants.Versions.v0_4)
  ein?: Types.employerTaxId;

  /** The organization's Unique Entity Identifier (UEI) from SAM.gov, used for federal contracting. */
  @Versioning.removed(CommonGrants.Versions.v0_4)
  uei?: Types.samUEI;

  /** The organization's Data Universal Numbering System (DUNS) number, a unique identifier for businesses. */
  @Versioning.removed(CommonGrants.Versions.v0_4)
  duns?: Types.duns;

  /** Collection of physical addresses associated with the organization. */
  addresses?: Fields.AddressCollection;

  /** Collection of phone numbers associated with the organization. */
  phones?: Fields.PhoneCollection;

  /** Collection of email addresses associated with the organization. */
  emails?: Fields.EmailCollection;

  /** The organization's mission statement. */
  mission?: string;

  /** The calendar year the organization was founded. */
  yearFounded?: Types.calendarYear;

  /** Collection of the organization's social media and web presence links. */
  socials?: OrgSocialLinks;

  /** Custom fields for the organization. */
  customFields?: Record<Fields.CustomField>;
}

Changelog

Version	Changes	Schema
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

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

Property	Type	Required	Description
systemId	SystemId	No	The hosting system's own identifier for this record.
otherIds	record<Identifier>	No	Additional identifiers keyed by their registry code, for registries the protocol does not define as a base identifier on the model.
org:us:ein	OrgIdEin	No	The organization's Employer Identification Number (EIN), assigned by the IRS.
org:us:uei	OrgIdUei	No	The organization's Unique Entity Identifier (UEI) from SAM.gov.
org:xi:duns	OrgIdDuns	No	The organization's Data Universal Numbering System (DUNS) number.

Formats

Example

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgIds.yaml
type: object
properties:
  org:us:ein:
    $ref: OrgIdEin.yaml
    description: The organization's Employer Identification Number (EIN), assigned by the IRS.
  org:us:uei:
    $ref: OrgIdUei.yaml
    description: The organization's Unique Entity Identifier (UEI) from SAM.gov.
  org:xi:duns:
    $ref: OrgIdDuns.yaml
    description: The organization's Data Universal Numbering System (DUNS) number.
allOf:
  - $ref: IdentifierCollection.yaml
unevaluatedProperties:
  not: {}
description: |-
  A collection of identifiers associated with an organization.

  Extends the generic identifier collection with the base identifiers CommonGrants
  defines for organizations. Additional registries can be published under `otherIds`.

TypeSpec

The TypeSpec code for this model.

/** A collection of identifiers associated with an organization.
 *
 * Extends the generic identifier collection with the base identifiers CommonGrants
 * defines for organizations. Additional registries can be published under `otherIds`.
 */
@Versioning.added(CommonGrants.Versions.v0_4)
model OrgIds extends Fields.IdentifierCollection {
  /** The organization's Employer Identification Number (EIN), assigned by the IRS. */
  `org:us:ein`?: OrgIdEin;

  /** The organization's Unique Entity Identifier (UEI) from SAM.gov. */
  `org:us:uei`?: OrgIdUei;

  /** The organization's Data Universal Numbering System (DUNS) number. */
  `org:xi:duns`?: OrgIdDuns;
}

Changelog

Version	Changes	Schema
0.4.0	Added OrgIds model	OrgIds.yaml

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

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	employerTaxId	No	The 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.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

Example

A JSON example of this model.

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgIdEin.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        const: org:us:ein
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    $ref: employerTaxId.yaml
    description: |-
      The 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.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          $ref: employerTaxId.yaml
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: org:us:ein
      url: https://commongrants.org/registries/org-us-ein
    id: "123456789"
description: An organization's Employer Identification Number (EIN), assigned by the IRS.

TypeSpec

The TypeSpec code for this model.

/** An organization's Employer Identification Number (EIN), assigned by the IRS. */
@example(Examples.OrgId.ein)
@Versioning.added(CommonGrants.Versions.v0_4)
model OrgIdEin is Fields.IdentifierT<Types.employerTaxId, "org:us:ein">;

Changelog

Version	Changes	Schema
0.4.0	Added OrgIdEin model	OrgIdEin.yaml

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

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	samUEI	No	The 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.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

Example

A JSON example of this model.

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgIdUei.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        const: org:us:uei
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    $ref: samUEI.yaml
    description: |-
      The 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.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          $ref: samUEI.yaml
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: org:us:uei
      url: https://commongrants.org/registries/org-us-uei
    id: AB0123456789
description: An organization's Unique Entity Identifier (UEI) from SAM.gov.

TypeSpec

The TypeSpec code for this model.

/** An organization's Unique Entity Identifier (UEI) from SAM.gov. */
@example(Examples.OrgId.uei)
@Versioning.added(CommonGrants.Versions.v0_4)
model OrgIdUei is Fields.IdentifierT<Types.samUEI, "org:us:uei">;

Changelog

Version	Changes	Schema
0.4.0	Added OrgIdUei model	OrgIdUei.yaml

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

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	duns	No	The 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.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

Example

A JSON example of this model.

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgIdDuns.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        const: org:xi:duns
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    $ref: duns.yaml
    description: |-
      The 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.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          $ref: duns.yaml
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: org:xi:duns
      url: https://commongrants.org/registries/org-xi-duns
    id: "123456789"
description: An organization's Data Universal Numbering System (DUNS) number.

TypeSpec

The TypeSpec code for this model.

/** An organization's Data Universal Numbering System (DUNS) number. */
@example(Examples.OrgId.duns)
@Versioning.added(CommonGrants.Versions.v0_4)
model OrgIdDuns is Fields.IdentifierT<Types.duns, "org:xi:duns">;

Changelog

Version	Changes	Schema
0.4.0	Added OrgIdDuns model	OrgIdDuns.yaml

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 funder or recipient.

Table

Property	Type	Required	Description
id	uuid	Yes	The organization's unique identifier.
name	string	Yes	The organization's legal name as registered with relevant authorities.
identifiers	OrgIds	No	Identifiers associated with the organization, keyed by registry code.

Formats

Example

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgRef.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The organization's unique identifier.
  name:
    type: string
    description: The organization's legal name as registered with relevant authorities.
  identifiers:
    $ref: OrgIds.yaml
    description: Identifiers associated with the organization, keyed by registry code.
required:
  - id
  - name
unevaluatedProperties:
  not: {}
examples:
  - 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
description: |-
  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 funder
  or recipient.

TypeSpec

The TypeSpec code for this model.

/** 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 funder
 * or recipient.
 */
@example(Examples.OrgRef.funder)
@Versioning.added(CommonGrants.Versions.v0_2)
model OrgRef {
  /** The organization's unique identifier. */
  @visibility(Lifecycle.Read)
  id: Types.uuid;

  /** The organization's legal name as registered with relevant authorities. */
  name: string;

  /** Identifiers associated with the organization, keyed by registry code. */
  @Versioning.added(CommonGrants.Versions.v0_4)
  identifiers?: OrgIds;
}

Changelog

Version	Changes	Schema
0.4.0	Added identifiers field	OrgRef.yaml
0.2.0	Added OrgRef model	OrgRef.yaml

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 funders or recipient organizations.

Table

Property	Type	Required	Description
primary	OrgRef	Yes	The primary organization in the collection.
otherOrgs	record<OrgRef>	No	Other organizations in the collection, keyed by an implementation-defined role.

Formats

Example

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgRefCollection.yaml
type: object
properties:
  primary:
    $ref: OrgRef.yaml
    description: The primary organization in the collection.
  otherOrgs:
    $ref: "#/$defs/RecordOrgRef"
    description: Other organizations in the collection, keyed by an implementation-defined role.
required:
  - primary
unevaluatedProperties:
  not: {}
examples:
  - 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
description: |-
  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 funders or recipient organizations.
$defs:
  RecordOrgRef:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: OrgRef.yaml

TypeSpec

The TypeSpec code for this model.

/** 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 funders or recipient organizations.
 */
@example(Examples.OrgRef.funders)
@Versioning.added(CommonGrants.Versions.v0_4)
model OrgRefCollection {
  /** The primary organization in the collection. */
  primary: OrgRef;

  /** Other organizations in the collection, keyed by an implementation-defined role. */
  otherOrgs?: Record<OrgRef>;
}

Changelog

Version	Changes	Schema
0.4.0	Added OrgRefCollection model	OrgRefCollection.yaml

OrgSocialLinks

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

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

Example

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

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgSocialLinks.yaml
type: object
properties:
  website:
    type: string
    format: uri
    description: The organization's primary website URL.
  facebook:
    type: string
    format: uri
    description: The organization's Facebook profile URL.
  twitterOrX:
    type: string
    format: uri
    description: The organization's Twitter/X profile URL.
  bluesky:
    type: string
    format: uri
    description: The organization's BlueSky profile URL.
  instagram:
    type: string
    format: uri
    description: The organization's Instagram profile URL.
  linkedin:
    type: string
    format: uri
    description: The organization's LinkedIn profile URL.
  otherSocials:
    $ref: "#/$defs/RecordUrl"
    description: Additional social media profiles not covered by the standard fields.
unevaluatedProperties:
  not: {}
examples:
  - 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
description: A collection of social media and web presence links for an organization.
$defs:
  RecordUrl:
    type: object
    properties: {}
    unevaluatedProperties:
      type: string
      format: uri

TypeSpec

The TypeSpec code for this model.

/** A collection of social media and web presence links for an organization. */
@example(Examples.Organization.exampleSocials)
@Versioning.added(CommonGrants.Versions.v0_2)
model OrgSocialLinks {
  /** The organization's primary website URL. */
  website?: url;

  /** The organization's Facebook profile URL. */
  facebook?: url;

  /** The organization's Twitter/X profile URL. */
  twitterOrX?: url;

  /** The organization's BlueSky profile URL. */
  bluesky?: url;

  /** The organization's Instagram profile URL. */
  instagram?: url;

  /** The organization's LinkedIn profile URL. */
  linkedin?: url;

  /** Additional social media profiles not covered by the standard fields. */
  otherSocials?: Record<url>;
}

Changelog

Version	Changes	Schema
0.4.0	Added OrgSocialLinks model	OrgSocialLinks.yaml

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.

Table

Property	Type	Required	Description
name	string	No	The organization's legal name as registered with relevant authorities.
mission	string or null	No	The organization's mission statement.
yearFounded	calendarYear or null	No	The calendar year the organization was founded.
identifiers	record or null	No	Identifiers associated with the organization, keyed by registry code.
orgType	record or null	No	The organization's type within the Philanthropy Classification System (PCS).
addresses	record or null	No	Collection of physical addresses associated with the organization.
phones	record or null	No	Collection of phone numbers associated with the organization.
emails	record or null	No	Collection of email addresses associated with the organization.
socials	record or null	No	Collection of the organization's social media and web presence links.
customFields	record or null	No	Custom fields for the organization.

Formats

Example

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
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: OrgPatchData.yaml
type: object
properties:
  name:
    type: string
    description: The organization's legal name as registered with relevant authorities.
  mission:
    anyOf:
      - type: string
      - type: "null"
    description: The organization's mission statement.
  yearFounded:
    anyOf:
      - $ref: calendarYear.yaml
      - type: "null"
    description: The calendar year the organization was founded.
  identifiers:
    anyOf:
      - $ref: "#/$defs/OrgPatchOrgIdsOrCreate"
      - type: "null"
    description: Identifiers associated with the organization, keyed by registry code.
  orgType:
    anyOf:
      - $ref: "#/$defs/OrgPatchPCSOrgTypeOrCreate"
      - type: "null"
    description: The organization's type within the Philanthropy Classification System (PCS).
  addresses:
    anyOf:
      - $ref: "#/$defs/OrgPatchAddressCollectionOrCreate"
      - type: "null"
    description: Collection of physical addresses associated with the organization.
  phones:
    anyOf:
      - $ref: "#/$defs/OrgPatchPhoneCollectionOrCreate"
      - type: "null"
    description: Collection of phone numbers associated with the organization.
  emails:
    anyOf:
      - $ref: "#/$defs/OrgPatchEmailCollectionOrCreate"
      - type: "null"
    description: Collection of email addresses associated with the organization.
  socials:
    anyOf:
      - $ref: "#/$defs/OrgPatchOrgSocialLinksOrCreate"
      - type: "null"
    description: Collection of the organization's social media and web presence links.
  customFields:
    anyOf:
      - type: object
        properties: {}
        unevaluatedProperties:
          anyOf:
            - $ref: OrgPatchCustomFieldOrCreate.yaml
            - type: "null"
      - type: "null"
    description: Custom fields for the organization.
unevaluatedProperties:
  not: {}
examples:
  - 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
description: |-
  A JSON Merge Patch (RFC 7396) body for updating an organization profile.

  Derived from `OrganizationBase`: every field is optional, fields that can
  be cleared accept `null` to unset them, record keys can be deleted by
  setting them to `null`, and read-only fields like `id` are excluded.
  Sent as `application/merge-patch+json`.
$defs:
  OrgPatchOrgIdsOrCreate:
    type: object
    properties:
      org:us:ein:
        anyOf:
          - $ref: OrgPatchOrgIdEinOrCreate.yaml
          - type: "null"
        description: The organization's Employer Identification Number (EIN), assigned by the IRS.
      org:us:uei:
        anyOf:
          - $ref: OrgPatchOrgIdUeiOrCreate.yaml
          - type: "null"
        description: The organization's Unique Entity Identifier (UEI) from SAM.gov.
      org:xi:duns:
        anyOf:
          - $ref: OrgPatchOrgIdDunsOrCreate.yaml
          - type: "null"
        description: The organization's Data Universal Numbering System (DUNS) number.
      systemId:
        anyOf:
          - $ref: OrgPatchSystemIdOrCreate.yaml
          - type: "null"
        description: The hosting system's own identifier for this record.
      otherIds:
        anyOf:
          - type: object
            properties: {}
            unevaluatedProperties:
              anyOf:
                - $ref: OrgPatchIdentifierOrCreate.yaml
                - type: "null"
          - type: "null"
        description: |-
          Additional identifiers keyed by their registry code, for registries the
          protocol does not define as a base identifier on the model.
    unevaluatedProperties:
      not: {}
    description: |-
      A collection of identifiers associated with an organization.

      Extends the generic identifier collection with the base identifiers CommonGrants
      defines for organizations. Additional registries can be published under `otherIds`.
  OrgPatchPCSOrgTypeOrCreate:
    type: object
    properties:
      class:
        type: string
        const: Organization types
        description: The PCS term for the organization type.
      term:
        type: string
        description: The plain language PCS term.
      code:
        type: string
        examples:
          - UC000000
        pattern: ^[A-Z]{2}[0-9]{6}$
        description: The code for this PCS term.
      description:
        anyOf:
          - type: string
          - type: "null"
        description: Description of the PCS term
    unevaluatedProperties:
      not: {}
    description: |-
      A Philanthropy Classification System (PCS) term for organization types.

      See https://taxonomy.candid.org/organization-type for more information.
  OrgPatchAddressCollectionOrCreate:
    type: object
    properties:
      primary:
        $ref: OrgPatchAddressOrCreate.yaml
        description: The primary address for a person or organization.
      otherAddresses:
        anyOf:
          - type: object
            properties: {}
            unevaluatedProperties:
              anyOf:
                - $ref: OrgPatchAddressOrCreate.yaml
                - type: "null"
          - type: "null"
        description: Additional addresses keyed by a descriptive label (e.g., "work", "home", "international").
    unevaluatedProperties:
      not: {}
    description: A collection of addresses.
  OrgPatchPhoneCollectionOrCreate:
    type: object
    properties:
      primary:
        $ref: OrgPatchPhoneOrCreate.yaml
        description: The person's primary phone number.
      fax:
        anyOf:
          - $ref: OrgPatchPhoneOrCreate.yaml
          - type: "null"
        description: The person's fax number, if applicable.
      otherPhones:
        anyOf:
          - type: object
            properties: {}
            unevaluatedProperties:
              anyOf:
                - $ref: OrgPatchPhoneOrCreate.yaml
                - type: "null"
          - type: "null"
        description: Additional phone numbers not covered by the standard fields.
    unevaluatedProperties:
      not: {}
    description: A collection of phone numbers for a person.
  OrgPatchEmailCollectionOrCreate:
    type: object
    properties:
      primary:
        $ref: email.yaml
        description: The primary email address for a person or organization.
      otherEmails:
        anyOf:
          - type: object
            properties: {}
            unevaluatedProperties:
              anyOf:
                - $ref: email.yaml
                - type: "null"
          - type: "null"
        description: Additional email addresses keyed by a descriptive label (e.g., "work", "personal", "support").
    unevaluatedProperties:
      not: {}
    description: A collection of email addresses.
  OrgPatchOrgSocialLinksOrCreate:
    type: object
    properties:
      website:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's primary website URL.
      facebook:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's Facebook profile URL.
      twitterOrX:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's Twitter/X profile URL.
      bluesky:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's BlueSky profile URL.
      instagram:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's Instagram profile URL.
      linkedin:
        anyOf:
          - type: string
            format: uri
          - type: "null"
        description: The organization's LinkedIn profile URL.
      otherSocials:
        anyOf:
          - type: object
            properties: {}
            unevaluatedProperties:
              anyOf:
                - type: string
                  format: uri
                - type: "null"
          - type: "null"
        description: Additional social media profiles not covered by the standard fields.
    unevaluatedProperties:
      not: {}
    description: A collection of social media and web presence links for an organization.

TypeSpec

The TypeSpec code for this model.

   * Extends the generic identifier collection with the base identifiers CommonGrants
   * defines for organizations. Additional registries can be published under `otherIds`.
   */
  @Versioning.added(CommonGrants.Versions.v0_4)
  model OrgIds {
    ...OmitProperties<Models.OrgIds, "otherIds">;

    /** Additional identifiers keyed by their registry code, for registries the
     * protocol does not define as a base identifier on the model.
     */
    otherIds?: Record<Fields.Identifier | null>;
  }

  /** A Philanthropy Classification System (PCS) term for organization types.
   *
   * See https://taxonomy.candid.org/organization-type for more information.

Changelog

Version	Changes	Schema
0.4.0	Added OrgPatchData model	OrgPatchData.yaml