Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header.

Authorization: Bearer mce_live_...

GET/v1/contributions

List contributions

Bearer token required. Include your API key in the Authorization header.

Returns a paginated list of contributions received by the committee. Supports filtering by reporting period, itemization status, and individual contributor. Results are ordered by date received, descending. Contributions are returned with their aggregate year-to-date totals, calculated using the MCE contributor-matching algorithm that normalizes names and groups by ZIP code.

Parameters

periodstring

Reporting period to filter by. Quarterly: "Q1", "Q2", "Q3", "Q4". Monthly: "1" through "12". Omit to return all periods.

yearinteger

Filter contributions by calendar year. Range: 2020--2100. Defaults to the current year.

itemizedboolean

Filter by itemization status. When true, returns only contributions where the donor aggregate YTD exceeds $200. When false, returns only unitemized contributions.

contributor_idstring

Filter contributions by donor UUID. Returns all contributions from this donor and any matched duplicates (same normalized name + ZIP).

cursorstring

Pagination cursor from a previous response. Pass the next_cursor value to retrieve the next page of results.

limitinteger

Maximum number of contributions to return per page. Range: 1--100. Default: 50.

Request

cURL

bash

curl -X GET "https://api.mesocrats.org/v1/contributions?year=2026&period=Q1&itemized=true&limit=2" \
  -H "Authorization: Bearer mce_live_sk_your_key_here" \
  -H "Content-Type: application/json"

Response

200 OK

JSON

json

{
  "object": "list",
  "data": [
    {
      "id": "don_8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "object": "contribution",
      "donor_id": "dnr_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "contributor_name": "Smith, Jane",
      "contributor_address": "123 Main St",
      "contributor_city": "Richmond",
      "contributor_state": "VA",
      "contributor_zip": "23220",
      "employer": "Acme Corp",
      "occupation": "Software Engineer",
      "date_received": "2026-03-15",
      "amount_cents": 5000,
      "aggregate_ytd_cents": 25000,
      "stripe_charge_id": "ch_3abc123def456",
      "itemized": true,
      "created_at": "2026-03-15T14:30:00Z"
    },
    {
      "id": "don_9e8d7c6b-5a4f-3e2d-1c0b-a9b8c7d6e5f4",
      "object": "contribution",
      "donor_id": "dnr_2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "contributor_name": "Johnson, Robert",
      "contributor_address": "456 Oak Ave",
      "contributor_city": "Glen Allen",
      "contributor_state": "VA",
      "contributor_zip": "23058",
      "employer": "State University",
      "occupation": "Professor",
      "date_received": "2026-02-28",
      "amount_cents": 20000,
      "aggregate_ytd_cents": 35000,
      "stripe_charge_id": "ch_4bcd234efg567",
      "itemized": true,
      "created_at": "2026-02-28T09:15:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_eyJkIjoiMjAyNi0wMi0yOCJ9",
  "total_count": 47
}