Integration Pathway

The Integration Pathway is the canonical workflow for technology and integration partners building against the Virtuous APIs. It exists for a reason: integrations that nonprofits depend on need to be well-designed, well-tested, and well-supported. This pathway ensures that by the time your integration is in the marketplace, it’s been thoughtfully reviewed at every stage — and that you have everything you need to support customers using it. This page walks through the pathway step by step. Each milestone has a partner action and a Virtuous action — both sides have work to do at every step.

​

When this applies

---

​

The full pathway

The pathway has three review gates where Virtuous formally reviews and approves your progress: after prototypes, after the mid-build demo, and after the final submission. Each gate ensures alignment before you invest further effort.

---

​

The major milestones

The pathway distills into six major milestones, each with paired partner and Virtuous actions: The detailed sections below walk through each step in the full flowchart.

---

​

Step 1: Sign the MNDA

Before we can share sandbox access or discuss your integration in technical depth, both parties need a Mutual Non-Disclosure Agreement (MNDA) in place. Why it matters:

• Protects both sides during the design and build conversations
• Allows Virtuous to share details about the API, roadmap, and customer use cases
• Allows you to share details about your product, customer base, and proposed integration

What you do:

• Apply through the Partner Portal (if you haven’t already — see Becoming a Partner)
• Review and sign the MNDA when sent

What Virtuous does:

• Reviews and counter-signs the MNDA
• Provisions your sandbox environment once the MNDA is in place

---

​

Step 2: Sandbox access and resource review

Once the MNDA is signed, you’ll receive credentials for a Virtuous sandbox environment. This is where you’ll develop and test your integration without touching real customer data. Resources you’ll have access to: What you do:

• Familiarize yourself with the API documentation for the products your integration touches
• Test authentication and basic API calls against the sandbox
• Identify any spec gaps or questions before you start design work

What Virtuous does:

• Makes sure your sandbox is provisioned and accessible
• Connects you with the right technical contacts if you have questions

---

​

Step 3: Craft prototypes or mockups

Before you start coding, design the integration. This is where you think through:

• Data flow — what data moves in which direction, and when
• Authentication and authorization — how customers will connect Virtuous to your product
• User experience — what customers see and configure in your product, and what they see in Virtuous
• Error handling — what happens when API calls fail, when data is missing, when something needs human attention
• Sync semantics — push vs. pull, polling cadence, real-time vs. batch
• Scope — what’s in v1 of the integration vs. what’s planned for later

The goal isn’t perfection — it’s a clear enough design that Virtuous can give meaningful feedback before you build. Useful design questions: What to submit: Prototypes or mockups that convey the design — these can be:

• Visual mockups of the customer-facing experience
• Architecture diagrams showing data flow
• Written design docs covering scope, sync model, and integration logic
• A combination of any of the above

The format matters less than the clarity. Your Partner Manager can share examples of what successful submissions have looked like.

---

​

Step 4: First review gate (Virtuous reviews prototypes)

Virtuous reviews your prototypes and provides feedback. Common things we look at: If everything looks good, we approve and you proceed to development. If there are concerns, we’ll work through them with you before signing off — better to surface design issues now than after you’ve built. Typical review timing: A few business days, depending on complexity.

---

​

Step 5: Development

With prototypes approved, you build the integration. During this phase:

• You’re coding against the sandbox
• You can reach out to your Partner Manager (and through them, to the API team) for technical questions
• The relevant API documentation is your day-to-day reference

For CRM+ integrations, see the CRM+ API docs — concepts, workflows, webhooks, integration recipes, and best practices. For Raise integrations, see the Raise API docs — same structure, focused on donation and donor data. For Volunteer integrations, see the Volunteer API docs — same structure, but note that Volunteer uses polling rather than webhooks. What you do:

• Build the integration against the sandbox
• Test with realistic data scenarios
• Implement the customer-facing flow (settings, monitoring, error visibility)
• Build the documentation as you go (you’ll need it for the final submission)

What Virtuous does:

• Stays available for questions
• Doesn’t formally review during this phase (the next review gate is the mid-build check-in)

​

When to reach out during development

Don’t wait until the mid-build demo to surface blockers. Reach out if:

• You hit a spec gap or unexpected API behavior
• You’re considering a significant deviation from the approved prototype
• You’re stuck on auth, webhook signature verification, pagination, or another foundational integration concern
• Customer expectations have shifted in a way that affects scope

The mid-build demo is for showing progress — not for surfacing crises. Earlier conversations save everyone time.

---

​

Step 6: Mid-build check-in

Roughly midway through development (timing depends on scope), you record a demo showing the integration in its current state. This demo:

