Part III (B): Submission via JSON

Introduction

A JSON endpoint of grant data is one method available to sync your agency or department’s grant information with this portal. This method is ideal for departments with IT staff comfortable supporting JSON file development that aren’t using WordPress. Using this method, you’ll create a public JSON endpoint that contains your grant data following the specification defined below. Once this endpoint is available and contains at least one grant, an approved grant contributor can register your endpoint on the Grants Portal.

Once an endpoint has been registered, the portal will periodically (once per 24 hours) perform a /GET request to your endpoint to check for changes or additions to your grant data. If new grants, or updates to existing grants, are identified, the portal will update the information on the portal to reflect those.

JSON Specification

Your endpoint must return valid JSON and be publicly accessible from the internet. The response must contain an array of one or more grants objects.

EXAMPLE JSON RESPONSE

GRANT RESPONSE

[
    {
        "grantTitle": "Example Grant",
        "uniqueID": 29,
        "awardStats": [
            {
                "fiscalYear": "2022-2023",
                "applicationsSubmitted": 1,
                "grantsAwarded": 1,
            },
            {
                "fiscalYear": "2021-2022",
                "applicationsSubmitted": 1,
                "grantsAwarded": 1,
            },
            {
                "fiscalYear": "2020-2021",
                "applicationsSubmitted": 1,
                "grantsAwarded": 1,
            }
        ],
        "grantID": "example-grant",
        "isForecasted": "active",
        "opportunityType": [ "grant" ],
        "loiRequired": true,
        "grantCategories": [
            "agriculture",
            "disadvantaged-communities",
            "disaster-prevention-relief"
        ],
        "categorySuggestions": "",
        "purpose": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr...",
        "description": "Stet clita kasd gubergren, no sea takimata sanctus...",
        "applicantType": {
            "type": [
                "business",
                "individual"
            ],
            "notes": "Sed diam nonumy eirmod tempor invidunt ut labore et dolore..."
        },
        "geoLimitations": "No geographic limitations.",
        "fundingSource": {
            "type": "federal",
            "notes": "This is a federally funded grant."
        },
        "matchingFunds": {
            "required": false,
            "percent": 0,
            "notes": ""
        },
        "totalEstimatedFunding": "exactFundingAmount",
        "estimatedAvailableFunds": "10000",
        "estimatedAvailableFundNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr...",
        "estimatedAwards": {
            "exact": "1"
        },
        "estimatedAmounts": {
            "same": true
        },
        "fundingMethod": {
            "type": "advances-and-reimbursements",
            "notes": ""
        },
        "openDate": "2020-07-04T00:00",
        "anticipatedOpenDate": "",
        "periodOfPerformance": "12 days",
        "expectedAwardDate": "November, 2020",
        "deadline": "2021-07-04T23:59",
        "electronicSubmission": {
            "type": "url",
            "url": "https://grantsportal.test.com/"
        },
        "details": "https://grantsportal.test.com/",
        "agencyURL": "https://grantsportal.test.com/",
        "subscribe": "https://grantsportal.test.com/",
        "events": "https://grantsportal.test.com/",
        "contactInfo": {
            "name": "John Doe",
            "email": "noreply@castlg-stage.10upmanaged.com",
            "tel": "1-555-555-5555"
        },
        "internalContactInfo": [
            {
                "name": "Jane Doe",
                "email": "noreply@grantsportal.test.com",
                "tel": "1-555-555-5555",
                "primary": true
            },
            {
                "name": "Jack Doe",
                "email": "noreply@grantsportal.test.com",
                "tel": "1-555-555-5555"
            }
        ],
        "_links": {
            "award": [
                {
                    "href": "https://grantsportal.test.com/json-endpoint/grant-awards-29.json"
                }
            ]
        }
    }
]

GRANT Award RESPONSE

