How to Build Automated Nonprofit Verification Into an Application

Q: How should my application handle IRS source conflicts?

Evaluate `irs_bmf_pub78_conflict` together with the BMF and Pub. 78 classification fields and their source dates. Preserve the conflict and route it according to your workflow instead of silently selecting one source.

Q: How should I decide when to re-run verification?

Use `most_recent_bmf`, `most_recent_pub78`, `organization_info_last_modified` and `report_date` as freshness inputs. Your application can use those dates with its own policy to decide when a prior result is too old for the current workflow.

Direct answer

Build automated nonprofit verification around the EIN. Your application sends the EIN to Pactman Nonprofit Check Plus API, receives a normalized nonprofit record, preserves the source-specific signals, and applies the business rules required by your workflow.

A practical implementation should verify the returned ein and organization_name, evaluate bmf_status and IRS classification, review pub78_verified and organization_types when contribution eligibility matters, preserve foundation classification, check revocation and reinstatement, evaluate ofac_status, handle irs_bmf_pub78_conflict, and use source dates to decide whether the result is current enough for your workflow.

Recommended verification flow

Capture and normalize the EIN. Remove spaces or dashes so 12-3456789 becomes 123456789.
Call the appropriate Pactman endpoint. Use the single-EIN nonprofitcheck workflow for one organization and the bulk workflow when your application needs to evaluate multiple EINs.
Confirm the returned organization. Match ein and organization_name to the organization supplied by the user or upstream system.
Evaluate IRS BMF status and classification. Review bmf_ein, bmf_status, bmf_subsection, subsection_description and exempt_status_code.
Evaluate Pub. 78 when relevant. Review pub78_ein, pub78_verified, most_recent_pub78 and the organization_types array.
Preserve foundation and filing context. Review foundation_code, foundation_code_description, foundation_509a_status, foundation_type_code, foundation_type_description, filing_req_code and group_exemption.
Check revocation and reinstatement. Review revocation_code, revocation_date and reinstatement_date.
Check sanctions screening. Evaluate ofac_status independently from IRS tax-status logic.
Handle conflicts, exceptions and freshness. Review irs_bmf_pub78_conflict, pub78_church_message, bmf_church_message, most_recent_bmf, most_recent_pub78 and organization_info_last_modified.
Apply and store your application result. Keep the Pactman source fields available for audit or re-evaluation rather than storing only a generic pass/fail value.

Example request(s)

curl --request GET \
  --url https://entities.pactman.org/api/entities/nonprofitcheck/v1/us/ein/YOUR_EIN \
  --header 'Authorization: Bearer YOUR_API_KEY'

Implementation note: The endpoint name above reflects the Pactman single-EIN Nonprofit Check endpoint used in Pactman's Production/Customer Environment.

curl --request POST \
  --url https://entities.pactman.org/api/entities/nonprofitcheckbulk/v1/us/eins \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    "YOUR_EIN_1",
    "YOUR_EIN_2",
    "YOUR_EIN_3",
    "YOUR_EIN_4",
    "YOUR_EIN_5"
  ]'

Implementation note: The endpoint name above reflects the Pactman single-EIN Nonprofit Check endpoint used in Pactman's Production/Customer Environment.

What your application should evaluate

Signal	Why it matters	Typical application decision
`ein` / `organization_name`	Confirms the API response belongs to the organization your application intended to verify.	Continue only when the returned identity matches the expected nonprofit.
`bmf_status` and IRS classification	`bmf_status` indicates whether the organization appears in the IRS Business Master File data used by Pactman, while `bmf_subsection`, `subsection_description` and `exempt_status_code` preserve tax-exempt classification.	Use as core IRS-status inputs to the application's rules engine.
`pub78_verified`	Indicates whether the organization is included in the most recent Publication 78 data used by Pactman.	Use when Pub. 78 inclusion or contribution eligibility matters to the workflow.
`organization_types`	Contains contribution information including `organization_type`, `deductibility_limitation` and `deductibility_status_description`.	Preserve the contribution classification rather than turning Pub. 78 into only a boolean.
Foundation classification	`foundation_code`, `foundation_code_description`, `foundation_509a_status`, `foundation_type_code` and `foundation_type_description` preserve public-charity/private-foundation context.	Apply rules appropriate to the returned organization classification.
Filing and group context	`filing_req_code` identifies the filing requirement context, while `group_exemption` preserves group-exemption information.	Use when those IRS attributes affect eligibility or exception handling.
Revocation fields	`revocation_code`, `revocation_date` and `reinstatement_date` expose revocation-related history.	Evaluate reinstatement before treating historical revocation information as current disqualification.
`ofac_status`	Returns the organization's OFAC SDN screening result.	Apply sanctions-screening policy separately from IRS eligibility logic.
`irs_bmf_pub78_conflict`	Indicates whether BMF and Pub. 78 differ on private-foundation classification.	Route conflicts through source-aware logic instead of silently selecting one source.
Freshness fields	`most_recent_bmf`, `most_recent_pub78`, `organization_info_last_modified` and `report_date` provide timing context for the result.	Use them to decide whether to accept the existing result, re-run verification, or trigger review.

