Ballerina library

candid.essentials

Modules

candidcandid.charitycheckpdf

candid.essentials

candid.premier

Module candid.essentials

API

Client

Definitions

AffiliationTypeFilter
ApiKeysConfig
AuditsFilter
ConnectionConfig
EssentialsFilteredLookupResponse
EssentialsFilteredLookupResponseData
EssentialsLookupResponse
Filters
FinancialsFilter
GeographyFilter
IrsFormTypesFilter
LastUpdated
NumberRangeFilter
OrganizationFilter
Query
Sort
SpecificExclusionsFilter
V1EssentialsResponse
V1EssentialsResponseData
V1EssentialsResponseDataHits
V1EssentialsResponseDataProperties
V2EssentialsResponse
V2EssentialsResponseData
V2EssentialsResponseDataHits
V3EssentialsResponse
V3EssentialsResponseDates
V3EssentialsResponseFinancials
V3EssentialsResponseFinancialsMostRecentYear
V3EssentialsResponseGeography
V3EssentialsResponseHits
V3EssentialsResponseOrganization
V3EssentialsResponseProperties
V3EssentialsResponsePropertiesRelationshipDetails
V3EssentialsResponsePropertiesRelationshipType
V3EssentialsResponseTaxonomies
V3EssentialsResponseTaxonomiesFoundationCode
V3EssentialsResponseTaxonomiesNteeCodes
V3EssentialsResponseTaxonomiesPopulationServedCodes
V3EssentialsResponseTaxonomiesSubjectCodes
V3EssentialsResponseTaxonomiesSubsectionCode
V3Filters
V3FinancialsFilter
V3FinancialsFilterMostRecentYear
V3FinancialsFilterMostRecentYearFormTypes
V3OrganizationFilter
V3OrgProperties
V3Query
V3Sort

ballerinax/candid.essentials Ballerina library

0.2.0

Clients

candid.essentials: Client

Isolated

Search GuideStar’s most common set of data about nonprofits to quickly find organizations most relevant to your users, and use those results to get more data from our other APIs. API returns search result in JSON format.

Constructor

Gets invoked to initialize the connector.

init (ApiKeysConfig apiKeyConfig, ConnectionConfig config, string serviceUrl)
  • config ConnectionConfig {} - The configurations to be used when initializing the connector
  • serviceUrl string "https://api.candid.org/essentials" - URL of the target service

post v1

Isolated FunctionResource Function
function post v1(Query payload, map<string|string[]> headers) returns V1EssentialsResponse|error

/essentials/v1

Parameters
  • payload Query - Below JSON request body is an example showing all available elements. Please use the examples from the API Documentation
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

post v2

Isolated FunctionResource Function
function post v2(Query payload, map<string|string[]> headers) returns V2EssentialsResponse|error

/essentials/v2

Parameters
  • payload Query - Below JSON request body is an example showing all available elements. Please use the examples from the API Documentation
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

post v3

Isolated FunctionResource Function
function post v3(V3Query payload, map<string|string[]> headers) returns V3EssentialsResponse|error

/essentials/v3

Parameters
  • payload V3Query - Below JSON request body is an example showing all available elements. Please use the examples from the API Documentation
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

get lookup

Isolated FunctionResource Function
function get lookup(map<string|string[]> headers) returns EssentialsLookupResponse|error

/essentials/lookup

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

get lookup/[string filterName]

Isolated FunctionResource Function
function get lookup/[string filterName](map<string|string[]> headers) returns EssentialsFilteredLookupResponse|error

/essentials/lookup/{filter_name}

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

get lookup/[string filterName]/[string keyOrValue]

Isolated FunctionResource Function
function get lookup/[string filterName]/[string keyOrValue](map<string|string[]> headers) returns EssentialsFilteredLookupResponse|error

/essentials/lookup/{filter_name}/{key_or_value}

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type

Records

candid.essentials: AffiliationTypeFilter

Fields
  • parent? boolean - Flag indicating the organization is a parent. Value set as true or false
  • subordinate? boolean - Flag indicating the organization is a subordinate. Value set as true or false
  • independent? boolean - Flag indicating the organization is independent. Value set as true or false
  • headquarter? boolean - Flag indicating the organization is a headquarter. Value set as true or false

candid.essentials: ApiKeysConfig

Closed record

Provides API key configurations needed when communicating with a remote HTTP endpoint.

Fields

candid.essentials: AuditsFilter

Fields
  • a133AuditPerformed? boolean - Flag indicating the organization performed A-133 audit. Value set as true or false

candid.essentials: ConnectionConfig