[
    {
        "uniqueID": 76,
        "grantID": 29,
        "fiscalYear": "2022-2023",
        "projectTitle": "Grant Award Title",
        "recipientType": "business",
        "primaryRecipientName": "Award Recipient Name",
        "primaryRecipientFirstName": "Example",
        "primaryRecipientLastName": "Grant Award",
        "secondaryRecipients": "no",
        "totalAwardAmount": 1000000,
        "matchingFundingAmount": 1000,
        "awardAmountNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr...",
        "grantFundedStartDate": "2022-06-03T14:06",
        "grantFundedEndDate": "2022-08-03T14:08",
        "projectAbstract": "Lorem ipsum dolor sit amet, consetetur sadipscing...",
        "geoLocationServed": "county",
        "countiesServed": [
            "amador"
        ],
        "geoServedNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing..."
  }
]

GRANT SCHEMA

grantTitle

DescriptionThe title of the grant opportunity. This should be identical to the name for the grant opportunity on your own website, RFP/A, etc. If this is an annually posted grant, add the year to the end of the title to ensure the title is unique.
TypeString
Required?Yes.

Example:

{
  ...
  "grantTitle": "My Grant Title",
  ...
}

uniqueID

DescriptionA unique ID for your grant. Is not used by the portal, but included in the specification so you may identify your grants within an internal system. If you do not have a unique ID that your department uses, please create one.
TypeString
Required?Yes

Example:

{
  ...
  "uniqueID": "grant-101",
  ...
}

awardStats

DescriptionAn object representing grant award stats information. Refer to the object details and example below for more information.
TypeObject
Required?No

awardStats Object:

FieldTypeRequired?DescriptionValid Values
fiscalYearstringNoThe fiscal year to save the number of applications and grants awarded for.“2021-2022”, “2022-2023”, “2023-2024”
applicationsSubmittedIntegerNoThe total applications received for this funding opportunity.
grantsAwardedIntegerNoEnter the number of individual grants awarded for this grant opportunity. Please update if changes are made in the grant agreement.

Example:

{
  ...
  "awardStats": [
      {
          "fiscalYear": "2022-2023",
          "applicationsSubmitted": 1,
          "grantsAwarded": 1,
      },
      {
          "fiscalYear": "2021-2022",
          "applicationsSubmitted": 1,
          "grantsAwarded": 1,
      },
      {
          "fiscalYear": "2020-2021",
          "applicationsSubmitted": 1,
          "grantsAwarded": 1,
      }
  ],
  ...
}

isForecasted

DescriptionWhether the grant is active, or forecasted. Forecasted grants require less information to be included.
TypeString
Required?Yes
Valid valuesactive, forecasted

Example:

{
  ...
  "isForecasted": "active",
  ...
}

opportunityType

DescriptionThe types of opportunity.
TypeArray[<String>]
Required?Yes
Valid valuesgrant, loan

Example:

{
  ...
  "opportunityType": [ "grant", "loan" ],
  ...
}

loiRequired

DescriptionWhether a letter of intent is required to be submitted with this grant.
TypeBoolean
Required?Active grants only

Example:

{
  ...
  "loiRequired": true,
  ...
}

grantCategories

DescriptionAn array of categories to associate with this grant. See Valid Items below for a list of the category IDs you can use.
TypeArray[<String>]
Required?Active grants only
Valid valuesagriculture, disadvantaged-communities, disaster-prevention-relief, education, employment-labor-training, energy, environment-water, food-nutrition, health-human-services, housing-community-economic-development, law-justice-legal-services, libraries-parks-recreation-arts, science-technology-research-development, transportation, uncategorized, veterans-military
Additional Notes“uncategorized” should only be used if none of the other categories are appropriate. If you’d like to make a suggestion that an additional category be supported, see categorySuggestions below.

Example:

{
  ...
  "grantCategories": [
    "agriculture",
    "energy"
  ],
  ...
}

categorySuggestions

DescriptionIf the supported categories do not sufficiently describe the opportunity, you may suggest an additional category be considered for support. Please include this field if you use “uncategorized” in the grantCategory field. If you have more than one suggestion, please separate them with commas.
TypeString
Required?No

Example:

{
  ...
  "categorySuggestions": "Astronomy, Ornithology",
  ...
}

purpose

