API Playground

The Virtuous API Docs include an interactive API Playground — every endpoint page lets you send real requests to the API, see real responses, and copy the resulting code into your project. Instead of reading a static reference page and then guessing how the request actually looks, you compose the request in the browser, fire it, and see exactly what happens. For partners building integrations, this is one of the most useful features in the docs: it collapses the gap between reading reference material and writing the actual code.

​

What the Playground does

When you open an endpoint page (e.g., a specific CRM+ Contact endpoint or a Volunteer Users endpoint), the page includes: Together, these turn each endpoint page into a tiny working API client.

​

When to use the Playground

The Playground is most useful in these scenarios: It’s not a substitute for writing production code, but it’s the fastest way to establish what works before you commit to an implementation.

​

Authentication in the Playground

Most Virtuous endpoints require authentication. The Playground supports this directly — you provide a token, the Playground includes it in the request, and you get a real authenticated response.

​

Where to put your credentials

The Playground exposes the authentication fields the endpoint requires. For Virtuous: For details on getting tokens for each product, see:

• CRM+ Authentication
• Raise Authentication
• Volunteer Authentication

​

Use sandbox tokens, not production tokens

​

Where your credentials are stored

When you paste a token into the Playground: Despite the storage convenience, treat the Playground like any other tool that handles your credentials — don’t paste tokens for accounts you don’t own, and clear stored tokens when you’re done.

​

Filling out parameters

Each endpoint’s Playground page shows every parameter the endpoint accepts. The form is organized by parameter location: For each parameter, the form shows:

• The parameter name
• The expected type (string, integer, array, etc.)
• Whether it’s required or optional
• A description of what it does
• Validation hints (allowed values, format expectations)

​

Prefilled examples

When the OpenAPI spec includes example values, the Playground typically prefills the form with those examples. This means for many endpoints, you can hit Send immediately with no edits and see a working response. From there, modify parameters to explore different cases.

​

Required vs. optional parameters

The Playground may show only required parameters by default, with optional parameters available behind a “Show optional” toggle. This keeps the form focused for quick exploration; expand it when you need to test edge cases.

​

Sending requests and reading responses

Once your parameters are filled in:

1. Click Send to fire the request
2. Wait for the response (typically a few hundred milliseconds for simple GETs; longer for complex queries)
3. Review the response:
   • HTTP status code (200, 201, 400, 401, 404, 422, 429, 500, etc.)
   • Response headers
   • Response body (usually JSON)

The response viewer formats JSON cleanly so you can read the actual field shape, nesting, and types — useful when the docs describe a resource and you want to see exactly what it looks like in practice.

​

Different response types

For most Virtuous endpoints, the response will be JSON.

​

Generated code samples

Beneath each Playground request is generated code that recreates the request you just configured. The code is generated based on the parameters you’ve filled in — change a parameter, and the code updates.

​

Available languages

The code samples are typically available in:

• cURL — the universal command-line option
• JavaScript — for Node.js or browser code
• Python — for Python integrations
• Go, Ruby, PHP, Java, C#, and others (depending on configuration)

You can switch languages to see your request in whatever your team writes in.

​

Using the generated code

The generated code is a starting point, not production code. A typical workflow:

1. Configure the request in the Playground
2. Send it; verify it works
3. Copy the generated code in your preferred language
4. Paste it into your integration as a reference
5. Adapt it to your code style, error handling, and authentication management

​

What the generated code does well

​

What the generated code doesn’t handle

Treat generated code as a starting scaffold. The actual production-grade integration patterns are in the Recipes and Best Practices pages.

​

Working with the OpenAPI specs

The Playground is generated from the OpenAPI specifications published with the docs. This means: When you want to see the full OpenAPI spec for a product, the AI Assistant can read it directly. You can also access the spec for direct inspection through the docs site’s OpenAPI integration.

​

Audit-flagged spec quirks

A reality worth knowing: the OpenAPI specs have some documented quirks (see audit findings referenced throughout the Concepts and Workflow pages). When the Playground shows spec-based information that differs from observed live behavior, the docs’ inline annotations call this out. When in doubt, trust the live response over the spec description. The Playground shows you the real API behavior; the spec is the documented expectation.

​

Practical workflows

A few patterns that emerge naturally when using the Playground.

​

”I’m starting on a new endpoint”

1. Navigate to the endpoint page in the docs
2. Read the description and required parameters
3. Paste in a sandbox token
4. Click Send with default (or example) parameters
5. Examine the response
6. Iterate — change parameters, observe what changes

​

”I’m writing code for this endpoint”

1. Navigate to the endpoint page
2. Configure the request with realistic parameters
3. Send; verify the response is what you expect
4. Switch the code sample to your language
5. Copy the code
6. Paste into your integration and add proper error handling, retry logic, pagination

​

”I’m debugging a failing API call”

1. Get the request your code is making (URL, headers, body)
2. Reproduce the request in the Playground
3. Send it
4. Compare:
   • If the Playground succeeds where your code fails → the issue is in your code (auth, header construction, JSON shape)
   • If the Playground also fails → the issue is in the request itself (wrong field, wrong endpoint, bad data)
5. Iterate until the Playground succeeds; then update your code to match

​

”I’m verifying a documented behavior”

1. Read the docs page describing the behavior
2. Construct the request the docs describe in the Playground
3. Send and observe — does the response match the documented behavior?
4. If yes, great. If no, the spec or the docs may have a known quirk (see audit annotations)

​

“I’m exploring an unfamiliar resource”

1. Navigate to the GET (list) endpoint for the resource
2. Send with default parameters
3. Examine the response — what fields exist on each item?
4. Navigate to the GET (detail) endpoint
5. Send for a specific item; see the fuller shape

This is often faster than reading the Concepts page when you want to see actual field shapes.

​

Playground limitations

A few things the Playground can’t do, by design: For workflows the Playground doesn’t cover, the docs’ Workflows, Recipes, and Best Practices groups are your reference.

​

Sharing a Playground state

Sometimes you want to share a specific Playground configuration with a teammate — “look at what this endpoint does.” A few patterns: For deeper context, pair the Playground reference with a link to the relevant Workflow or Recipe page.

​

Tips for getting the most out of the Playground

A few practices that consistently help:

​

Where to go next