Closed record

Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Fields
  • httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
  • timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
  • forwarded string(default "disable") - The choice of setting forwarded/x-forwarded header
  • followRedirects? FollowRedirects - Configurations associated with Redirection
  • cache CacheConfig(default {}) - HTTP caching related configurations
  • compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (accept-encoding) header
  • circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
  • retryConfig? RetryConfig - Configurations associated with retrying
  • cookieConfig? CookieConfig - Configurations associated with cookies
  • responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
  • socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
  • validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
  • laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled, nil values are treated as optional, and absent fields are handled as nilable types. Enabled by default.

candid.essentials: EssentialsFilteredLookupResponse

Fields
  • code? int - HTTP response status code

candid.essentials: EssentialsFilteredLookupResponseData

Key value pair for filter name, value, and search_value

Fields
  • searchValue? string - Value to pass in Essential's API filters
  • value? string - Text for the filter_name results
  • 'key? string - Code for the filter_name results

candid.essentials: EssentialsLookupResponse

Fields
  • took? int - Time taken for request to process
  • code? int - Response Code
  • message? string - Diagnostic message for response status
  • errors? string[] - List of errors encountered

candid.essentials: Filters

Fields

candid.essentials: FinancialsFilter

Fields

candid.essentials: GeographyFilter

Fields
  • zip? string - Five digit ZIP code
  • radius? int - Radius from the specified ZIP code in miles. Allowed range is between 1 and 50 miles. Values exceeding 50 will default to a radius of 50 miles

candid.essentials: IrsFormTypesFilter

Fields
  • f990ez? boolean - Flag indicating the organization files a form 990 EZ. Value set as true or false
  • f990? boolean - Flag indicating the organization files a form 990. Value set as true or false
  • requiredToFile990t? boolean - Flag indicating the organization is required to file a 990-T. Value set as true or false
  • f990pf? boolean - Flag indicating the organization files a form 990-PF. Value set as true or false
  • f990n? boolean - Flag indicating the organization files a form 990N. Value set as true or false

candid.essentials: LastUpdated

Fields
  • endDate? string - A filter, along with start_date, defines a range on date_type, in the format yyyy-MM-ddTHH:mm:ss
  • dateType? "seal_last_modified"|"profile_last_modified"|"dei_last_modified"|"financials_last_modified"|"last_modified" - A filter, to specify updates made to a organization over the specified end_date and start_date
  • startDate? string - A filter, along with end_date, defines a range on date_type, in the format yyyy-MM-ddTHH:mm:ss

candid.essentials: NumberRangeFilter

Fields
  • min? int - Minimum number
  • max? int - Maximum number

candid.essentials: OrganizationFilter

Fields
  • bmfStatus? boolean - Flag indicating the organization has the most recent IRS BMF. Defaults to null. Otherwise true or false
  • profileLevels? string[] - GuideStar seal levels, comma separated
  • nteeMinorCodes? string[] - National Taxonomy of Exempt Entities (NTEE) minor codes, comma separated
  • subsectionCodes? string[] - IRS subsection codes and/or descriptions, comma separated
  • nteeMajorCodes? string[] - National Taxonomy of Exempt Entities (NTEE) major codes, comma separated
  • foundationCodes? string[] - Foundation codes and/or descriptions, comma separated
  • pub78Verified? boolean - Flag indicating the organization is pub78 verified. Value set as true or false

candid.essentials: Query

Fields
  • searchTerms? string - Can be any string you'd like to search on, including EIN, organization name, keywords, etc
  • size? int - The maximum number of hits to be returned. Defaults to 25. The maximum number allowed is 25
  • 'from? int - The offset from the first result. Defaults to 0

candid.essentials: Sort

Fields
  • sortBy? "organization_name"|"bmf_gross_receipts"|"bmf_assets" - Leave blank to sort by relevance
  • 'ascending? boolean - Default value is true (ascending). Set to false to sort by descending value

candid.essentials: SpecificExclusionsFilter

Fields
  • excludeDefunctOrMergedOrganizations? boolean - Flag to exclude defunct or merged organizations. Value set as true or false
  • excludeRevokedOrganizations? boolean - Flag to exclude revoked organizations. Value set as true or false

candid.essentials: V1EssentialsResponse

Fields
  • took? int - Time taken for request to process
  • code? int - Response Code
  • message? string - Diagnostic message for response status
  • errors? string[] - List of errors encountered

candid.essentials: V1EssentialsResponseData

Fields
  • took? int - Elapsed time to calculate results
  • totalHits? int - Number of results returned by search

candid.essentials: V1EssentialsResponseDataHits