DescriptionThe purpose of the grant.
TypeString (maximum 450 characters)
Required?Active grants only

Example:

{
  ...
  "purpose": "Lorem ipsum dolor sit amet.",
  ...
}

description

DescriptionA description of the grant.
TypeString (maximum 3200 characters)
Required?Yes

Example:

{
  ...
  "description": "Lorem ipsum dolor sit amet.",
  ...
}

applicantType

DescriptionAn object representing the type of applicant for this grant. Refer to the object details and example below for more information.
TypeObject
Required?Active grants only

applicantType Object:

FieldTypeRequired?DescriptionValid Values
typeArray[<String>]YesThe allowed applicant types.business, individual, nonprofit, other, public-agency, tribal-government
notesstring (max 450 characters)NoNotes about the allowed applicant types.

Example:

{
  ...
  "applicantType": {
    "type": [
      "business",
      "individual"
    ],
    "notes": "Lorem ipsum dolor sit amet."
  },
  ...
}

geoLimitations

DescriptionNotes on any geographic limitations for the grant.
TypeString (max 450 characters)
Required?No

Example:

{
  ...
  "geoLimitations": "Only businesses headquartered in California may apply.",
  ...
}

fundingSource

DescriptionAn object representing the funding source of a grant. Refer to the object details and example below for more information. Note: If you selected “Other”, please outline the funding source details in the notes section below.
TypeObject
Required?Active grants only

fundingSource Object

FieldTypeRequired?DescriptionValid Values
typestringYesThe revenue source. See valid values for allowed revenue types.federal, state, both, other
notesstring (max 450 characters)NoNotes about the revenue type.

Example:

{
  ...
  "fundingSource": {
    "type": "federal",
    "notes": "Lorem ipsum dolor sit amet."
  },
  ...
}

matchingFunds

DescriptionAn object to describe if matching funds are required, at what percent, and any additional information. Refer to the object details and example below for more information.
TypeObject
Required?Active grants only

matchingFunds Object

FieldTypeRequired?Description
requiredBooleanYesWhether matching strings are required.
percentIntegerOnly if required is true.The percent of the funds that are required to be matched.
notesString (max 450 characters)NoAdditional notes to help applicants understand the matching funds requirement.

Example:

{
  ...
  "matchingFunds": {
    "required": true,
    "percent": 50,
    "notes": "Requires match of 50% of grant awarded."
  },
  ...
}

totalEstimatedFunding

DescriptionTotal Estimated Available Funding for the grant.
TypeString
Required?Active grants only
Valid valuesexactFundingAmount, fundingAmountNotes

Example:

{
  ...
  "totalEstimatedFunding": "exactFundingAmount",
  ...
}

estimatedAvailableFunds

DescriptionThe estimated dollar amount of the available funds, rounded to the dollar.
TypeInteger
Required?Active grants only

Example:

{
  ...
  "estimatedAvailableFunds": 10000,
  ...
}

estimatedAvailableFundNotes

DescriptionAvailable funding notes for the grant when exact funding amount is not available for grant.
TypeString (max 450 characters)
Required?Required when “totalEstimatedFunding” value is “fundingAmountNotes”

Example:

{
  ...
  "estimatedAvailableFundNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr...",
  ...
}

estimatedAwards

DescriptionAn object describing how the grant will be awarded.
TypeObject
Required?Active grants only

Valid Values: Required one of following value.

Value TypeDescription
“exact”IntegerExact value of estimated awards.
“between”Array[<Integer>]Range of estimated awards with range values in number,
“dependent”StringDependent on number of awards,

Example:

“between”:

{
  ...
  "estimatedAwards": {
    "between":[ 0, 100 ]
  },
  ...
}

“exact”:

{
  ...
  "estimatedAwards": {
    "exact": 100 
  },
  ...
}

“dependent”:

{
  ...
  "estimatedAwards": {
    "dependent": "Dependant on number of awards."
  },
  ...
}

estimatedAmounts

DescriptionAn object describing the fund amounts the grant will be awarding.
TypeObject
Required?Active grants only

