# Delivr Documentation

> Documentation for Delivr

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Introduction](https://docs.delivr.ai/docs/delivr-apis.md)
- [Authentication](https://docs.delivr.ai/docs/authentication.md)
- [Quickstart: Enrich Emails with Intent](https://docs.delivr.ai/docs/intent-enrichment.md)
- [Which API Should I Use?](https://docs.delivr.ai/docs/which-api-should-i-use.md)
- [Rate Limits and Metering](https://docs.delivr.ai/docs/rate-limits-and-metering.md)
- [Account Setup](https://docs.delivr.ai/docs/account-setup.md)
- [Person-Level vs Account-Level Intent](https://docs.delivr.ai/docs/person-level-intent.md)
- [How Identity Resolution Works](https://docs.delivr.ai/docs/how-identity-resolution-works.md)
- [Understanding Resolution Rates](https://docs.delivr.ai/docs/understanding-resolution-rates.md)
- [Understanding Segmentation Types](https://docs.delivr.ai/docs/understanding-segmentation-types.md)
- [Pixel and DSP Events API](https://docs.delivr.ai/docs/resolution-as-a-service.md)
- [Pixel and DSP Event Fields](https://docs.delivr.ai/docs/on-domain-event-fields.md)
- [Event Types Reference](https://docs.delivr.ai/docs/event-types.md)
- [Pixel Platform Compatibility](https://docs.delivr.ai/docs/pixel-platform-compatibility.md)
- [SPA Pixel Integration](https://docs.delivr.ai/docs/spa-pixel-integration.md)
- [White Label Pixel Setup](https://docs.delivr.ai/docs/delivr-white-label-pixel-instructions.md)
- [Events API v3](https://docs.delivr.ai/docs/events-api-v3.md)
- [Intent Audiences API](https://docs.delivr.ai/docs/delivr-audience.md)
- [Taxonomy API](https://docs.delivr.ai/docs/delivr-taxonomy-api.md)
- [Field Catalog API](https://docs.delivr.ai/docs/field-catalog-api.md)
- [Intent Audience Fields](https://docs.delivr.ai/docs/intent-audience-fields.md)
- [Building Audience Filters](https://docs.delivr.ai/docs/building-audience-filters.md)
- [Building an Audience Builder UI](https://docs.delivr.ai/docs/building-audience-builder-ui.md)
- [Create an Intent Audience (End-to-End)](https://docs.delivr.ai/docs/recipe-create-intent-audience.md): Browse topics, create audience, poll status, preview, and download
- [Reading Parquet Files](https://docs.delivr.ai/docs/reading-parquet-files.md): Convert audience downloads to CSV or open in Excel
- [Export Events to CSV](https://docs.delivr.ai/docs/recipe-export-events-csv.md): Paginate and export visitor data to CSV with multi-day chunking
- [High-Intent Visitors](https://docs.delivr.ai/docs/recipe-get-high-intent-visitors.md): Export identified visitors who viewed your pricing or product pages in the last 24 hours
- [Export an Audience to S3, Email, or Slack](https://docs.delivr.ai/docs/recipe-export-audience-to-s3.md)
- [Activate an Audience to DelivrDSP](https://docs.delivr.ai/docs/recipe-activate-audience-delivrdsp.md)
- [Write Intent Activity to HubSpot Timelines](https://docs.delivr.ai/docs/recipe-hubspot-intent-activity.md)

## API Reference
- [Query events (web_event)](https://docs.delivr.ai/reference/queryeventswebevent.md): Base event columns only, with no identity resolution. The cheapest tier, and the one to use for volume, scoping and trend work.  Bills the `web_event` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.  Selecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.
- [Query events (resolution_hem)](https://docs.delivr.ai/reference/queryeventsresolutionhem.md): Base columns plus hashed-email identifiers.  Bills the `resolution_hem_only` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.  Selecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.
- [Query events (resolution_hem_pte)](https://docs.delivr.ai/reference/queryeventsresolutionhempte.md): Base columns plus HEM and PTE identifiers, without profile fields.  Bills the `resolution_hem_pte` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.  Selecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.
- [Query events (resolution_full_profile)](https://docs.delivr.ai/reference/queryeventsresolutionfullprofile.md): Every column, including contact, company and demographic fields. The most expensive tier.  Bills the `resolution_full_profile` meter. The route fixes both the price and the field set, so what a call costs is legible before you make it.  Selecting a field above this tier is rejected with a `400` naming the field and the tier that carries it, rather than being silently dropped or silently billed higher. Call this tier's `/schema` route to see exactly which fields it admits: the allowed set is derived from the event schema and the billing catalogue, so a field that becomes billable leaves the cheaper tiers automatically.
- [Get the field schema for one tier](https://docs.delivr.ai/reference/gettiereventschema.md): Fields the named tier can return. Non-billable.
- [Get the full event schema](https://docs.delivr.ai/reference/geteventschema.md): Every field the events API knows about, across all tiers. Non-billable.
- [Resolve identity](https://docs.delivr.ai/reference/lookuphem.md): Resolve a hashed email (HEM) or plain email address to stored identity data. Provide either `hem` or `email` (not both).  **Hash type.** A `hem` is matched by algorithm: SHA-256 (64 hex characters) or MD5 (32 hex characters). The algorithm is inferred from the digest length; pass `hem_type` to set it explicitly (it is then validated against the hem). When `email` is provided instead, it is normalized and hashed for you.  **Filtering and projection.** Optional `filter` and `select` params apply the same grammar as `/api/v3/events/{tier}`, evaluated against the single resolved record:  - `select` projects a subset of fields (comma-separated). Absent fields are omitted. - `filter` (`<field>:<op>:<value>`, `,` = AND, `|` = OR within a group; ops   `eq`, `ne`, `like`, `not_null`) decides whether the record is returned. If the   record does not match, the endpoint responds `404` (no record). Example —   business-email records only:   `filter=current_business_email:ne:""|business_emails:ne:""|is_email_business:eq:"true"`.   Quote literal values (`is_email_business:eq:"true"`).  **Billing.** Metered on egress as `contact_record` (the same meter as a contact query or audience download, not the events `resolution_*` tiers): a `200` that returns a record bills one contact record; a `404` (not found or filtered out) bills nothing. `select` projects fields but does not change the meter.
- [Batch contact enrichment](https://docs.delivr.ai/reference/querycontacts.md): Resolve a batch of email addresses to enriched contact records — the same identity data as `GET /api/v1/lookup`, but up to 1000 emails per call. Each email is normalized and SHA-256 hashed before lookup.  **Filtering and billing.** Provide an optional `filter` (same grammar as the lookup endpoint) to receive only records that match; non-matching records are dropped from the response and are not billed. Billing is on egress as `contact_record` — only records that carry a business email are billed, so a filtered-out or non-resolving email costs nothing. To receive and be billed for only records with a current business email, set `filter` to `current_business_email:ne:""`.  **Pagination.** `page_size` (default 100, max 1000) bounds the page; a non-empty `cursor` in the response means more records remain — pass it back to fetch the next page.
- [Resolution statistics](https://docs.delivr.ai/reference/getresolutionstatistics.md): Return aggregate resolution-rate statistics for your organization, rolled up across all of its pixels over the recent reporting window.  The headline number depends on which unit you look at. The **event rate** counts pixel fires; the **visitor (cookie) rate** counts unique people and is the honest per-visitor number, always lower because resolved visitors generate many events while every bot or Safari hit mints a throwaway cookie. The **addressable** rate is measured against US traffic only, excluding bots and cookieless requests, and is the one to benchmark against.  Non-US traffic sits outside that benchmark but is mostly still eligible for resolution. A visitor on a non-US IP can and does resolve, usually at a lower rate, whenever their identity is already known to the graph. Use the `ip_country` field on the events endpoints to scope results by visitor country.  The exception is the EEA, the UK and Switzerland. Visitors on an IP in those 32 countries are never resolved, because their law requires opt-in consent for the profile data we would attach. Their events are still collected and returned; only the identity is withheld. See "Where we do not resolve visitors" in the event field catalog for the country list.  The `funnel` partitions **all** events into priority-ordered, mutually exclusive buckets, so the buckets sum to `total_events`. Priority, not resolution alone, decides the bucket: Safari events that did resolve are counted under `resolved`, not `safari`, and `international` holds every non-US event, resolved or not, because `resolved` counts only addressable (US) resolutions. `first_touch` splits the rate by first-time vs returning visitors (the most actionable view: returning visitors resolve far higher because identity binds a cookie to a person over repeat visits).  Sections that need counters your data predates are omitted rather than reported as zero.  By default the response aggregates every pixel in your organization over the last seven completed days. The optional parameters below narrow it, always within your own organization.
- [List categories](https://docs.delivr.ai/reference/listcategories.md): Returns the top-level intent taxonomy categories.
- [Count categories](https://docs.delivr.ai/reference/countcategories.md): Returns the number of categories matching the supplied filters.
- [Get category](https://docs.delivr.ai/reference/getcategory.md): Returns a single taxonomy category by id.
- [List subcategories](https://docs.delivr.ai/reference/listsubcategories.md): Returns intent taxonomy subcategories, optionally filtered by parent category.
- [Count subcategories](https://docs.delivr.ai/reference/countsubcategories.md): Returns the number of subcategories matching the supplied filters.
- [Get subcategory](https://docs.delivr.ai/reference/getsubcategory.md): Returns a single taxonomy subcategory by id.
- [List topics](https://docs.delivr.ai/reference/listtopics.md): Returns intent taxonomy topics, the granular buying-intent signals that audiences target.
- [Count topics](https://docs.delivr.ai/reference/counttopics.md): Returns the number of topics matching the supplied filters.
- [Get topic](https://docs.delivr.ai/reference/gettopic.md): Returns a single taxonomy topic by id.
- [Create topic request](https://docs.delivr.ai/reference/createtopicrequest.md): Submits a request to add a new intent topic to the taxonomy.
- [List topic requests](https://docs.delivr.ai/reference/listtopicrequests.md): Returns the intent topic requests submitted by your organization and their status.
- [Get topic request](https://docs.delivr.ai/reference/gettopicrequest.md): Returns a single topic request by id.
- [Resubmit topic request](https://docs.delivr.ai/reference/updatetopicrequest.md): Allows partners to submit changes and move a topic request back to waiting_for_approval.
- [List fields](https://docs.delivr.ai/reference/listfields.md): Retrieve all fields, optionally filtered by schema type, category, or status. Pass `include_options=true` to receive picklist values for select and multiselect fields (adds ~1.5 MB to the response due to fields like `job_title_normalized` with 16,000+ values).
- [List categories](https://docs.delivr.ai/reference/listfieldcategories.md): Returns distinct category names for active fields.
- [Get field by key](https://docs.delivr.ai/reference/getfieldbykey.md): Retrieve a single field by its `field_key`. Options are always included in the response.
- [List audiences](https://docs.delivr.ai/reference/listaudiences.md): List audiences with optional filtering by type, project, organization, segmentation type, status, or name search.
- [Create audience](https://docs.delivr.ai/reference/createaudience.md): Create a new audience with the specified type and parameters.  **Type-specific requirements:** - `intents`: Requires `filter` with topic-based intent criteria. - `contact`: Requires `filter` with contact-database criteria. `elixir` is the former name for this type and is still accepted on create; audiences created before the rename may still report `elixir` until they are migrated. - `list`: Requires `source_list_id` and `source_list_mode`, and still requires `filter` like every other type. Send an empty object (`"filter": {}`) -- a list audience's population comes from the uploaded list, so there is nothing to filter on, but omitting the field is rejected with `{"field": "Filter", "constraint": "required"}`. Setting `source_list_id` is what makes the server treat the audience as type `list`. **Availability:** rolling out. You can create a `list` audience today, but build output is not yet available for this type.
- [Get audience](https://docs.delivr.ai/reference/getaudience.md): Retrieve audience metadata, storage path, and size.
- [Update audience](https://docs.delivr.ai/reference/updateaudience.md): Update audience name, description, filter, output path, or select clause.
- [Delete audience](https://docs.delivr.ai/reference/deleteaudience.md): Delete an audience by ID.
- [Clone audience](https://docs.delivr.ai/reference/cloneaudience.md): Create a copy of an existing audience with a new name. The clone inherits the original's type, filter, segmentation type, and project/organization.
- [Download audience files](https://docs.delivr.ai/reference/downloadaudience.md): Return presigned S3 links for the audience's output files. If the files are not yet ready, the response indicates the current status and an unload is triggered automatically. Keep polling until `status` is `ready` or `failed`; large builds can take longer than a fixed client timeout. Preparation continues on the server if a client stops polling.
- [Refresh audience](https://docs.delivr.ai/reference/refreshaudience.md): Reset the audience to the `Pending` state so the renewal worker re-runs its unload. Use this to manually trigger a fresh build when you don't want to wait for the next scheduled `renew_time` tick, or to recover an audience that hit a transient `Failed` state.  Refresh does not re-validate or re-compile the filter, so it succeeds even when the upstream schema service is unavailable. It also does not change the filter, name, description, or any other configuration. The response is the audience as-of the reset, with `status = Pending` and `task_id` cleared.  Returns `409 Conflict` when the audience is already mid-unload (`Syncing`), or when it is paused for any reason other than `idle`. An idle pause is lifted automatically and refreshes normally; every other pause, including a `manual` one, must be resumed first, because the renewal worker skips paused rows and the queued rebuild would never be claimed. That response adds `pause_reason` naming which case it was.
- [Pause audience](https://docs.delivr.ai/reference/pauseaudience.md): Pause an audience so it stops auto-renewing on its scheduled `renew_time`. The current schedule is stashed in `previous_renew_time` and restored on resume; `paused_at` is stamped and `pause_reason` is set to `manual`.  Pausing does not cancel an in-flight unload, clear results, or change the filter. A paused audience can still be downloaded. It cannot be refreshed until it is resumed: the renewal worker skips paused rows, so a queued rebuild would never be claimed, and `refresh` returns `409` with `pause_reason` rather than accepting work that cannot run.  Returns `409 Conflict` when the audience is already paused.
- [Resume audience](https://docs.delivr.ai/reference/resumeaudience.md): Clear the pause markers and restore the renewal schedule that was stashed in `previous_renew_time` when the audience was paused.  Refuses with `409 Conflict` when the audience is paused for a reason other than `manual`: - `pause_reason = "org_inactive"`: the parent organization must   be reactivated before any of its audiences can be resumed.   Response body includes `"code": "org_inactive"`. - `pause_reason = "project_inactive"`: the parent project must   be reactivated first. Response body includes   `"code": "project_inactive"`.  Returns `409 Conflict` with no `code` field when the audience is not paused at all.
- [Get audience sample](https://docs.delivr.ai/reference/getaudiencesample.md): Retrieve a small preview of an audience so you can validate it before exporting. This is a capped, redacted teaser, not a data feed: it returns up to 25 rows carrying firmographics, role, intent, first name, and the HEM match key, plus `has_*` flags indicating which contact fields exist. Raw contact data (emails, phones, LinkedIn, personal address, full name) is NOT returned here; download/unload the audience to get (and be billed for) the full contact records. `total_count` reports the audience's true size regardless of the sample size.
- [Get audience task status](https://docs.delivr.ai/reference/getaudiencestatus.md): Check whether an audience's parquet files are ready in S3.
- [Trigger audience unload](https://docs.delivr.ai/reference/triggeraudienceunload.md): Trigger an actual unload for an audience, writing its results to S3. The audience must be in a completed state. Once triggered, use the status endpoint to poll for completion.
- [Check intent data availability](https://docs.delivr.ai/reference/getaudienceavailability.md): Returns which dates have ready intent data, sourced from an in-memory calendar that polls Synapse every minute. Zero database calls at request time. Use this to determine whether fresh data is available before triggering audience creation or export.  Does not trigger billing. Utility endpoint, basic JWT auth only.
- [Estimate audience size](https://docs.delivr.ai/reference/estimateaudiencesize.md): Estimate the distinct reach of a filter **without creating an audience**. Sizes the filter tree against the precomputed intent index and returns distinct person / email / mobile counts, so a builder can show a live reach estimate as the filter changes.  The estimate is **distinct reach only** and never includes a billable record count: the row-per-email fan-out that billing is based on only exists after a build. Treat the returned counts as approximate reach; the exact billed record count is known only after the audience is created.  Not every filter can be sized from the index. When `supported` is `false`, the index cannot stand behind a count (for example a filter shape it does not cover, or an intent window not yet fully indexed); fall back to creating the audience to get an exact size. A `200` is returned for any well-formed request, even when `supported` is `false`; only a malformed body returns `400`.  "Field is present" rules (`is not null`, `is not blank`) and their negations (`is null`, `is blank`) are sized **exactly**, against a precomputed field-present index, so adding one narrows the estimate as you would expect. A field the index cannot yet answer this way makes the filter fall back to the scan (`supported: false`) rather than being sized without it, so a returned count is never a silent over-estimate.  `dropped_predicates` is the disclosure channel for any rule the estimate sizes *without* (an upper bound on reach): when present it lists those rules while `supported` stays `true`, so check it before presenting a count as exact. It is absent when the whole filter was applied, which is now the usual case. This endpoint is a reach estimate, not a filter validator: create the audience to confirm a filter behaves as intended.  Project-scoped: name the project with the `X-Project-Id` header or a `?project_id=` query parameter, as with the other audience endpoints.
- [Batch audience usage rollup](https://docs.delivr.ai/reference/getaudiencelinkageusage.md): Returns export and campaign usage for a batch of audiences, so a list view can show which ones are in use without a request per row.  Every requested id comes back, in the order requested. An audience with no live export is returned with zero counts and `in_use` false, which also covers ids that no longer exist, so a missing entry never means "not found".  The project is taken from the authenticated context rather than a parameter, so usage is only ever reported within the caller's own project.
- [Get audience schema](https://docs.delivr.ai/reference/getaudienceschema.md): Returns the contact data schema describing available fields for audience building and filtering.
- [Look up intent for one identifier](https://docs.delivr.ai/reference/intentlookup.md): Resolve a single person to their intent topics, by `email` or by `linkedin_url`. The per-row call for scoring contacts you already have. A LinkedIn URL identifies a person rather than one address, so it resolves across every address we hold for them and can match where a single email would not. An unmatched or malformed identifier returns `matched: false` with an empty `topics` array, never an error.
- [Look up intent for many identifiers](https://docs.delivr.ai/reference/intentbatch.md): Resolve up to 10,000 identifiers in one call, each an `email` or a `linkedin_url`, mixed freely. Results are returned in input order, one per item; each echoes the supplied `id`. Page through this limit for larger audiences.
- [Look up intent for one company](https://docs.delivr.ai/reference/intentcompany.md): Resolve a single company to its intent topics, by `domain` or by `linkedin_company_url`, aggregated across the people at that company. Each topic carries a `people_count`. An unmatched or malformed identifier returns `matched: false` with an empty `topics` array, never an error.
- [Look up intent for many companies](https://docs.delivr.ai/reference/intentcompanybatch.md): Resolve up to 10,000 companies in one call, each a `domain` or a `linkedin_company_url`, mixed freely. Results are returned in input order, one per item; each echoes the supplied `id`. Page through this limit for larger lists.
- [List companies showing intent on a topic](https://docs.delivr.ai/reference/intentcompaniesbytopic.md): The inverse direction (TAM / account discovery): given a `topic_id`, return the companies whose people show intent on it, ordered by how many people (`people_count`), strongest first. Results are paginated - pass the returned `next_cursor` back to get the next page; an empty `next_cursor` means the last page. `count` (the topic's total company count) is returned only on the first page.
- [List people showing intent on a topic](https://docs.delivr.ai/reference/intentpeoplebytopic.md): The person-grain TAM direction: given a `topic_id`, return the people (as HEMs) who show intent on it, ordered by `perc_score`, strongest first, with cursor pagination. Each HEM is a deterministic match key (sha256 of a normalized email) you can intersect against your own contacts; raw emails are never returned. `count` (the topic's total people) is returned only on the first page.
- [Companies showing intent across multiple topics](https://docs.delivr.ai/reference/intentcompaniesbytopicmulti.md): Multi-topic account discovery: given up to 25 `topic_ids` in one call, return the companies showing intent across them. The fan-out runs in parallel server-side, so a 25-topic request is about as fast as a single topic.  `group_by` selects the response shape:   - `entity` (default): one row per company, annotated with which of the     requested topics it shows intent on (`topics`), how many it matched     (`topic_count`), and aggregate signals. Set `min_topics` to require a     company match at least N of the topics (N = number of topics =     intersection; default 1 = union). This view is cursor-paginated.   - `topic`: the raw per-topic ranked lists (the same fan-out, not     merged), one bucket per requested topic.  `min_score` and `min_people_count` filter each topic's results. `per_topic_limit` (default 1000, max 5000) caps how deep each topic is scanned. `min_topics`, `page_size`, and `cursor` apply only to `group_by=entity`.
- [People showing intent across multiple topics](https://docs.delivr.ai/reference/intentpeoplebytopicmulti.md): Multi-topic person-grain discovery: given up to 25 `topic_ids` in one call, return the people (as HEMs) showing intent across them. The fan-out runs in parallel server-side, so a 25-topic request is about as fast as a single topic. Each HEM is a deterministic match key (sha256 of a normalized email); raw emails are never returned.  `group_by` selects the response shape:   - `entity` (default): one row per person, annotated with which of the     requested topics they show intent on (`topics`) and how many they     matched (`topic_count`). Set `min_topics` to require a match across at     least N of the topics (default 1 = union). This view is     cursor-paginated.   - `topic`: the raw per-topic ranked lists, one bucket per requested     topic.  `min_score` and `min_perc_score` filter each topic's results. `per_topic_limit` (default 1000, max 5000) caps how deep each topic is scanned. `min_topics`, `page_size`, and `cursor` apply only to `group_by=entity`.
- [Preview people showing intent on a topic (free sample)](https://docs.delivr.ai/reference/intentpeoplebytopicpreview.md): Free, capped preview of the person-grain topic direction: given a `topic_id`, return a small sample (up to 25) of the top people (as HEMs), ranked by `perc_score`, plus the topic's total `count`. Use it to show a teaser while configuring a source, then call the paid `/api/v1/intent/people` to pull and pay for the full list.  Nothing is billed. Distinct from `dry_run` (which returns a cost count and no records): this returns actual sample records. It does not paginate (no `cursor`, no `next_cursor`) and never returns `seen_email`; you always get the strongest-intent top of the list. `count` is the topic's full people total, so the sample is only a window onto it.
- [Preview companies showing intent on a topic (free sample)](https://docs.delivr.ai/reference/intentcompaniesbytopicpreview.md): Free, capped preview of the account-discovery direction: given a `topic_id`, return a small sample (up to 25) of the top companies, ranked by `people_count`, plus the topic's total `count`. Use it to show a teaser while configuring a source, then call the paid `/api/v1/intent/companies` to pull and pay for the full list.  Nothing is billed. Distinct from `dry_run` (which returns a cost count and no records): this returns actual sample records. It does not paginate (no `cursor`, no `next_cursor`); you always get the strongest-intent top of the list. `count` is the topic's full company total, so the sample is only a window onto it.
- [Preview people showing intent across multiple topics (free sample)](https://docs.delivr.ai/reference/intentpeoplebytopicmultipreview.md): Free, capped multi-topic preview of the person-grain direction: given up to 25 `topic_ids`, return a small sample (up to 25) of the top people (as HEMs), merged one row per person and annotated with which of the requested topics they matched, plus the total `count` of matching people. The merged (group_by=entity) shape is forced. Use it to show a teaser while configuring a source, then call the paid `/api/v1/intent/people/multi` to pull and pay for the full list.  Nothing is billed. It does not paginate (no `cursor`, no `next_cursor`) and never returns raw email; you always get the strongest-intent top of the merged list. Only floor filters are accepted; group_by, per_topic_limit, page_size, cursor, and resolve are not part of this request.
- [Preview companies showing intent across multiple topics (free sample)](https://docs.delivr.ai/reference/intentcompaniesbytopicmultipreview.md): Free, capped multi-topic preview of the account-discovery direction: given up to 25 `topic_ids`, return a small sample (up to 25) of the top companies, merged one row per company and annotated with which of the requested topics they matched, plus the total `count` of matching companies. The merged (group_by=entity) shape is forced. Use it to show a teaser while configuring a source, then call the paid `/api/v1/intent/companies/multi` to pull and pay for the full list.  Nothing is billed. It does not paginate (no `cursor`, no `next_cursor`); you always get the strongest-intent top of the merged list. Only floor filters are accepted; group_by, per_topic_limit, page_size, and cursor are not part of this request.
- [Create list](https://docs.delivr.ai/reference/createlist.md): Create a new list with the specified type and source.
- [List lists](https://docs.delivr.ai/reference/listlists.md): Retrieve lists with optional filtering. At least one of `organization_id`, `project_id`, or `integration_id` is required.
- [Get list](https://docs.delivr.ai/reference/getlist.md): Retrieve a single list by ID.
- [Update list](https://docs.delivr.ai/reference/updatelist.md): Update a list. Supports partial updates -- only provided fields are changed.
- [Delete list](https://docs.delivr.ai/reference/deletelist.md): Delete a list and all its values.
- [Bulk delete lists](https://docs.delivr.ai/reference/bulkdeletelists.md): Delete multiple lists in a single request (max 1000).
- [Bulk add values](https://docs.delivr.ai/reference/bulkaddlistvalues.md): Add values to a list in bulk. Maximum 100,000 values per request. Duplicate values are skipped.
- [Get presigned upload URL](https://docs.delivr.ai/reference/presignlistimport.md): Request a presigned URL for uploading a file directly to S3. After uploading, call `POST /api/v1/lists/{id}/imports` to trigger the import.
- [Trigger import](https://docs.delivr.ai/reference/triggerlistimport.md): Trigger an import after uploading a file to S3 via the presigned URL. Returns a job ID that can be polled for status.
- [Poll import status](https://docs.delivr.ai/reference/getlistimportstatus.md): Poll the status of an import job.
- [List campaigns](https://docs.delivr.ai/reference/listcampaigns.md): Retrieve campaigns. At least one of `organization_id`, `project_id`, or `integration_id` is required. The response shape depends on whether pagination is requested:  - With `limit` or `offset`: returns `{ data, total_count }`. - Without: returns a plain JSON array.  Six parameters are answered only under `project_id`: `limit`, `offset`, `sort_by`, `sort_order`, `query` and `status`. Naming any of them alongside `organization_id` or `integration_id` is refused with 400 rather than ignored, because the queries behind those two scopes read none of them: accepting one and dropping it would answer a narrower question with a wider set of rows and nothing saying so.  The `source` and `active` filters are the other way round and apply under `organization_id`.
- [Project performance summary](https://docs.delivr.ai/reference/getprojectperformancesummary.md): Aggregate performance for all campaigns in a project, with a per-campaign breakdown and a daily trend. Pagination applies only to the per-campaign breakdown; totals and the daily trend are always returned in full.
- [Project budget summary](https://docs.delivr.ai/reference/getprojectbudgetsummary.md): Per-campaign budget utilization across a project.
- [Get campaign](https://docs.delivr.ai/reference/getcampaign.md): Returns a single campaign by id.
- [Get campaign performance](https://docs.delivr.ai/reference/getcampaignperformance.md): Performance summary plus daily breakdown for a single campaign. Daily rows can be paginated; the summary is always returned in full and is unaffected by pagination.  Default date range is the last 30 days.
- [Get campaign budget status](https://docs.delivr.ai/reference/getcampaignbudgetstatus.md): Returns the current budget and spend status for a campaign.
- [Get campaign match rates](https://docs.delivr.ai/reference/getcampaignmatchrates.md): Audience match data across all lists attached to the campaign, plus impression/click reach against matched contacts.
- [List attached lists](https://docs.delivr.ai/reference/listcampaignlists.md): Returns the lists attached to a campaign.
- [Validate the API key and return its scope](https://docs.delivr.ai/reference/whoami.md): Returns the organization the API key belongs to and the projects under it. A successful `200` confirms the key is valid; the payload also lets a caller discover the scope ids the key can use on other endpoints. No request parameters are needed; scope comes from the key.
- [Get your organization](https://docs.delivr.ai/reference/getorganization.md): Returns the organization that owns the API key. No parameters are needed; the organization is resolved from the key.
- [Update your organization](https://docs.delivr.ai/reference/updateorganization.md): Updates the organization that owns the API key. Only the fields present in the request are changed; omitted fields are left untouched. Any `organization_id` in the body must match the key's organization; a key can only ever update its own organization.
- [Delete your organization](https://docs.delivr.ai/reference/deleteorganization.md): Soft-deletes the organization that owns the API key. A body `organization_id`, if present, must match the key's organization; a key can only ever delete its own organization. Send an empty object `{}` when you have no body fields. This is destructive.
- [Get billing usage summary](https://docs.delivr.ai/reference/getbillingusage.md): Returns your organization's billable usage for a date window: the period total, a per-project breakdown, a per-source breakdown, and a daily trend. The organization is resolved from the API key; no scope parameters are needed.  With no dates, the window defaults to the current calendar month. Dates are day-grained; `end_date` is inclusive. This endpoint is read-only and never metered.
- [Get billing usage by meter](https://docs.delivr.ai/reference/getbillingusagebymeter.md): Returns your organization's billable usage rolled up by meter (the billable SKU: `resolution_full_profile`, `contact_record`, `resolution_hem_pte`, `resolution_hem_only`, `intent_signal_scored`, `web_event`), one entry per meter per month, joined to your active contract's rate card so each line carries the unit rate and the billable amount.  The rollup is month-grained: a provided `start_date` snaps to the first of its month, and a provided `end_date` extends to cover that month. With no dates, the window is the current month. Read-only, never metered.
- [Get daily billing usage by meter](https://docs.delivr.ai/reference/getbillingusagedailybymeter.md): Returns your organization's billable usage as one entry per (day, meter) cell — the data behind the usage trend chart in the dashboard. Days with no usage for a meter are omitted; treat missing cells as zero.  Window semantics match the by-meter rollup: month-grained snapping, defaulting to the current month. Read-only, never metered.
- [Create application](https://docs.delivr.ai/reference/createapp.md): Create a new application. Only requires JWT, no client credentials needed. After creation, use /public/core/api/app/retrieve to obtain your client_id and client_secret.
- [Retrieve application details](https://docs.delivr.ai/reference/getapp.md): Retrieve detailed information about a specific app including client credentials (client_id and client_secret). Only requires JWT, no client credentials needed.
- [List applications](https://docs.delivr.ai/reference/listapps.md): Get a full list of apps associated with the authenticated user.
- [Update application](https://docs.delivr.ai/reference/updateapp.md): Update information about a specific app, such as its name.
- [Delete application](https://docs.delivr.ai/reference/deleteapp.md): Delete a specific app. This will invalidate the associated client credentials.
- [List organizations and projects for the authenticated user](https://docs.delivr.ai/reference/getuseroverview.md): Get the authenticated user's full hierarchy of organizations and projects. Useful for building navigation and obtaining scope IDs.
- [Retrieve organization](https://docs.delivr.ai/reference/getorganizationbyid.md): Retrieve detailed information about a specific organization including address and billing details.
- [Update organization](https://docs.delivr.ai/reference/partnerupdateorganization.md): Update organization information. The request body must wrap fields inside an "organization" object.
- [List organization users](https://docs.delivr.ai/reference/listorganizationusers.md): Retrieve a list of users within the specified organization. Scoped to the key's organization.
- [Create organization user](https://docs.delivr.ai/reference/createorganizationuser.md): Create a new user and add them to the specified organization. Scoped to the key's organization.
- [Retrieve organization user](https://docs.delivr.ai/reference/getorganizationuser.md): Retrieve detailed information about a specific organization user. Scoped to the key's organization.
- [Update organization user](https://docs.delivr.ai/reference/updateorganizationuser.md): Update a specific organization user's information. Scoped to the key's organization.
- [Deactivate organization user](https://docs.delivr.ai/reference/deleteorganizationuser.md): Deactivate a specific organization user. Scoped to the key's organization.
- [List projects](https://docs.delivr.ai/reference/listprojects.md): Get a list of projects within the specified organization. Scoped to the key's organization.
- [Create project](https://docs.delivr.ai/reference/createproject.md): Create a new project within the specified organization. The request body must wrap fields inside a "project" object. Scoped to the key's organization.
- [Retrieve project](https://docs.delivr.ai/reference/getproject.md): Retrieve detailed project information including address, timezone, and onboarding status. Scoped to the key's organization.
- [Update project](https://docs.delivr.ai/reference/updateproject.md): Update project information such as name, address, timezone, and onboarding status.
- [Deactivate project](https://docs.delivr.ai/reference/deleteproject.md): Deactivate a project. Scoped to the key's organization.
- [List project users](https://docs.delivr.ai/reference/listprojectusers.md): Retrieve a list of users within the specified project. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Create project user](https://docs.delivr.ai/reference/createprojectuser.md): Create a new user and add them to the specified project. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Retrieve project user](https://docs.delivr.ai/reference/getprojectuser.md): Retrieve detailed information about a specific project user. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Update project user](https://docs.delivr.ai/reference/updateprojectuser.md): Update a specific project user's information. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Deactivate project user](https://docs.delivr.ai/reference/deleteprojectuser.md): Deactivate a specific project user. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Create pixel](https://docs.delivr.ai/reference/createpixel.md): Create a new tracking pixel. Simple mode: pass only a title (defaults applied). Detailed mode: include params and custom_fields for full control. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [List pixels](https://docs.delivr.ai/reference/listpixels.md): Retrieve all tracking pixels for the specified project. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Retrieve pixel](https://docs.delivr.ai/reference/getpixel.md): Retrieve detailed information about a specific pixel including params, custom fields, and installation URL. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Update pixel](https://docs.delivr.ai/reference/updatepixel.md): Update the specified pixel's title, status, params, or custom fields. Set `status` to `active` or `inactive` to activate or deactivate the pixel. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Delete pixel](https://docs.delivr.ai/reference/deletepixel.md): Delete the specified pixel permanently. Name the target project in the request (a `project_id` field for writes, or a `?project_id=` query parameter for reads).
- [Verify pixel installation](https://docs.delivr.ai/reference/verifypixel.md): Verify that a pixel is installed. Fetches the page named by the required `?url=` parameter server-side and confirms the install script is present in its HTML, which verifies a fresh install before any visitor traffic exists, and counts the pixel's events over the last 24 hours; events are queryable within seconds of a page view. Either signal verifies. Tag-manager installs (for example Google Tag Manager) inject the script at runtime and are not detectable by the page scan; a page that cannot be fetched reports `fetch_failed`, which means "could not check", not "not installed". Name the target project with the `?project_id=` query parameter.
- [List integrations](https://docs.delivr.ai/reference/listintegrations.md): Returns the integrations under a project or organization. Supply `project_id` (preferred) or `organization_id`. Credentials are never included; `has_credentials` reports whether they are set.
- [Create an integration](https://docs.delivr.ai/reference/createintegration.md): Creates an S3 or DelivrDSP integration in the given project. The organization is taken from the API key; pass the project as the `project_id` query parameter. Secret fields (`access_key_id`, `secret_access_key`, `username`, `password`) are encrypted at rest and never returned.
- [Get an integration](https://docs.delivr.ai/reference/getintegration.md): Returns a single integration owned by the API key's organization.
- [Update an integration](https://docs.delivr.ai/reference/updateintegration.md): Updates an integration. Only the fields present in the request are changed; omitted fields are left untouched. Send `credentials` to rotate the integration's secrets (the shape matches the secret fields from create). The integration `type` is immutable.
- [Delete an integration](https://docs.delivr.ai/reference/deleteintegration.md): Permanently deletes an integration owned by the API key's organization.
- [Get CRM field mappings](https://docs.delivr.ai/reference/getintegrationcrmconfig.md): Returns the CRM field mappings, object settings, and task mapping for a Salesforce or HubSpot integration, in the clean public shape.
- [Set CRM field mappings](https://docs.delivr.ai/reference/updateintegrationcrmconfig.md): Sets the field mappings, object settings, and task mapping for a Salesforce or HubSpot integration. `field_mappings`, `object_settings`, and `task_mapping` are replaced wholesale (a key you omit is cleared); the CRM-derived field cache the platform maintains is preserved.
- [Create an export](https://docs.delivr.ai/reference/createexport.md): Creates an export and its destination atomically. The organization is taken from the API key; the `project_id` in the body must belong to it, as must the destination's `integration_id`. The export name must be unique within the project. For a `weekly` schedule, `run_day_of_week` is required.
- [List exports](https://docs.delivr.ai/reference/listexports.md): Returns the exports in a project under the API key's organization.
- [Get an export](https://docs.delivr.ai/reference/getexport.md): Returns an export and its delivery destination(s).
- [Update an export](https://docs.delivr.ai/reference/updateexport.md): Updates an export. Omitted fields are unchanged. Supply `destination` to re-point or reconfigure delivery: it is re-translated and the export's destination is updated together with the export, in one transaction. Changing `query` or `record_limit` requires `destination` too, so the export query and its destination stay in sync. The export must have exactly one destination, and its type cannot change in place (delete and recreate to switch type).
- [Delete an export](https://docs.delivr.ai/reference/deleteexport.md): Deletes an export and its destination(s).
- [Get pixel JavaScript](https://docs.delivr.ai/reference/getpixelscript.md): Retrieves the tracking pixel JavaScript for your website. The server responds with a 302 redirect to the CDN-hosted script. Include this on every page you want to track.
- [Send pixel event (POST)](https://docs.delivr.ai/reference/sendevent.md): Ingests a pixel event via POST and pushes it to the internal processing pipeline. Returns redirect URLs for cookie sync and a cookie identifier.
- [Send pixel event (GET)](https://docs.delivr.ai/reference/sendeventget.md): GET-based equivalent of the send-event endpoint. Query parameters mirror the JSON payload. Useful for environments where POST requests are restricted (e.g., image tags, redirects).
- [Cookie sync](https://docs.delivr.ai/reference/cookiesync.md): Synchronizes Delivr identifiers with upstream partners and optionally redirects to a supplied URL. Typically called via an image tag or redirect chain in the browser. Returns a 1x1 transparent GIF.

## Changelog
- [API Updates - May 2026](https://docs.delivr.ai/changelog/api-updates-may-2026.md)
- [API Updates - April 2026](https://docs.delivr.ai/changelog/api-updates-april-2026.md)
- [API Updates - March 2026](https://docs.delivr.ai/changelog/api-updates-march-2026.md)
- [API Updates - February 2026](https://docs.delivr.ai/changelog/api-updates-february-2026.md)
- [API Updates - January 2026](https://docs.delivr.ai/changelog/api-updates-january-2026.md)