Example decision logic

A production application might create an internal verification result only after it has:

matched ein and organization_name to the intended nonprofit;
evaluated the BMF fields required by the workflow;
evaluated pub78_verified and organization_types when Pub. 78 or contribution eligibility matters;
preserved foundation, filing and group-exemption context;
reviewed revocation and reinstatement information;
evaluated ofac_status;
handled irs_bmf_pub78_conflict and religious-organization exception messages; and
considered the source dates before treating the response as current.

The supplied bulk sample demonstrates the normalized model. For EIN "680343125", Pactman returns bmf_status: true, bmf_subsection: "03", subsection_description: "501(c)(3) Public Charity", pub78_verified: true, foundation_type_code: "pc" and foundation_type_description: "Public charity described in section 509(a)(1) or (2)". The same record has revocation_code, revocation_date and reinstatement_date as null, and its ofac_status states that the organization was not included in the OFAC SDN list.

Important: Do not invent a universal verified field in your application and discard the underlying data. Store or retain the source signals needed by your policy so a rule can be changed, explained or re-evaluated without losing the original verification context.

Why use a consolidated nonprofit verification API?

Without a consolidated API, an application may need separate ingestion and normalization pipelines for IRS BMF, Publication 78, revocation and sanctions-related information. It must also decide how to reconcile source dates, foundation classification and conflicting records.

Pactman Nonprofit Check Plus exposes those signals through one normalized response model. The supplied single-EIN and bulk examples use the same current 43 organization-level fields, which lets an application reuse the same evaluation layer for interactive checks and batch workflows.

One normalized response

Create one internal nonprofit-verification object from the Pactman response instead of maintaining a separate application model for each source.

Separate source signals

Keep bmf_status, pub78_verified, foundation fields, revocation fields, ofac_status and irs_bmf_pub78_conflict distinct so your rules engine retains source meaning.

Reusable compliance rules

Map the normalized response into configurable rules for onboarding, donation processing, grantmaking, donor-advised funds, fintech workflows or recurring reviews instead of embedding one hard-coded definition of verification throughout the application.

Developer-friendly automation

Trigger verification from application events such as nonprofit onboarding, transaction setup, grant review or scheduled rechecks, then use the returned fields to drive the next workflow state programmatically.

Frequently asked questions

Should my application store only a pass/fail verification result?

No. Keep the source fields your policy depends on. A single pass/fail value makes it harder to explain why a decision was made or to re-evaluate an organization after your business rules change.

Can the same logic be used for single and bulk verification?

Yes. The supplied single and bulk examples expose the same current organization-level response fields. Build the rule-evaluation layer around the organization record so it can be reused whether one EIN or multiple EINs are being processed.

How should my application handle IRS source conflicts?

Evaluate irs_bmf_pub78_conflict together with the BMF and Pub. 78 classification fields and their source dates. Preserve the conflict and route it according to your workflow instead of silently selecting one source.

How should I decide when to re-run verification?

Use most_recent_bmf, most_recent_pub78, organization_info_last_modified and report_date as freshness inputs. Your application can use those dates with its own policy to decide when a prior result is too old for the current workflow.

Next step

Build a verification service in your application that accepts an EIN, calls Pactman, stores the source signals required by your policy, applies configurable business rules, and returns a workflow-specific result without hiding the underlying IRS, Pub. 78, revocation, OFAC, conflict and freshness data.

Ready to automate nonprofit verification?

Use Pactman Nonprofit Check Plus API to connect nonprofit verification directly to your application.

Get an API Key →