List every Virtuous API resource group (Contact, Gift, Project, Event, Webhook, etc.) and how many endpoints each has. Read-only.

Use with list_endpoints to drill into a resource.

Discover Virtuous API endpoints across the ENTIRE API. Read-only.

Returns matching endpoints with their method, path template (with :placeholders), title, whether they read or write, and parameter names. Use the returned method+path with call_endpoint (or describe_endpoint first).

Get full metadata for a single endpoint (method, path, title, resource, read/write, path + query parameters). Read-only.

List Virtuous object types that can be queried/read, with descriptions.

Read-only. Use the returned keys with get_query_options, query_records, and get_record.

Get the queryable fields, data types, and allowed operators for an object type so you can construct a valid query. Read-only.

Run a read-only bulk query against a Virtuous object type. Read-only.

Auto-paginate a query and return up to max_records records. Read-only.

Convenience over query_records: instead of you managing skip/take, this loops through pages (each capped at 1000 by the API) until it has max_records, the result set is exhausted, or the QUERY_ALL_HARD_CAP safety ceiling is hit. Because every page is a request against the ORG-WIDE rate budget, keep max_records as small as the task needs and prefer a precise groups filter. The response includes a rate_limit snapshot so you can see remaining budget after the sweep.

Fetch a single record by id via GET /api/{object_type}/{record_id}. Read-only.

Find a single contact by email, or by reference source + id. Read-only.

Provide either an email or a reference_source + reference_id.

Fuzzy-search contacts by a free-text string. Read-only.

Get all gifts for a contact via GET /api/Gift/ByContact/{id}. Read-only.

Get notes for a contact. Read-only.

Get the individuals that make up a contact. Read-only.

Fetch a reference/lookup list (contact types, tags, custom fields, task types, project types, etc.) used to build queries or understand allowed values. Read-only.

Auto-paginates: these list endpoints default to only 10 rows server-side (a silent-truncation footgun — e.g. /api/OrganizationGroup has 30 groups but returned just 10, hiding the 'Pending Portfolio Assignment' holding group). When the response is a paged {"list", "total"} envelope this walks every page and returns the FULL list (with a returned count) so callers never reason over a truncated reference set.

Get the current organization and the API key's permissions. Read-only.

Useful to understand what the key is allowed to read/write before attempting any action.

Report the most recently observed Virtuous rate-limit headers. Read-only.

Virtuous enforces an ORG-WIDE request budget (documented at 5,000 requests/hour) shared by every API key/integration in the organization. This returns the latest X-RateLimit-Limit, X-RateLimit-Remaining, reset_at, and seconds_until_reset seen on a response — useful before kicking off a large batch or many queries. It is empty until at least one request has been made in this session, so a low remaining here reflects other integrations' usage too.

Escape hatch for arbitrary READ-ONLY GET requests to the Virtuous API.

Only GET is allowed here. Use when no dedicated read tool fits. Read-only.

Auto-page arbitrary read-only GET endpoints that use skip/take.

Use for list-style GET endpoints such as /api/Contact/ByTag/{tagId} or /api/OrganizationGroup/{id}/contacts. If the first response is not a {"list": [...], "total": N} envelope, the original response is returned.

MUTATING: create a new record via POST /api/{object_type}.

DO NOT call with confirm=true unless the user has explicitly approved creating this exact record. With confirm=false this performs no change and returns a preview to show the user. NOTE: to create Contacts/Gifts safely, prefer create_transaction (it runs through Virtuous matching/validation).

MUTATING: update a record via PUT /api/{object_type}/{record_id}.

DO NOT call with confirm=true unless the user has explicitly approved this exact change. With confirm=false this performs no change and returns a preview.

MUTATING: archive (or unarchive) a record via PUT /api/{object_type}/Archive/{id}.

DO NOT call with confirm=true unless the user explicitly approved it. With confirm=false this performs no change and returns a preview.

MUTATING + DESTRUCTIVE: delete a record via DELETE /api/{object_type}/{id}.

This permanently removes data. DO NOT call with confirm=true unless the user has explicitly approved deleting this exact record. With confirm=false this performs no change and returns a preview.

MUTATING: submit a Contact or Gift transaction (the recommended, matched/validated way to import contacts and gifts).

'contact' -> POST /api/Contact/Transaction 'gift' -> POST /api/v2/Gift/Transaction DO NOT call with confirm=true unless the user explicitly approved it. With confirm=false this performs no change and returns a preview.

MUTATING: submit a BULK import of contacts or gifts (the rate-limit-friendly, Virtuous-recommended way to load many records at once).

Virtuous best practices say: to load many gifts/contacts, post them through the BATCH endpoints rather than one transaction per call. This both runs the records through Virtuous's matching/validation/dedupe pipeline AND makes far fewer requests against the ORG-WIDE rate budget (one batch call instead of N).

'contact' -> POST /api/Contact/Batch 'gift' -> POST /api/v2/Gift/Transactions DO NOT call with confirm=true unless the user explicitly approved it. With confirm=false this performs no change and returns a preview (including how many records are in the batch).

MUTATING escape hatch for any write endpoint not covered by a dedicated tool (e.g. cancel a recurring gift, write off a pledge, send an email, toggle a webhook).

DO NOT call with confirm=true unless the user has explicitly approved this exact request. With confirm=false this performs no change and returns a preview. If the request is actually read-only it will be rejected — use read_request for reads.

Invoke ANY Virtuous API endpoint. This gives full coverage of the entire API.

Reads (GET, and POST to Query/QueryOptions/Search/Find/Proximity) run freely. WRITE endpoints (any other POST/PUT/PATCH/DELETE) MODIFY data and obey the confirmation policy: with confirm=false NO call is made and a preview is returned so you can show the user and ask. Only pass confirm=true after the user has explicitly approved the exact action.

Use list_endpoints / describe_endpoint to find the right method + path first.