• Showcases the integration’s working state
• Covers configuration (how customers set it up), workflows (what they do with it), and data flow (what moves between systems)
• Lets Virtuous confirm direction before you invest in the final polish

What you do:

• Record a demo (typically 10-20 minutes — long enough to cover meaningfully, short enough to be reviewable)
• Highlight the parts you’re confident in and the parts you’d appreciate feedback on
• Share the demo with your Partner Manager

What Virtuous does:

• Reviews the demo for direction, completeness, and alignment with the approved prototype
• Approves to proceed to final development, or flags concerns to address before you continue

This is the second review gate. By the time you pass it, the integration’s shape should be clear and you’re in execution mode for the remaining work.

---

​

Step 7: Complete development

With the mid-build check-in passed, finish the build:

• Polish customer-facing flows
• Round out edge cases (error states, empty states, recovery paths)
• Performance and reliability tuning
• Integration testing across realistic scenarios

The goal: a build that’s ready to support real nonprofits, not just to demo.

---

​

Step 8: Create user-facing documentation

User-facing documentation is required for marketplace listing. This is documentation for the nonprofit customer — not for you and not for Virtuous engineers. It should cover: Style notes for partner-built customer docs:

• Customer-facing voice (not internal voice)
• Screenshots where they help
• Plain language — don’t assume technical sophistication
• Linkable, searchable, kept current as the integration evolves

---

​

Step 9: List contacts for support, sales, and development

For mutual customers to be supported well, Virtuous needs to know who to reach at your organization for different conversations: You’ll provide these contacts as part of your final submission. They can be individuals or shared aliases (support@yourcompany.com is fine); what matters is that someone responsive is on the other end.

---

​

Step 10: Submit everything to Virtuous

The final submission package includes:

• The completed integration
• User-facing documentation
• Customer-facing screenshots / marketing assets for the marketplace listing
• The contact list for support, sales, and development
• Any additional materials your Partner Manager has asked for (security disclosures, privacy practices, etc.)

The submission triggers the third and final review gate.

---

​

Step 11: Final review (Virtuous reviews and certifies)

Virtuous reviews the complete submission. The review covers: When everything is approved, Virtuous certifies the integration. This is the formal sign-off that the integration meets program standards. Typical review timing: Longer than the earlier gates — usually a couple of weeks depending on integration complexity and the volume of items being reviewed.

---

​

Step 12: Marketplace listing and launch

With certification complete:

• Virtuous provisions your marketplace listing access
• You finalize the listing — positioning, screenshots, descriptions, FAQs
• Your integration becomes visible to nonprofits browsing the marketplace
• You can begin co-marketing and customer outreach with marketplace presence as a credential

🎉 You’re done with the pathway. From here, the relationship enters its ongoing phase — see What comes next.

---

​

What comes next

The Integration Pathway gets you to launch, but partnership is ongoing: The integration also evolves. The first version is rarely the last. Plan for:

• Iterating on the integration as customer feedback comes in
• Tracking changes to the Virtuous APIs (see Versioning and Backward Compatibility in CRM+, or the equivalent in Raise / Volunteer)
• Periodic updates to your customer-facing documentation
• Renewed certification if you significantly change the integration’s scope

---

​

Common questions

​

How long does the full pathway typically take?

It varies dramatically by integration complexity. A simple one-way data sync might complete in 6-8 weeks. A bidirectional integration with multiple Virtuous products and rich workflows can take several months. Plan for the pathway, not against it — the review gates exist to catch design issues early, which saves time overall.

​

Can we skip the review gates?

No. The gates exist for good reason — they ensure alignment before you’ve invested too much effort in the wrong direction. Skipping reviews almost always means redoing work later.

​

What if Virtuous changes the API mid-pathway?

We try not to. If a significant API change is planned that would affect your integration, your Partner Manager will let you know and we’ll figure out the path forward together. For minor changes, the defensive parsing practices in the API docs (see Versioning and Backward Compatibility) protect against most disruption.

​

What if our integration scope changes during development?

Significant scope changes typically require an updated prototype review. Minor changes within the original scope are fine — your Partner Manager is the right person to discuss whether a change warrants formal re-review.

​

What if we need to maintain multiple integrations across CRM+, Raise, and Volunteer?

That’s common. The pathway accommodates multi-product integrations from the start — the prototype submission identifies which products are involved, and the relevant reviewers are pulled in. Many integrations span at least two products.

​

Can we begin marketing the integration before it’s certified?

We ask that you wait until certification is complete before publicly announcing the integration. Pre-certification marketing creates customer expectations that may not be met if changes are needed during final review.

​

What happens if the final review surfaces required changes?

Your Partner Manager will share specific feedback and timelines. Most final-review feedback is addressable — significant rework is rare if the earlier gates were thorough.

---

​

Where to go next