GOTV Intel API

Authentication

Send your key in the Authorization header on every request. Keys look like gtvi_ab12cd34_...; the first part is the key's visible prefix, the rest is secret. Keys carry the directory:read scope.

curl -H "Authorization: Bearer $GOTV_INTEL_KEY" "https://gotv.com/intel/api/v1/races/ia-sen-2"

• Keep keys on your server. Never put one in browser code, a mobile app or a URL.
• A key is shown once, when it is issued. We store only a hash of it.
• We rotate a key on request, and revoke one at once if it is exposed.

Endpoints

Base URL https://gotv.com/intel/api/v1. Every endpoint is GET only and needs a key.

• Every person and seat has an id, our internal identifier. Store it: it never changes, while names and page addresses can.
• Seats also have a code, which the endpoints take: lowercase, state first. ia-cd-2 is a U.S. House seat, ia-sen-2 a U.S. Senate seat (the number is the Senate class), ia-gov a statewide office, ia-sd-21 and ia-hd-58 state legislative seats. Codes come from /races and /search.
• url is the public page for the person or race.

JSON responses are { data, use_restriction, terms }. An example from /races/{key}, with made-up figures:

{
  "data": {
    "id": "IA-SEN",
    "code": "ia-sen-2",
    "url": "https://gotv.com/intel/race/ia-sen-2",
    "office": "Iowa U.S. Senate",
    "level": "us-senate",
    "state": "IA",
    "election": "Nov 3 General",
    "candidates": [
      {
        "id": "p_example",
        "name": "Jane Example",
        "party": "Republican",
        "ballot": "On the 2026 ballot",
        "incumbent": false,
        "officeHeld": "U.S. Representative",
        "heldSeat": "ia-cd-2",
        "fec": {
          "source": "FEC",
          "basis": "cycle_to_date",
          "raised": 1250000,
          "cashOnHand": 480000,
          "through": "2026-09-30",
          "url": "https://www.fec.gov/data/candidate/S6IA00000/"
        },
        "filingUrl": "https://www.fec.gov/data/candidate/S6IA00000/",
        "url": "https://gotv.com/intel/person/jane-example"
      }
    ]
  },
  "use_restriction": "Campaign research only. ...",
  "terms": "https://gotv.com/intel/developers#terms"
}

Errors are { error: { code, message } } with these statuses:

200

The data you asked for.

400

A parameter is missing or not in the expected form.

401

No key, or a key that is not active.

403

The key does not have the directory:read scope.

404

Nothing on file for that state, seat or contest.

429

Over the per-minute limit or the daily cap. Wait the seconds in Retry-After.

503

The API is not available right now. Try again later.

Money

• v1 carries FEC candidate totals only: raised, cash on hand, spent and debts, cycle to date, with the date they run through and a link to the candidate's FEC page. These are federal candidates' public totals, not itemized contributions.
• State campaign finance figures are not in v1.
• In states where figures are withheld, fec is null and moneyNote says so.

Limits

• 60 requests a minute per key, and a daily cap set by your plan, stated when your key is issued. The daily cap resets at midnight UTC.
• Every response has X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Daily-Limit and X-RateLimit-Daily-Remaining. Over a limit the API answers 429 with Retry-After in seconds.
• We log each request's endpoint, status and time against its key. We do not store request bodies.
• A key that pulls whole states in bulk is flagged for review.

MCP server

AI assistants that support the Model Context Protocol can use the same data through a remote MCP server at https://gotv.com/intel/api/mcp (streamable HTTP), with the same key and the same limits. Its tools are read only:

• search_candidates: Search candidates and races
• list_states: List states
• list_races: List a state's 2026 races
• get_race: Get a race
• district_results: District results

Each tool's description carries the use restriction. A client configuration:

{
  "mcpServers": {
    "gotv-intel": {
      "type": "http",
      "url": "https://gotv.com/intel/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

What the API never returns

• Contact details: emails, phone numbers, addresses or staff names.
• Donor or payee names, or itemized contributions or expenditures, from any source.
• Finance figures for states where they are withheld.
• Anything from client accounts: campaign lists, proposals, reports, evidence, credits or billing.
• Voter-level records, photos or biographies.

Coverage varies by state and office: a person, seat or result may not be on file yet.

Terms of use

1. Keys are issued to an organization after account review. Each organization is responsible for every use of its keys and does not share them outside the organization.
2. The API is for campaign research only.
3. Nothing from the API is a consumer report. It may not be used for any purpose under the Fair Credit Reporting Act (FCRA), including deciding eligibility for employment, credit, insurance, housing or licensure. GOTV Intel is not a consumer reporting agency.
4. No resale. You may not sell, sublicense or redistribute the data, in bulk or through another service.
5. The data comes from public records and can lag behind them or contain errors. Confirm anything you rely on against the primary record, which every response links where we have it.
6. Stay within your key's limits, and do not use several keys to get around them.
7. We may suspend or revoke a key that breaks these terms.
8. The site feeds under https://gotv.com/intel/api/ outside /v1 power the website. They are not a supported API, can change at any time and are rate limited.
9. These terms add to the GOTV.com Terms of Service.