Fields
  • parentOrgs? string - Names of parent organizations, comma seperated
  • contactPhone? string - Phone number of the primary contact at the organization
  • city? string - City of the organization's address
  • latLong? string - latitude and longitude of the organization's adress
  • county? string - County of the organization's address
  • ein? string - Employer Identification Number
  • formType? string - Tax form filing type.
  • form990TotalExpenses? string - Total expenses filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • contactEmail? string - Email of the primary contact at the organization
  • profileLevel? "BRONZE"|"SILVER"|"GOLD"|"PLATINUM"|"NONE" - GuideStar seal levels
  • subsectionCode? string - IRS subsection code of the organization
  • addressLine1? string - Address line 1 of the organization
  • addressLine2? string - Address line 2 of the organization
  • state? string - State (Abbreviation) of the organization's address
  • form990TotalRevenue? string - Total revenue filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • alsoKnownAs? string - Organization name Also Known As
  • zip? string - Zip code of the organization's address
  • contactName? string - Name of the primary contact at the organization
  • publicReport? string - GuideStar's public profile URL
  • bmfGrossReceipts? string - Gross receipts of the organization reported on the BMF
  • organizationName? string - The public name recognized by the IRS
  • nteeCode? string - National Taxonomy of Exempt Entities
  • mission? string - Mission statement for the organization
  • numberOfEmployees? string - Number of employees at the organization
  • websiteUrl? string - URL for the organization's website
  • organizationId? string - A unique number identifying organizations and organizational entities
  • bridgeId? string - Deprecated Bridge ID
  • msa? string - Metropolitan statistical area of the organization's adresss
  • form990TotalAssets? string - Total assets filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • contactTitle? string - Title of the primary contact at the organization
  • foundationCode? string - Foundation code that describes the organization
  • bmfAssets? string - Assets of the organization reported on the BMF

candid.essentials: V1EssentialsResponseDataProperties

Fields
  • bmfStatus? boolean - If the organization is present on the BMF
  • parent? boolean - If the organization is a parent
  • defunctedOrMerged? boolean - If the organization is defuncted or merged
  • subordinate? boolean - If the organization is a subordinate
  • independent? boolean - If the organization is independent
  • pub78Verified? boolean - If the organization is Pub78 verified
  • auditA133Performed? boolean - If the organization performed a A-133 audit
  • allowOnlineGiving? boolean - If the organization allows online giving
  • revoked? boolean - If the organization is revoked
  • nationalHq? boolean - If the organization is a national headquarter

candid.essentials: V2EssentialsResponse

Fields
  • took? int - Time taken for request to process
  • code? int - Response Code
  • message? string - Diagnostic message for response status
  • errors? string[] - List of errors encountered

candid.essentials: V2EssentialsResponseData

Fields
  • took? int - Elapsed time to calculate results
  • totalHits? int - Number of results returned by search

candid.essentials: V2EssentialsResponseDataHits

Fields
  • parentOrgs? string - Names of parent organizations, comma seperated
  • contactPhone? string - Phone number of the primary contact at the organization
  • city? string - City of the organization's address
  • logoUrl? string - URL for the organization's logo
  • latLong? string - latitude and longitude of the organization's adress
  • county? string - County of the organization's address
  • ein? string - Employer Identification Number
  • formType? string - Tax form filing type.
  • form990TotalExpenses? string - Total expenses filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • contactEmail? string - Email of the primary contact at the organization
  • profileLevel? "BRONZE"|"SILVER"|"GOLD"|"PLATINUM"|"NONE" - GuideStar seal levels
  • subsectionCode? string - IRS subsection code of the organization
  • addressLine1? string - Address line 1 of the organization
  • addressLine2? string - Address line 2 of the organization
  • state? string - State (Abbreviation) of the organization's address
  • form990TotalRevenue? string - Total revenue filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • alsoKnownAs? string - Organization name Also Known As
  • zip? string - Zip code of the organization's address
  • contactName? string - Name of the primary contact at the organization
  • publicReport? string - GuideStar's public profile URL
  • bmfGrossReceipts? string - Gross receipts of the organization reported on the BMF
  • organizationName? string - The public name recognized by the IRS
  • nteeCode? string - National Taxonomy of Exempt Entities
  • mission? string - Mission statement for the organization
  • numberOfEmployees? string - Number of employees at the organization
  • websiteUrl? string - URL for the organization's website
  • organizationId? string - A unique number identifying organizations and organizational entities
  • bridgeId? string - Deprecated Bridge ID
  • msa? string - Metropolitan statistical area of the organization's adresss
  • form990TotalAssets? string - Total assets filed on the most recent Form 990, 990-PF, or 990-EZ filing
  • contactTitle? string - Title of the primary contact at the organization
  • foundationCode? string - Foundation code that describes the organization
  • bmfAssets? string - Assets of the organization reported on the BMF

