Guide

Lookups API

Several fields on the other APIs take an id from one of your account's own lists: the type of a gift, the category of an event, the outcome of a volunteer task. The Lookups API hands you those lists, so you can map a name in your system to the id Argenta expects, once, at startup. It uses the same API keys and the same base URL as the Constituents, Volunteerism, Donations and Events APIs.

Authentication

Use the same key as the other APIs (Subscription Settings -> API Keys, team admins only), sent as a bearer token:

Authorization: Bearer argenta_sk_...

The base URL is https://app.argentasoftware.com/api/v1. These are read endpoints, so a read-only key is enough. Everything returned belongs to your own account.

Endpoints

Method & path	What it does
`GET /lookups`	Every list at once, keyed by list name.
`GET /lookups/{name}`	One list. The name ignores case, hyphens and underscores, so `payment-methods`, `payment_methods` and `PaymentMethods` all work.

The lists

List	Fills
`donationTypes`	`FkDonationType` on a donation.
`donationCategories`	`FkCategory` on a donation.
`paymentMethods`	`FkPaymentMethod` on a donation.
`eventTypes`	`FkEventType` on an event, and `eventTypeId` when searching events.
`eventCategories`	`FkCategory` on an event, and `categoryId` when searching.
`eventSeasons`	`FkSeason` on an event, and `seasonId` when searching.
`eventStatuses`	`FkStatus` on an event, and `statusId` when searching.
`eventTimeZones`	`FkTimeZone` on an event.
`volunteerTaskCategories`	`FkCategory` on a volunteer task.
`volunteerTaskOutcomes`	`FkOutcome` on a volunteer task.
`chapters`, `divisions`, `departments`, `districts`	Read-only. These come back on records you fetch so you can tell where something sits in your organization. They are not writable through the API.

Volunteer task groups are not here: they have their own richer endpoint at GET /volunteer-task-groups. Constituent types and mailing states are not here either, because neither needs a list. A constituent's type is 1 Individual, 2 Household or 3 Organization, and a state is written as a name or a two-letter abbreviation.

Fetch every list

curl "https://app.argentasoftware.com/api/v1/lookups" \
  -H "Authorization: Bearer argenta_sk_..."

{
  "donationTypes": [
    { "id": 1, "name": "*Unknown/Other or N/A", "isNone": true },
    { "id": 4, "name": "Cash", "isNone": false },
    { "id": 7, "name": "In Kind", "isNone": false }
  ],
  "paymentMethods": [ ... ],
  "eventStatuses": [ ... ]
}

Fetch one list

curl "https://app.argentasoftware.com/api/v1/lookups/event-statuses" \
  -H "Authorization: Bearer argenta_sk_..."

{
  "name": "eventStatuses",
  "items": [
    { "id": 1, "name": "New", "isNone": false },
    { "id": 3, "name": "In Planning", "isNone": false },
    { "id": 4, "name": "Registration Open", "isNone": false }
  ]
}

What isNone means. Some lists carry a placeholder row that stands for "not specified", shown in Argenta as *Unknown/Other or N/A. Sending its id is the same as leaving the field out, so treat an isNone row as a blank rather than a real choice. It is flagged instead of hidden because the id it uses is a perfectly ordinary id on other lists: on eventStatuses, for instance, 1 is the real status "New".

Using it

Fetch the lists when your integration starts up and hold them, rather than calling before every write. They change when someone edits them in Argenta, which is rare, and each call is a wide read on our side. Match on name to find the id you want, then send that id.

Every field these lists fill is optional. Leave it out, or send null, and the record is created without it. Send an id that is not on your account's list and the write is rejected with 400 invalid_field naming the field, so a stale cached id fails loudly instead of landing on the wrong record.

Errors

Status	Code	When
401	`unauthorized`	Missing, malformed, revoked, or unknown key.
404	`not_found`	No list by that name. The message lists the valid names.
429	`rate_limited`	Slow down and retry with backoff.

Rate limits
Two limits apply, not one. Per key it is 15 requests a second and 600 a minute. There is also a per-IP limit of 40 a second and 1200 a minute, checked before we even read your key, so several keys calling from the same server share that budget. Either limit returns a 429 with a Retry-After header saying how many seconds to wait. The AI writing assistant is metered on its own separate from these: 10 requests a minute and 100 an hour for each person, and 1,000 an hour across the whole system. It also refuses text longer than 10,000 characters before any limit is counted.

The same shared limit as every other /api/v1 endpoint, counted per key. Caching the lists at startup keeps this endpoint clear of your working budget.