blackbaud-re-nxt-sky-api

name

blackbaud-re-nxt-sky-api

description

Guide for building integrations with the Blackbaud Raiser's Edge NXT SKY API — the REST API for nonprofit fundraising CRM. Use this skill whenever the user mentions Blackbaud, Raiser's Edge, RE NXT, SKY API, nonprofit CRM API, constituent API, gift API, or is building any integration that reads/writes donor, gift, fundraising, campaign, or constituent data to/from Raiser's Edge NXT. Also trigger when you see references to api.sky.blackbaud.com, Bb-Api-Subscription-Key headers, or oauth2.sky.blackbaud.com endpoints in code.

Blackbaud Raiser's Edge NXT SKY API

This skill helps you build integrations against the Raiser's Edge NXT SKY API — Blackbaud's REST API for the industry-standard nonprofit fundraising CRM. RE NXT is used by nonprofits, foundations, and universities to manage donors ("constituents"), process gifts, run campaigns, and track major-gift pipelines.

How to use this skill

This file is a router. It gives you enough shared context to orient, then points you at a detailed reference file for whatever you're actually doing. Before writing integration code for a specific resource, open the matching reference file — it has the concrete endpoints, request/response JSON, field names, and the gotchas that are easy to get wrong (and which differ resource-to-resource). The references exist because the SKY API is large and inconsistent in places; guessing field names from memory is the main way integrations break.

Reference files live in references/. Read the one(s) relevant to the task; you rarely need more than one or two at a time.

Routing table

If the task involves…	Read
OAuth setup, tokens, refresh, getting a subscription key	references/authorization.md
Anything that calls the API (dates, money, pagination, rate limits, errors, dedup)	references/conventions.md
Finding, creating, or updating constituents (people/orgs); names, demographics	references/constituents.md
Addresses, emails, phones, online presences	references/contact-information.md
Linking constituents to each other (spouse, employer, board member)	references/relationships.md
Wealth/capacity scores, prospect ratings	references/ratings.md
Custom/attribute key-value data on a constituent	references/custom-fields.md
School/degree/class-year records	references/education.md
Tags/segments like "Board Member", "Alumni"	references/constituent-codes.md
Tracking touchpoints/tasks (calls, meetings, mailings)	references/actions.md
Free-text notes on a constituent	references/notes.md
Recording or reading gifts/donations, splits, payments, soft credits	references/gifts.md
Campaigns, funds, appeals, packages (the giving hierarchy)	references/fundraising-hierarchy.md
Major-gift pipeline / prospect opportunities	references/opportunities.md
Looking up valid values (titles, types, categories); the text-vs-ID problem	references/code-tables.md
Bulk extracts via saved RE lists or queries	references/lists-and-queries.md

If a task spans several resources (e.g. "sync a donor and their gift"), see the write sequencing section below, then read each resource's reference as you get to it.

The data model in one paragraph

The constituent is the hub — a person (Individual) or org (Organization) — and almost everything attaches to it by constituent_id. Contact info, relationships, ratings, custom fields, education, codes, notes, and actions are all constituent sub-resources. Gifts record money and tie to the Campaign > Fund > Appeal hierarchy through gift splits. Opportunities track prospective major gifts. Code tables define the valid values for categorized fields throughout. See the relevant reference for how each piece actually works.

Cross-cutting essentials (the things every call needs)

These apply everywhere. references/conventions.md and references/authorization.md cover them in full; this is the orientation.

• Base URL: https://api.sky.blackbaud.com, with per-API, per-version path prefixes — e.g. /constituent/v1/..., /gift/v1/..., /fundraising/v1/..., /opportunity/v1/..., /list/v1/..., /query/v1/....
• Every request needs two headers: Authorization: Bearer {access_token} and Bb-Api-Subscription-Key: {subscription_key}. Writes also need Content-Type: application/json.
• Access tokens expire after 60 minutes; refresh them (refresh tokens last 60 days and rotate on use). OAuth 2.0 Authorization Code Flow — see references/authorization.md.
• Money is an object, not a number: {"value": 100.0} everywhere amounts appear.
• Dates are inconsistent — some fields take a fuzzy date object {"y":2026,"m":3,"d":5} (partial dates allowed), others take ISO-8601 strings. Which is which is per-resource; the reference files flag it. Details in references/conventions.md.
• Writes return just the new ID ({"id":"1281"}), not the full record — GET it back if you need the whole thing. (Most creates return HTTP 200; gifts return 201.)
• List responses are an envelope: {"count": N, "value": [...], "next_link": "..."}. Paginate with limit/offset or by following next_link. See references/conventions.md.
• Rate limits: ~5 calls/second (exceeding → 429) and a daily call quota (exceeding → 403 with a quota message). Both send a Retry-After header — honor it. Details and backoff guidance in references/conventions.md.

Write sequencing (when pushing data in)

Order matters because of how records reference each other. The canonical sequence:

1. Search before creating a constituent to avoid duplicates — RE NXT does not enforce uniqueness. (references/constituents.md)
2. Create/update the constituent. (references/constituents.md)
3. Add contact info — addresses, emails, phones, online presences. (references/contact-information.md)
4. Ensure related orgs exist as constituents before linking (an employer must itself be a constituent). (references/constituents.md)
5. Create relationships between constituents. (references/relationships.md)
6. Write ratings / custom fields / codes — their categories must already exist in the relevant code table. (references/code-tables.md)
7. Resolve fund/campaign/appeal IDs, then record gifts with splits that reference those IDs and sum to the gift total. (references/fundraising-hierarchy.md, then references/gifts.md)

There are no idempotency keys — design retries around search-before-create / lookup-by-key so failures don't create duplicates. (references/conventions.md)

Official resources

• Developer Portal: https://developer.blackbaud.com/skyapi
• RE NXT API reference: https://developer.blackbaud.com/skyapi/products/renxt
• Authorization docs: https://developer.blackbaud.com/skyapi/docs/authorization
• API basics: https://developer.blackbaud.com/skyapi/docs/basics/

Each reference file ends with a link to the live endpoint docs for that resource — use it to confirm exact schemas, since Blackbaud adds fields over time.