Valid Values: Required one of following value.

Value TypeDescription
“same”IntegerUse this type if the grant beneficiaries will receive the same or equal amount. The value should be the amount that is awarded.
“range”Array[<Integer>]Use this type if the awarded amounts will fall within a range, where the first value is the minimum amount and the second value is the maximum.
“dependent”StringUse this type if the amount of the funds awarded is dependent on the number of applications submissions were received, application process, or some other factor.

Example:

“same”:

{
  ...
  "estimatedAmounts": {
    "same": 10000
  },
  ...
}

“range”:

{
  ...
  "estimatedAwards": {
    "range": [ 5000, 1000 ]
  },
  ...
}

“dependent”:

{
  ...
  "estimatedAwards": {
    "dependent": "Depends on the number of applications received"
  },
  ...
}

fundingMethod

DescriptionAn object describing how the awarded funds will be disbursed. Note: If you selected “Other”, please outline the funding method details in the notes section below.
TypeObject
Required?Active grants only

fundingMethod Object

FieldTypeRequired?DescriptionValid Values
typestringYesThe funding type. See valid values for allowed revenue types.advances, advances-and-reimbursements, reimbursements, other
notesstring (max 450 characters)NoNotes about the funding method

Example:

{
  ...
  "fundingMethod": {
    "type": "advances-and-reimbursements",
    "notes": ""
  },
  ...
}

openDate

DescriptionThe date and time, in ISO-8601 format, that the grant will open.
TypeString
Required?Yes

Example:

{
  ...
  "openDate": "2020-07-04T00:00",
  ...
}

anticipatedOpenDate

DescriptionAnticipated Open Date for the Forecasted Grant. You can use things like “Q1” or “Summer 2020”.
TypeString
Required?Forecasted grants only.

Example:

{
  ...
  "anticipatedOpenDate": "Summer 2020",
  ...
}

periodOfPerformance

DescriptionThe period of performance.
TypeString (maximum 20 characters)
Required?Active grants only

Example:

{
  ...
  "periodOfPerformance": "12 weeks.",
  ...
}

expectedAwardDate

DescriptionThe expected date the grant will be awarded. This is an open text field to accept non-exact times like, “3rd Quarter 2021”.
TypeString (maximum 20 characters)
Required?Active grants only

Example:

{
  ...
  "expectedAwardDate": "Q3 2021",
  ...
}

deadline

DescriptionThe application deadline date and time, in ISO-8601 format. When grants close at midnight, the grant details page will display 00:00, which can be confusing for users. If possible, use “23:59” (11:59pm) for clarity.
TypeString
Required?No

Example:

{
  ...
  "deadline": "2021-07-04T23:59",
  ...
}

electronicSubmission

DescriptionObject containing one of, or both, “email” and “url” keys. Describes the electronic method where an applicant can submit an application. Refer to the example below for proper schema.
TypeObject
Required?Active grants only

electronicSubmission Object

FieldTypeRequired?DescriptionValid Values
typeStringYesApplication submitted electronic method type.none, url, email
urlStringOnly when type value is “url”Url to electronically submit application.
emailStringOnly when type value is “email”Email Id to electronically submit application.

Example:

{
  ...
  "electronicSubmission": {
    "type": "none"
  },
  ...
}
{
  ...
  "electronicSubmission": {
    "type": "url",
    "url": "https://www.grants.ca.gov"
  },
  ...
}
{
  ...
  "electronicSubmission": {
    "type": "email",
    "email": "noreply@grantsportal.test.com"
  },
  ...
}

details

DescriptionA URL where more details about the grant can be found.
TypeString
Required?Active grants only

Example:

{
  ...
  "details": "https://www.grants.ca.gov/",
  ...
}

agencyURL

DescriptionA URL where more details about the grant maker can be found.
TypeString
Required?Active grants only

Example:

{
  ...
  "agencyURL": "https://www.grants.ca.gov/",
  ...
}

subscribe

DescriptionA URL where more updates about the grant can be found.
TypeString
Required?No

Example:

{
  ...
  "subscribe": "https://www.grants.ca.gov/",
  ...
}

