Donorperfect API

DonorPerfect Online XML API

Reference for integrating with the DonorPerfect Online (DP) XML API (SofterWare, Inc.) — User Manual v7.1, corresponding to DonorPerfect Online 2024.02.16. The DP API is an HTTPS-only XML-returning API exposing both predefined stored-procedure-like calls and ad-hoc SQL SELECT queries against the underlying MS SQL Server 2019 database.

Base URL

https://www.donorperfect.net/prod/xmlrequest.asp

All requests are HTTPS GET. There is one endpoint — operations are dispatched via the action query parameter.

Authentication

Single API key per DP user account, provided by DonorPerfect Support / API Help Desk (api@softerware.com).

?apikey=<your-api-key>

Audit trail: Most write calls accept an @user_id parameter (≤20 chars) for audit logging. This is a free-form string — not validated against actual DP users. Use your application name (e.g., 'MyAppName') so changes can be attributed.

Request Anatomy

https://www.donorperfect.net/prod/xmlrequest.asp?apikey=xxxxx&action=dp_gifts&params=@donor_id=640

Parameter Formats

Named parameters (recommended — order-independent, easier to debug):

&params=@donor_id=0, @first_name='Orianthi', @last_name='Panagaris', @user_id='MyAppName'

Positional parameters (legacy, still supported):

&params=0,'Orianthi','Panagaris',null,null,...

Response Format

All responses are XML. Each row is a <record> containing one <field> per column:

<result>
  <record>
    <field name="donor_id" id="donor_id" value="147"/>
    <field name="first_name" id="first_name" value="Orianthi"/>
    <field name="last_name" id="last_name" value="Panagaris"/>
    ...
  </record>
</result>

For create/update calls, the result is a single <field> with the new/affected ID:

<result>
  <record>
    <field name="" id="" value="10230" />
  </record>
</result>

Limits & Admin

Two Execution Modes

The DP API has two distinct ways to call it. Prefer Predefined Procedures whenever one fits.

1. Predefined Procedures

Stored-procedure-style calls. Invoked as action=dp_<name> with &params= containing named parameters.

2. Dynamic Queries (SQL SELECT)

Raw ANSI SQL passed as the action value — runs against the underlying MS SQL Server 2019 database.

&action=SELECT donor_id, first_name, last_name FROM dp WHERE last_name = 'bacon'

Supports JOIN, wildcards (%), TOP N, ORDER BY, COALESCE, etc. Only the SQL features documented in this skill are guaranteed to work — DP supports a limited SQL subset.

Avoid SELECT * in production code — slow and brittle to schema changes. Use it only for ad-hoc exploration of a single record.

Predefined Procedures

Donor / Constituent

Gifts, Pledges, EFT

Tributes (In Honor Of / In Memory Of)

Custom Fields, Codes, Checkboxes, Flags

Full parameter tables for every procedure are in references/procedures.json.

Database Tables (Dynamic Queries)

Sources of truth for SELECT-style retrieval and for understanding the data model behind the procedures.

Full column lists and notes are in references/tables.json.

Key Entities & Relationships

Common Patterns

Pagination Around the 500-Row Limit

SELECT TOP 500 code, description FROM dpcodes
WHERE field_name='SOLICIT_CODE' AND code > '{last code}'
ORDER BY code

Delta Sync — Recent Gift Changes

SELECT TOP 500 gift_id, amount, created_date, modified_date, gl_code
FROM dpgift
WHERE COALESCE(DPGIFT.MODIFIED_DATE, DPGIFT.CREATED_DATE) >= '{date}'
  AND gift_id > {last_gift_id}
ORDER BY gift_id

COALESCE returns modified_date if non-null, otherwise created_date — so new and modified gifts both come through.

Created / Modified Audit Fields

Not directly writable, but populated automatically:

• @user_id → created_by on new records, modified_by on updates to existing records
• created_date → today on new records
• modified_date → today on updates to existing records

Soft Credits

A soft credit recognizes Donor B for a gift that Donor A actually made.

RECORD_TYPE = 'S'
DONOR_ID    = <recognized donor>
GLINK       = <gift_id of the actual gift>
AMOUNT      = <same as actual gift>

Create with dp_savegift with @record_type='S' and @glink=<actual gift_id>.

Split Gifts

A split gift divides one transaction across multiple designations (e.g., $100 split $75 Building Fund / $25 General).

Create Main first, then each child with glink=<main gift_id>.

Pledges & Pledge Payments

1. Create the parent pledge with dp_savepledge — RECORD_TYPE='P', @total, @bill, @frequency (M/Q/S/A).
2. For EFT auto-processing, set the parent pledge's DPGIFTUDF.EFT='Y' using dp_save_udf_xml:

   action=dp_save_udf_xml&params=@matching_id={pledge gift_id}, @field_name='EFT',
     @data_type='C', @char_value='Y', @date_value=null, @number_value=null, @user_id='MyApp'
   

3. Populate @vault_id on the pledge with the SafeSave Vault ID — required for the pledge to be active.
4. Create a payment method via dp_PaymentMethod_Insert (after creating the SafeSave Customer Vault ID).
5. Subsequent pledge payments are regular gifts (dp_savegift with @record_type='G', @pledge_payment='Y', @plink=<parent pledge gift_id>) — or DP processes them automatically via EFT once set up.

Gift Adjustments (e.g., Refunds)

DonorPerfect represents an adjustment as a three-record chain:

Workflow:

1. SELECT existing gift to capture all field values.
2. Update original gift via dp_savegift setting @record_type='A' (everything else unchanged).
3. Create Adjustment gift via dp_savegift with delta amount and @glink.
4. Create Resulting gift via dp_savegift with new amount, @alink, and gift_narrative appended.

