engaging-networks-api

<essential_principles>

<authentication_overview> The Engaging Networks REST API provides programmatic access to fundraising pages, supporter data, and campaign metrics for nonprofit organizations.

Session-based authentication (two-step process):

1. Obtain API User token from EN admin (Settings -> API Users)
2. POST to /authenticate with API User token to get session token
3. Use session token in ens-auth-token header for all subsequent requests
4. Session tokens expire (typically 1 hour) - re-authenticate when expired
5. Store API User token securely in environment variables
6. Never expose tokens in client-side code or logs
7. Ensure IP addresses are whitelisted in API User settings

Two token types:

• API User Token: Permanent UUID from EN Admin, used ONLY for POST /authenticate
• Session Token: Temporary token from /authenticate response, used for all other API calls </authentication_overview>

<rate_limits_overview> Hard limits:

• 5,000 requests per hour per API user (EN-specific)
• 200 page processing requests per 5 minutes per IP
• HTTP 429 response when exceeded

Best practices:

• Implement exponential backoff with jitter
• Cache page metadata (changes infrequently)
• Use maximum pagination limit (100)
• Schedule data collection during off-peak hours </rate_limits_overview>

<regional_instances> EN has multiple deployments - use the correct one:

• US: https://us.engagingnetworks.app/ens/service
• US2: https://us2.engagingnetworks.app/ens/service
• CA: https://ca.engagingnetworks.app/ens/service

Note: EU and AU clients currently use the CA servers (ca.engagingnetworks.app). There are no separate eu. or au. endpoints at this time. If your organization was provisioned under an EU or AU label, use the CA base URL.

Check your EN admin panel URL to determine your region. </regional_instances>

<data_model> Core entities:

• Pages: Campaign pages (donation, advocacy, event, survey) with configuration
• Page Components: Reusable building blocks (code blocks, form blocks, templates, text blocks, thank-you emails, upsell lightboxes, display widgets)
• Supporters: Contact records with fields, questions, memberships, and suppression status
• Transactions: Donation/payment records accessed via supporter (NOT via page)
• Recurring Transactions: Recurring payment schedules per supporter
• Origin Sources: Acquisition channel tracking per supporter
• Export Jobs: Asynchronous bulk data exports from pre-configured queries
• Marketing Automations: Automated supporter journeys with stats
• Account: Audit log access

Typical integration flow:

1. Authenticate (POST /authenticate) to get session token
2. List pages by type (GET /page?type=dc&status=live)
3. Look up supporters (GET /supporter?email=... or GET /supporter/query)
4. Access supporter transactions (GET /supporter/{id}/transactions)
5. Manage origin sources (GET/POST/PUT/DELETE /supporter/{id}/originsource)
6. Run export jobs for bulk data (POST /exportjob, poll, download)
7. Process page submissions (POST /page/{id}/process) </data_model>

<error_handling_overview> Retry on:

• 429 (rate limit) - with exponential backoff
• 5xx (server errors) - with fixed delay

Don't retry:

• 400 (bad request) - fix the request
• 401 (unauthorized) - check token
• 403 (forbidden) - check permissions
• 404 (not found) - resource doesn't exist </error_handling_overview>

<data_privacy> This skill is a development assistant. Its primary purpose is helping you write, debug, and deploy code that uses the EN API — not acting as a live data operations proxy.

Recommended: use a sandbox or test EN account. All workflows work without real donor data.

Data flow awareness: When the agent executes EN API calls, response data is processed by the model provider's infrastructure (Anthropic, OpenAI, etc.). Any supporter PII in API responses — names, emails, addresses, donation history — is transferred to a third party during inference. Read operations expose PII even though they don't modify data.