candid.essentials: V3EssentialsResponse

Fields
  • took? int - Time taken for request to process
  • code? int - Response Code
  • resultsCount? int - Number of results returned by search
  • time? string - Time of API call
  • message? string - Diagnostic message for response status
  • pageCount? int - Number of pages returned by the search
  • errors? string[] - List of errors encountered

candid.essentials: V3EssentialsResponseDates

Fields
  • sealLastModified? string - Date when Candid seal status was last modified
  • financialsLastModified? string - Datetime of last update to organization's financial information
  • deiLastModified? string - Datetime of last update to organization demographics information
  • profileLastModified? string - Datetime of last update to Candid profile
  • lastPublished? string - Datetime of organization's last publication

candid.essentials: V3EssentialsResponseFinancials

Fields
  • a133AuditPerformed? boolean - Flag indicating the organization performed A-133 audit
  • requiredToFile990t? boolean - Flag indicating the organization is required to file a 990-T
  • bmfGrossReceipts? decimal - Gross receipts of the organization reported on the BMF
  • bmfAssets? decimal - Assets of the organization reported on the BMF

candid.essentials: V3EssentialsResponseFinancialsMostRecentYear

Fields
  • totalAssets? decimal - Most recent year total assets
  • fiscalYear? decimal - Fiscal year of the most recent tax filing
  • totalRevenue? decimal - Most recent year total revenue
  • formTypes? string - Tax form filing type
  • totalExpenses? decimal - Most recent year total expenses

candid.essentials: V3EssentialsResponseGeography

Fields
  • congressionalDistrict? string - Congressional district of the organization's address
  • city? string - City of the organization's address
  • latitude? decimal - latitude of the organization's adress
  • addressLine1? string - Address line 1 of the organization
  • county? string - County of the organization's address
  • msa? string - Metropolitan statistical area of the organization's adresss
  • addressLine2? string - Address line 2 of the organization
  • state? string - State (Abbreviation) of the organization's address
  • longitude? decimal - longitude of the organization's adress

candid.essentials: V3EssentialsResponseHits

Fields

candid.essentials: V3EssentialsResponseOrganization

Fields
  • alsoKnownAs? string - Organization name Also Known As
  • contactName? string - Name of the primary contact at the organization
  • contactPhone? string - Phone number of the primary contact at the organization
  • logoUrl? string - URL for the organization's logo
  • leaderName? string - Name of leader
  • rulingYear? decimal - The year the IRS granted organization tax exempt status (a.k.a. Ruling Year)
  • profileYear? decimal - GuideStar seal year
  • ein? string - Employer Identification Number
  • organizationName? string - The public name recognized by the IRS
  • leaderTitle? string - Leader's title
  • contactEmail? string - Email of the primary contact at the organization
  • profileLevel? string - GuideStar seal level
  • mission? string - Mission statement for the organization
  • numberOfEmployees? decimal|string - Number of employees at the organization
  • websiteUrl? string - URL for the organization's website
  • organizationId? string - A unique number identifying organizations and organizational entities
  • groupExemption? string - Four-digit number assigned to a group of organizations falling under a central/parent organization holding group exemption letters
  • contactTitle? string - Title of the primary contact at the organization

candid.essentials: V3EssentialsResponseProperties

Fields
  • bmfStatus? boolean - If the organization is present on the BMF
  • defunctedOrMerged? boolean - If the organization is defuncted or merged
  • pub78Verified? boolean - If the organization is Pub78 verified
  • allowOnlineGiving? boolean - If the organization allows online giving
  • revoked? boolean - If the organization is revoked
  • deiSubmitted? boolean - If the organization has submitted demographics information

candid.essentials: V3EssentialsResponsePropertiesRelationshipDetails

Organization's relation with other organizations

Fields
  • relationshipType? "parent"|"subordinate" - Relationship type of organization
  • organizationName? string - Name of organization
  • ein? string - Employer Identification Number

candid.essentials: V3EssentialsResponsePropertiesRelationshipType

Fields
  • parent? boolean - If the organization is a parent
  • headquarters? boolean - If the organization is a national headquarter
  • subordinate? boolean - If the organization is a subordinate
  • independent? boolean - If the organization is independent

candid.essentials: V3EssentialsResponseTaxonomies

Fields