If the original gift had UDF or other extra field data, the Resulting gift should mirror it.

Checkbox Fields vs. Flags

These are NOT the same — keep them separate:

Reading currently-set checkbox values:

SELECT field_name, matching_id, code FROM dpusermultivalues
WHERE field_name='DONINTS' AND matching_id={donor_id}

Reading currently-set flags:

SELECT * FROM dpflags WHERE donor_id={donor_id}

Discovering valid codes for a field:

SELECT code, description FROM dpcodes WHERE field_name='{field name}'

Tributes Workflow

To add a tribute and notify a recipient about one specific gift:

1. Lookup or create the tribute. Use dp_tribAnon_Search to find existing, or dp_tribAnon_Create with @DPCodeID from SELECT CODE, CODE_ID, DESCRIPTION FROM DPCODES WHERE FIELD_NAME='MEMORY_HONOR' (typically 707=In Honor Of, 708=In Memory Of).
2. Associate to the gift with dp_tribAnon_AssocTribsToGift.
3. Add a recipient for this gift with dp_tribAnon_SaveTribRecipient (named-parameter syntax required).
4. Create the notification record with dp_tribNotif_Save — most fields mirror the original gift; markers are @gift_type='SN', @record_type='N', @ty_letter_no='NT'.

To update the recipient list for ALL gifts on a tribute, use dp_tribAnon_Update — but you MUST include existing recipients or they'll be removed:

SELECT r.tributeid, t.name, r.donor_id, r.createddate, t.activeflg
FROM dptributesanon t, dptributesanon_recipients r
WHERE t.tributeid = r.tributeid AND t.tributeid = {desired tributeid}

Then call with @recipients=N'105|43256|323387|137' (pipe-delimited, N-prefixed).

User Defined Fields (UDFs)

dp_save_udf_xml writes to whichever UDF table matches your @matching_id:

Set ONE of @char_value / @date_value / @number_value based on @data_type (C/D/N); set the other two to null. The UDF field must already exist in the DP system (Code Maintenance > Field Definitions).

Codes (DPCODES) — Drop-Down Values

All coded fields (GL Code, Solicit Code, Campaign, Memory/Honor, Flag, Address Type, Donor Type, etc.) draw their valid values from DPCODES.

SELECT code, description FROM dpcodes WHERE field_name='{FIELD_NAME}'

Add/update via dp_savecode. Behavior of @original_code:

Set @inactive='N' to ensure the code shows in UI dropdowns.

Multi-Currency

Pass @currency='USD' / 'CAD' / etc. on dp_savegift and dp_savepledge. If omitted on a pledge, defaults to USD.

Receipt Delivery (@receipt_delivery_g)

Canadian sites also have @acknowledgepref: 1AR (Ack+Receipt), 2AD (Ack/no Receipt), 3DD (no Ack/no Receipt).

UK Gift Aid

DP includes these fields for the UK Gift Aid tax incentive program:

Quebec Law 25 (Privacy & Consent)

Stored as UDFs — must be present in the DP system before writing. Test first:

SELECT DISTINCT field_name FROM sd_field
WHERE field_name LIKE 'PM_%' OR field_name LIKE 'PO_%'

PM_* fields live on DPUDF (Main); PO_* fields live on DPTHERINFOUDF (Other Info):

Save via dp_save_udf_xml with @matching_id=@donor_id for PM_* and @matching_id=@other_id for PO_*.

Unicode

DP systems must be Unicode-enabled by Support to store UCS-2/UTF-16. Then prefix strings with N:

@first_name=N'Phúc cho những người'

Gotcha: dp_save_udf_xml does NOT currently support Unicode via the =N'xxx' syntax — Unicode characters land as ?. Workaround: contact DP API Desk.

URL Encoding Example (PHP)

$preamble = "https://www.donorperfect.net/prod/xmlrequest.asp?apikey=";
$key = "xxxxxxxxxxxxxxxxxx";
$action = "&action=dp_save_udf_xml&params=";
$payload = "@matching_id=640, @field_name='MRWMEMO', @char_value='Basic math = 5',
            @date_value=null, @number_value=null, @user_id='APITestCall'";
$encoded_APIcall = $preamble . $key . $action . urlencode($payload);

The apikey appears BEFORE urlencode(); only the payload is encoded.

Full Reference

For complete parameter tables, edge cases, and original sample calls, the PDF and structured JSON are in references/:

references/procedures.json                                 # All 25 procedures with full parameter tables
references/tables.json                                     # All DP tables with column lists and notes
references/DPO_SUP_Manual_XML_API_Documentation050324.pdf  # Source v7.1 (May 2024)

Search patterns:

• All procedures: jq '.procedures | keys' references/procedures.json
• One procedure: jq '.procedures.dp_savegift' references/procedures.json
• All tables: jq '.tables | keys' references/tables.json
• Table columns: jq '.tables.DPGIFT.key_columns' references/tables.json
• PDF deep dive: Read references/DPO_SUP_Manual_XML_API_Documentation050324.pdf with a pages range

Support

API support covers: call syntax, recommendations, error explanations, restoring API service after DP outages. It does NOT cover: writing/debugging your application, creating custom docs, or any work on code outside the DP API itself.

Disclaimer

This skill is not affiliated with, endorsed by, or sponsored by SofterWare or DonorPerfect. It references publicly available API documentation for educational and integration purposes. The information may be outdated or incomplete — always refer to the official DonorPerfect documentation and release notes for the most current API specifications. Field availability (e.g., Quebec Law 25 UDFs, Unicode, EFT) depends on per-client configuration and add-ons; always test for field presence before writing.