Developer Documentation

Contact Lists API Reference

Create and manage static and smart contact lists. Add and remove contacts, manage list tags, and trigger smart rule evaluation.

Contact Lists

Create and manage contact lists for segmentation, targeting, and campaign organization. FundraiserMax supports two list types: Static lists with manual membership and Smart lists with rule-based automatic membership. All list operations require the lists:read or lists:write scopes.

GET/v1/contact-lists

List contact lists with optional search, type filtering, and pagination.

Name	Type	Required	Description
`search`	string	No	Search by list name.
`type`	string	No	Filter by type: STATIC or SMART.
`limit`	number	No	Max results (default 25, max 100).
`offset`	number	No	Pagination offset.
`sortBy`	string	No	Field to sort by.
`sortOrder`	string	No	ASC or DESC.

curl -X GET "https://api.fundraisermax.com/api/v1/contact-lists?type=STATIC&limit=10" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret"

Response

{
  "lists": [
    {
      "id": "lst_abc123",
      "name": "Major Donors",
      "description": "Donors who have contributed $1,000+",
      "type": "STATIC",
      "tags": ["vip", "fundraising"],
      "isActive": true,
      "memberCount": 42,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 1
}

GET/v1/contact-lists/:id

Get a single contact list by ID, including member count and smart list rules.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).

curl -X GET "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret"

POST/v1/contact-lists

Create a new contact list. Use type STATIC for manual lists or SMART for rule-based automatic membership.

Name	Type	Required	Description
`name`	string	Yes	List name.
`type`	string	Yes	STATIC or SMART.
`description`	string	No	Optional description.
`tags`	string[]	No	Tags for list organization.
`campaignId`	string	No	Associate with a campaign.
`rules`	object[]	No	Smart list rules (required for SMART type).

curl -X POST "https://api.fundraisermax.com/api/v1/contact-lists" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gala 2026 Invitees",
    "type": "STATIC",
    "description": "Invite list for the 2026 annual gala",
    "tags": ["gala", "2026"]
  }'

PUT/v1/contact-lists/:id

Update an existing contact list.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`name`	string	No	Updated name.
`description`	string	No	Updated description.
`tags`	string[]	No	Updated tags.

curl -X PUT "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "Gala 2026 VIP Invitees", "tags": ["gala", "2026", "vip"]}'

DELETE/v1/contact-lists/:id

Soft-delete a contact list.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).

curl -X DELETE "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret"

GET/v1/contact-lists/:id/contacts

Get paginated contacts that are members of a list.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`search`	string	No	Search by name or email.
`limit`	number	No	Max results (default 25, max 100).
`offset`	number	No	Pagination offset.

curl -X GET "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/contacts?limit=25" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret"

POST/v1/contact-lists/:id/contacts

Add contacts to a static list. Maximum 100 contacts per request. Cannot add to smart lists.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`contactIds`	string[]	Yes	Array of contact IDs to add (max 100).
`notes`	string	No	Optional notes about the addition.

curl -X POST "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/contacts" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["cnt_111", "cnt_222", "cnt_333"]}'

DELETE/v1/contact-lists/:id/contacts

Remove contacts from a list. Maximum 100 contacts per request.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`contactIds`	string[]	Yes	Array of contact IDs to remove (max 100).
`reason`	string	No	Optional reason for removal.

curl -X DELETE "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/contacts" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["cnt_111"], "reason": "Unsubscribed"}'

POST/v1/contact-lists/:id/tags

Add tags to a contact list. Duplicates are ignored.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`tags`	string[]	Yes	Tags to add.

curl -X POST "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/tags" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["priority", "q1-2026"]}'

DELETE/v1/contact-lists/:id/tags

Remove specific tags from a contact list.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).
`tags`	string[]	Yes	Tags to remove.

curl -X DELETE "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/tags" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["priority"]}'

POST/v1/contact-lists/:id/apply-rules

Trigger smart rule evaluation for a smart list. Re-evaluates all rules and updates membership automatically. May take several seconds for large accounts.

Name	Type	Required	Description
`id`	string	Yes	Contact list ID (path).

curl -X POST "https://api.fundraisermax.com/api/v1/contact-lists/lst_abc123/apply-rules" \
  -H "X-API-Key: fmx_your_key_id" \
  -H "Authorization: Bearer your_api_secret"