candid.essentials: V3EssentialsResponseTaxonomiesFoundationCode

Fields
  • foundationCodeDescription? string - Description of foundation code
  • foundationCode? string - Foundation code that describes the organization

candid.essentials: V3EssentialsResponseTaxonomiesNteeCodes

Fields
  • nteeCodeDescription? string - Description of NTEE code
  • nteeCode? string - National Taxonomy of Exempt Entities

candid.essentials: V3EssentialsResponseTaxonomiesPopulationServedCodes

Fields
  • populationServedDescription? string - Description of Population served code
  • populationServedCode? string - Population served code

candid.essentials: V3EssentialsResponseTaxonomiesSubjectCodes

Fields
  • subjectCode? string - Subject code
  • subjectCodeDescription? string - Description of subject code

candid.essentials: V3EssentialsResponseTaxonomiesSubsectionCode

Fields
  • subsectionCode? string - IRS subsection code of the organization
  • subsectionCodeDescription? string - Description of IRS subsection code

candid.essentials: V3Filters

Fields

candid.essentials: V3FinancialsFilter

Fields
  • a133AuditPerformed? boolean - Flag indicating the organization performed A-133 audit. Value set as true or false
  • requiredToFile990t? boolean - Flag indicating the organization is required to file a 990-T. Value set as true or false

candid.essentials: V3FinancialsFilterMostRecentYear

Fields

candid.essentials: V3FinancialsFilterMostRecentYearFormTypes

Fields
  • f990ez? boolean - Flag indicating the organization files a form 990ez. Value set as true or false
  • f990? boolean - Flag indicating the organization files a form 990. Value set as true or false
  • f990pf? boolean - Flag indicating the organization files a form 990-PF. Value set as true or false
  • f990n? boolean - Flag indicating the organization files a form 990n. Value set as true or false

candid.essentials: V3OrganizationFilter

Fields
  • groupExemption? string[] - Group exemption codes, comma separated
  • profileLevels? string[] - GuideStar seal levels, comma separated
  • nteeMinorCodes? string[] - National Taxonomy of Exempt Entities (NTEE) minor codes, comma separated
  • subsectionCodes? string[] - IRS subsection codes and/or descriptions, comma separated
  • nteeMajorCodes? string[] - National Taxonomy of Exempt Entities (NTEE) major codes, comma separated
  • foundationCodes? string[] - Foundation codes and/or descriptions, comma separated
  • populationServedCodes? string[] - Population served codes, comma separated
  • subjectCodes? string[] - Subject codes, comma separated

candid.essentials: V3OrgProperties

Fields
  • bmfStatus? boolean - Flag indicating the organization has the most recent IRS BMF. Defaults to null. Otherwise true or false
  • excludeDefunctOrMergedOrganizations? boolean - Flag to exclude defunct or merged organizations. Value set as true or false
  • excludeRevokedOrganizations? boolean - Flag to exclude revoked organizations. Value set as true or false
  • pub78Verified? boolean - Flag indicating the organization is pub78 verified. Value set as true or false
  • allowOnlineGiving? boolean - Flag indicating the organization allows online giving. Value set as true or false
  • deiSubmitted? boolean - Flag indicating the organization has submitted demographics information. Value set as true or false

candid.essentials: V3Query

Fields
  • searchTerms? string - Can be any string you'd like to search on, including EIN, organization name, keywords, etc
  • size? int - The maximum number of hits to be returned. Defaults to 25. The maximum number allowed is 25
  • 'from? int - The offset from the first result. Defaults to 0

candid.essentials: V3Sort

Fields
  • sortBy? "organization_name"|"bmf_gross_receipts"|"bmf_assets"|"distance"|"year_founded" - Leave blank to sort by relevance
  • sortOrder? "asc"|"desc" - Default value is ascending. Allowed values are "asc" (ascending) and "desc" (descending)

Import

import ballerinax/candid.essentials;Copy

Other versions

0.2.1

0.2.0

0.1.10.1.00.0.1

Metadata

Released date: 5 months ago

Version: 0.2.0

License: Apache-2.0

Compatibility

Platform: any

Ballerina version: 2201.12.0

GraalVM compatible: Yes

Pull count

Total: 100

Current verison: 9

Weekly downloads

Source repository

Keywords

Nonprofit Data

Philanthropy Data

Nonprofit APIs

Vendor/Candid

Area/Other

Type/Connector

Contributors

Dependencies

ballerina/log/2.12.0ballerina/os/1.10.1ballerina/data.jsondata/1.1.3
See more...

Terms of service

Privacy policy

Cookie policy

Delete policy

© 2026 WSO2 LLC