> ## Documentation Index > Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt > Use this file to discover all available pages before exploring further. # Integration Pathway > The end-to-end workflow for technology and integration partners — from MNDA signing through marketplace listing. Each milestone explained with the partner action and the Virtuous action 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 | Scenario | This pathway applies | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | You're building an integration between your product and Virtuous (CRM+, Raise, or Volunteer) | ✓ | | You're maintaining or extending an existing integration | Partial — sections on review and validation still apply | | You're using the API for internal-only purposes (no third-party customers) | ✗ The Pathway is for integrations that other nonprofits will use | | You're a service partner (no software) | ✗ See [Becoming a Partner](/virtuous/partners/becoming-a-partner) instead | *** ## The full pathway ```mermaid theme={null} graph TD Start([Start]) MNDA["1. Sign MNDA"] Sandbox["2. Sandbox access granted"] Review["3. Review API resources"] Craft["4. Craft prototypes / mockups"] Submit1["5. Submit prototypes to Virtuous"] Gate1{"Virtuous reviews + approves"} Dev["6. Development begins"] MidCheck["7. Mid-build check-in"] Gate2{"Virtuous reviews + approves demo"} Complete["8. Complete development"] Docs["9. Create user-facing documentation"] Contacts["10. List contacts for support, sales, dev"] Submit2["11. Submit everything to Virtuous"] Gate3{"Virtuous reviews + certifies"} Marketplace["12. Marketplace listing access"] Finish([Finish]) Start --> MNDA MNDA --> Sandbox Sandbox --> Review Review --> Craft Craft --> Submit1 Submit1 --> Gate1 Gate1 --> Dev Dev --> MidCheck MidCheck --> Gate2 Gate2 --> Complete Complete --> Docs Docs --> Contacts Contacts --> Submit2 Submit2 --> Gate3 Gate3 --> Marketplace Marketplace --> Finish ``` 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: | # | Milestone | Partner action | Virtuous action | | - | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | 1 | **MNDA + sandbox access** | Sign the Mutual NDA so we can share confidential information about the API and your integration | Approve the MNDA and provision your sandbox environment | | 2 | **Prototype review** | Submit initial prototypes or mockups for the planned integration so Virtuous can give feedback before you invest in development | Review prototypes and approve to proceed (or provide feedback if changes are needed) | | 3 | **Development** | Start coding within the sandbox using the Virtuous APIs and provided resources | Reach out if you need assistance — we're a Slack message or email away | | 4 | **Mid-build check-in** | Create a recorded demo to showcase the integration's current state — covering configuration, workflows, and data flow — to ensure alignment | Review the demo and approve to proceed to final development (or flag concerns early) | | 5 | **Final submission + documentation** | Complete development and submit the final build along with user-facing documentation for Virtuous review | Review and certify the integration | | 6 | **Marketplace listing** | Update your marketplace listing with positioning, screenshots, and customer-facing details | Provide access for you to manage your marketplace listing | 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](/virtuous/partners/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:** | Resource | Purpose | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Sandbox environment | A non-production Virtuous instance for development and testing | | API documentation | The public docs for [CRM+](/crm/overview), [Raise](/raise/overview), and [Volunteer](/volunteer/overview) — relevant depending on what you're building | | OAuth credentials | For CRM+ and Raise integrations; or Bearer token for Volunteer | | Partner Portal resources | Sample data, design assets, integration templates | | Your Partner Manager | The point of contact for product questions, scoping, and unblockers | **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:** | Question | Why it matters | | ------------------------------------------------------------- | ---------------------------------------------------------------------- | | What's the customer onboarding flow? | Determines where OAuth happens and how scopes get authorized | | How do you detect changes in Virtuous data? | Webhooks (CRM+, Raise) vs. polling (Volunteer) shapes the architecture | | How does your product handle Virtuous outages or rate limits? | Affects perceived reliability for customers | | What's the smallest end-to-end useful integration? | Helps scope v1 — you can always add features later | | How will customers see the integration is working? | Monitoring and visibility for them, not just for you | | Where does data live, and who's responsible for it? | Important for both compliance and customer expectations | **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: | Review focus | What we're checking | | -------------------------- | ----------------------------------------------------------------------- | | Customer experience | Does the integration solve a real customer problem clearly? | | Data flow correctness | Are you using the right endpoints and patterns? | | API usage patterns | Are you handling pagination, rate limits, error recovery appropriately? | | Webhook vs. polling design | Are you using the right change-detection mechanism? | | Scope realism | Is v1 achievable and valuable? Is later scope on a sensible roadmap? | | Documentation completeness | Will customers be able to install and operate the integration? | 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](/crm/overview) — concepts, workflows, webhooks, integration recipes, and best practices. **For Raise integrations,** see the [Raise API docs](/raise/overview) — same structure, focused on donation and donor data. **For Volunteer integrations,** see the [Volunteer API docs](/volunteer/overview) — 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: | Section | Contents | | --------------------- | ---------------------------------------------------------------------------- | | Overview | What the integration does and what value it provides | | Prerequisites | What customers need to have set up (Virtuous account, your account, billing) | | Installation / setup | Step-by-step setup including authorization and configuration | | Configuration options | The settings customers can adjust and what each one does | | Data flow | What data moves between systems and how often | | Common workflows | The most-used customer scenarios with walkthroughs | | Troubleshooting | Common issues and how to resolve them | | Support contact | How customers reach you for help | | FAQ | Frequently asked questions from customers | 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: | Contact type | Who Virtuous reaches out to for... | | ------------------------------- | ------------------------------------------------------------------------------------- | | Support | Customer issues with the integration; technical questions from shared customers | | Sales | Joint opportunities; new customer introductions; co-selling conversations | | Development | Integration changes; API questions; production issues that need engineering attention | | Partner Manager (Virtuous-side) | Your dedicated contact at Virtuous for relationship and program questions | You'll provide these contacts as part of your final submission. They can be individuals or shared aliases ([support@yourcompany.com](mailto: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: | Review focus | What we're checking | | ----------------------- | ---------------------------------------------------------------------------- | | Technical functionality | The integration does what it says it does, reliably, in realistic scenarios | | API usage hygiene | Rate-limit respect, error handling, pagination, idempotency | | Customer experience | Setup is clear; data flow is observable; failures are visible | | Documentation quality | A nonprofit customer could install and operate the integration from the docs | | Support readiness | Contact list complete; clear path for customer escalation | | Marketing assets | Listing copy is accurate, screenshots are current, branding is consistent | 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). *** ## What comes next The Integration Pathway gets you to launch, but partnership is ongoing: | Activity | Cadence | | ---------------------------- | -------------------------------------------------------------------------------------------------- | | Partner Manager check-ins | Quarterly or as appropriate; more frequent during active GTM work | | Customer escalation handling | As needed; your Partner Manager is the bridge | | Integration maintenance | Continuous — as APIs evolve and customer needs change | | Co-marketing opportunities | Ongoing — webinars, blog spotlights, joint content, conference moments | | Tier reviews | Periodic — see [Partner Types and Tiers](/virtuous/partners/partner-types-and-tiers#partner-tiers) | | Roadmap conversations | Periodically, especially for partners actively shaping their integration | 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](/crm/best-practices/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](/crm/best-practices/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 The application process that precedes the Integration Pathway. The Partner Portal, Academy, Marketplace, and resources you'll use throughout the pathway. For CRM+ integrations — concepts, workflows, webhooks, and best practices. For Volunteer integrations — including the polling patterns specific to this API.