events

DescriptionA URL where information about planned events surrounding the grant can be found.
TypeString
Required?No

Example:

{
  ...
  "events": "https://www.grants.ca.gov/",
  ...
}

contactInfo

DescriptionAn object to describe the public contact information where applicants can direct questions about the grant.
TypeObject
Required?Active grants only

contactInfo Object

FieldTypeRequired?Description
nameStringNoName of the individual that can be contacted regarding the grant opportunity
emailStringYesThe email address for the contact.
telStringYesThe telephone number of the contact.

Example:

{
  ...
  "contactInfo": {
    "name": "John Doe",
    "email": "noreply@castlg-stage.10upmanaged.com",
    "tel": "1-555-555-5555"
  },
  ...
}

internalContactInfo

DescriptionAn array of objects to describe the internal contact information where other agencies or departments can direct questions.
TypeArray[<object>]
Required?Active grants only

internalContactInfo Object

FieldTypeRequired?Description
nameStringYesName of the individual that can be contacted regarding the grant opportunity
emailStringYesThe email address for the contact.
telStringYesThe telephone number of the contact.
primaryBooleanNoWhether this contact is the primary contact. If this value is not present, the first listed contact will be deemed the primary.

Example:

{
  ...
  "internalContactInfo": [
    {
      "name": "John Doe",
      "email": "noreply@grants.ca.gov",
      "tel": "1-555-555-5555",
      "primary": true
    },
    {
      "name": "Jane Doe",
      "email": "noreply@grants.ca.gov",
      "tel": "1-555-555-5555"
    },
  ],
  ...
}


_links

DescriptionAll associated links for the grant, used for adding link for grant award json endpoint link for associated grant.
TypeObject
Required?No
Valid ValueGrant award json endpoint url in “href” value. Please refer to the example below on where and how url should be added in “_links”

Example:

{
  ...
  "_links": {
    "award": [
      {
        "href": "https://grantsportal.test.com/json-endpoint/grant-awards-29.json"
      }
    ]
  },
  ...
}


GRANT Award SCHEMA

uniqueID

DescriptionA unique ID is typically numbers, letters or a combination of letters or numbers that the state department uses to identify the grant award. If your department does not use a Unique ID for grant award, please create one.
TypeString
Required?Yes

Example:

{
  ...
  "uniqueID": "76",
  ...
}

grantID

DescriptionThis will be the same value as “uniqueID” entered at the initial entry of the associated grant opportunity from the endpoint. This ID will be used to connect grant awards to the specific grant.
TypeString
Required?Yes

Example:

{
  ...
  "grantID": "29",
  ...
}

fiscalYear

DescriptionFiscal year for the grant award. This value should match from awardStats data of associated Grant.
TypeString
Required?Yes

Example:

{
  ...
  "fiscalYear": "2022-2023",
  ...
}

projectTitle

DescriptionProject title for the award. The project title must match the title provided in the application.
TypeString (maximum 300 characters)
Required?No

Example:

{
  ...
  "projectTitle": "Grant Award Title",
  ...
}

recipientType

DescriptionIndicate the recipient type, or the recipient type of the primary awardee if multiple awardees.
TypeString
Required?Yes
Valid Valuesbusiness, individual, nonprofit, public-agency, tribal-government

Example:

{
  ...
  "recipientType": "business",
  ...
}

primaryRecipientName

DescriptionProvide the award recipient’s name (legal name of the principal investigator, project lead, or institution name), or the name of the primary awardee if multiple recipients. Please update this if changes are made in the grant agreement.
TypeString (maximum 200 characters)
Required?Only if recipientType value is other than “individual”.

Example:

{
  ...
  "primaryRecipientName": "Award Recipient Name",
  ...
}

primaryRecipientFirstName

DescriptionProvide the award recipient’s first name, or the first name of the primary awardee if multiple recipients. Please update if changes are made in the grant agreement.
TypeString (maximum 100 characters)
Required?Only if recipientType value is “individual”.

Example:

{
  ...
  "primaryRecipientFirstName": "Example",
  ...
}

primaryRecipientLastName

DescriptionProvide the award recipient’s last name, or the last name of the primary awardee if multiple recipients. Please update if changes are made in the grant agreement.
TypeString (maximum 200 characters)
Required?Only if recipientType value is “individual”.

Example:

{
  ...
  "primaryRecipientLastName": "Grant Award",
  ...
}

secondaryRecipients

DescriptionIndicate if additional recipients (e.g. sub, secondary, or co-recipients/grantees) were listed in the application.
TypeString
Required?Yes
Valid valuesyes, no

Example:

{
  ...
  "secondaryRecipients": "no",
  ...
}

totalAwardAmount

DescriptionEnter the dollar amount awarded to the recipient, as listed on the grant agreement – think of this as the “grant cost” rather than the “project cost”. Note: Please update if the award amount gets augmented in the grant agreement (however, updates are not required if award amount changes are not reflected in an updated agreement).
TypeString
Required?Yes

Example:

{
  ...
  "totalAwardAmount": 1000000,
  ...
}

matchingFundingAmount

DescriptionIf partial or full matching is requested or required by the agreement or voluntarily contributed by the awardee, enter the matched funding dollar amount. If no matched funding is contributed enter “0”. Update if changes are made in the grant agreement.
TypeString
Required?Yes

Example:

{
  ...
  "matchingFundingAmount": 1000,
  ...
}

awardAmountNotes

DescriptionProvide any additional details, including: exceptions, amount or source (state, federal, in-kind, etc.) limitations, and matching funding percentage, if applicable.
TypeString (maximum 300 characters)
Required?Yes

Example:

{
  ...
  "awardAmountNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr...",
  ...
}

grantFundedStartDate

DescriptionBeginning Date of Grant-Funded Project, in ISO-8601 format.
TypeString
Required?Yes

Example:

{
  ...
  "grantFundedStartDate": "2022-06-03T14:06",
  ...
}

grantFundedEndDate

DescriptionEnd Date of Grant-Funded Project, in ISO-8601 format.
TypeString
Required?Yes

Example:

{
  ...
  "grantFundedEndDate": "2022-08-03T14:08",
  ...
}

projectAbstract

DescriptionProvide a brief outline of the project purpose, priorities, scope of this opportunity, and grant beneficiaries. Beneficiaries include any communities, persons, or entities that benefit from this funding. Please update if changes are made in the grant agreement.
TypeString (maximum 600 characters)
Required?Yes

Example:

{
  ...
  "projectAbstract": "Lorem ipsum dolor sit amet, consetetur sadipscing...",
  ...
}

geoLocationServed

DescriptionGeographic Location Served.
TypeString
Required?Yes
Valid valuescounty, statewide, out-of-state

Example:

{
  ...
  "geoLocationServed": "county",
  ...
}

countiesServed

DescriptionCounties Served, If “County” is selected in the Geographic Location Served field, add all relevant California counties.
TypeArray[<String>]
Required?Yes
Valid Valuesalameda, alpine, amador, butte, calaveras, colusa, contra-costa, del-norte, el-dorado, fresno, glenn, humboldt, imperial, inyo, kern, kings, lake, lassen, los-angeles, madera, marin, mariposa, mendocino, merced, modoc, mono, monterey, napa, nevada, orange, placer, plumas, riverside, sacramento, san-benito, san-bernardino, san-diego, san-francisco, san-joaquin, san-luis-obispo, san-mateo, santa-barbara, santa-clara, santa-cruz, shasta, sierra, siskiyou, solano, sonoma, stanislaus, sutter, tehama, trinity, tulare, tuolumne, ventura, yolo, yuba

Example:

{
  ...
  "countiesServed": [
     "amador"
  ],
  ...
}

geoServedNotes

DescriptionGeographic Location Served Notes
TypeString (maximum 300 characters)
Required?Yes

Example:

{
  ...
  "geoServedNotes": "Lorem ipsum dolor sit amet, consetetur sadipscing..."
  ...
}

Last Updated: 9/12/2022