# Choose your API Decide exactly which Instasent API fits the job in front of you: Product, Ingest, Transactional or Legacy. Quick answers by use case, trade-offs, and a clear decision path for the cases where more than one would work. Instasent exposes four public APIs. Picking the right one on day one saves rework, because tokens, data shapes and scopes don't transfer between them. This page is the decision page: scan the quick table, walk the decision flow, and you should come out knowing exactly which API to point your code at. If the word "API" isn't right for your case (marketing sends, audience exploration from the UI), the answer is probably **the dashboard**, not an API. Come back here when you have code to write. ## Quick answer by use case > **Tip**: Find your row. If two rows look applicable, read the decision flow below — one of them will be right and the other will have a footgun. | I want to… | Use | Why | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Send an OTP, password reset, 2FA code | [Transactional API](/transactional-api/overview) | Raw throughput, no contact setup needed, lowest latency. | | Send a receipt, shipping notification or any plain transactional SMS to an anonymous phone | [Transactional API](/transactional-api/overview) | Same reasoning — no customer profile involved. | | Send an **API-driven campaign** or any high-volume batch from a recipient list you already own | [Transactional API — `POST /sms/bulk`](/transactional-api/http/quickstart#sending-many-messages-at-once-smsbulk) | Many customers, including marketing agencies, run campaigns straight on top of Transactional. Reach for Product API only if you want Instasent to own the audience. | | Send SMS at carrier-level volume with persistent sessions | [Transactional API — SMPP](/transactional-api/smpp/integration) | SMPP is the only protocol built for high-throughput bind-and-send. | | Send a **tracked** SMS to a specific customer (history, attribution, automations) | [Product API — direct messaging](/product-api/guide) | The message is recorded against the audience contact and feeds campaigns/analytics. | | List campaigns, automations and their status | [Product API](/product-api/guide) | Campaigns and automations are first-class Product API resources. | | Pull the messages a campaign or automation has already sent (with stats) | [Product API](/product-api/guide) | Dedicated endpoints list SMS by campaign, campaign option, automation and automation message. | | Read direct-SMS history for a customer or across a project | [Product API](/product-api/guide) | Direct messages live on the audience timeline and on project-wide listings. | | See which SMS senders are registered on a project | [Product API](/product-api/guide) | `List SMS senders` exposes the senders configured in project settings. | | Import contacts and events from your CRM or e-commerce platform | [Ingest API](/ingest-api/guide) | Datasource-scoped, write-only token; the right blast radius for a sync worker. | | Search the unified audience or pull a contact by phone / email / user id | [Product API](/product-api/guide) | Audience is a Product-API concept. | | Read a contact's event timeline | [Product API](/product-api/guide) | Same reason — events are a project-level concept. | | Analyse audience events attributed to a campaign | [Product API](/product-api/guide) | `Scroll audience events by campaign attribution` is the analytics surface. | | Run an HLR / number lookup | [Transactional API](/transactional-api/overview) | `POST /lookup` lives on Transactional (and on Legacy for existing integrations). | | Read balance or price profiles from an SMS integration | [Transactional API](/transactional-api/overview) | `/organization/account` and `/…/price-profile/me/countries` are on Transactional. | | Maintain an integration that already calls `/sms`, `/sms/bulk`, `/lookup` on the Legacy base URL | [Legacy API](/legacy-api/overview) | It keeps working; do not rewrite for the sake of rewriting. | | Build a **new** SMS integration of any kind | [Transactional API](/transactional-api/overview) | Transactional is the evolution of Legacy — same endpoints plus DLR webhooks, SMPP and per-project tokens. There is no SMS feature that is Legacy-only. | ## Decision flow If you are still unsure after the table, walk through these questions in order. The first "yes" picks the API. #### 1. Are you maintaining an existing Legacy integration? If your code already calls `/sms`, `/sms/bulk`, `/lookup` or `/organization/account` against the Legacy base URL, stay on [Legacy](/legacy-api/overview). It is supported and deliverability is identical. Migrate to [Transactional](/transactional-api/overview) when you want DLR webhooks, SMPP or per-project tokens, or when the integration is due for a larger refactor. There is no SMS endpoint that only exists on Legacy — every path is mirrored on Transactional. #### 2. Do you need an SMS pipe without the audience layer (single, bulk, lookup, balance, pricing)? Use the [Transactional API](/transactional-api/overview). This is Instasent's SMS wholesale surface: OTPs, alerts, receipts, password resets, **API-driven campaigns via `POST /sms/bulk`**, HLR lookup, balance and per-country pricing. Two transports: - **HTTP** for most integrations, single or bulk. - **SMPP** when you need persistent sessions and carrier-grade throughput. Tokens live on an **API SMS** project; it's a thin container with senders and webhooks attached. #### 3. Do you need the SMS recorded against a specific customer (timeline, attribution, automations, analytics)? Use the [Product API — direct messaging](/product-api/guide). The send is written to the audience contact as an **event**, which means it feeds the timeline, segmentation, campaign attribution and delivery stats automatically — you do not instrument anything. The same API lists what campaigns and automations have sent, reads direct-SMS history, and exposes the senders registered on the project. Requires a **Standard** project and a Product API token with `PROJECT_DIRECT_WRITE`. > **Warning**: This is **not** the right tool for OTPs. It is slower to set up (you need an audience contact first) and heavier on scopes. If the message is one-shot and the recipient has no customer record, the Transactional API is the correct choice even if you happen to have a Standard project. #### 4. Are you pushing customer data into Instasent? Use the [Ingest API](/ingest-api/guide). Datasource-scoped write-only tokens, batched writes of up to 100 items per call, idempotent contacts and append-only events. The wire protocol is the same as the ingest endpoints in Product, but the token is narrower and the failure mode safer. Use Product API's ingest endpoints instead only when the same worker also reads audience data or manages configuration — then you want the broader token anyway. #### 5. Are you reading audience data, events, segments, campaigns or automations? Use the [Product API](/product-api/guide). It is the only read surface for these. Plan scopes carefully: `PROJECT_AUDIENCE_READ` gets you contacts at Default privacy; `PROJECT_AUDIENCE_DATA_BASIC` or `_FULL` is required to see most fields; `PROJECT_AUDIENCE_DATA_EVENTS` is required for event reads. See [Data privacy and plan gating](/product-api/guide#data-privacy-and-plan-gating). #### 6. Do you need an HLR / number lookup? Use the [Transactional API](/transactional-api/overview) — `POST /lookup`, `GET /lookup/{id}` and `GET /lookup`. Legacy also exposes the same endpoints for existing integrations, but new code should go to Transactional along with any SMS you send from the same application. ## The four APIs in one paragraph each **[Product API](/product-api/guide).** The control plane **and** the customer-communication API. It manages organizations, projects, datasources and the unified audience, and it is the API for everything around messaging a known customer: sending direct SMS to audience contacts, reading direct-SMS history and messages attributed to campaigns or automations, listing campaigns and automations with their stats, and reading the SMS senders configured on each project. Every message sent through it is also written to the audience contact as an **event**, which is why it feeds the timeline, segmentation and attribution analytics out of the box. Token scopes are fine-grained. **[Ingest API](/ingest-api/guide).** A surface-narrowed subset of Product, focused on **writing** contacts and events into a single datasource. Same endpoints, narrower token, safer blast radius. The right choice for CRM syncs, e-commerce webhooks, event streams. **[Transactional API](/transactional-api/overview).** Instasent's SMS wholesale surface, over HTTP or SMPP. No concept of audience — you send to a phone number, optionally get a DLR webhook, done. Full endpoint set: single send (`/sms`), bulk (`/sms/bulk`), message read, HLR lookup (`/lookup`), account balance, price profiles. Covers one-off messages (OTPs, alerts, receipts) and bulk dispatch — plenty of customers, marketing agencies included, run campaigns straight on this API. Also known as the SMS API. **[Legacy API](/legacy-api/overview).** The first-generation version of the SMS surface. Same endpoint set as Transactional (SMS send/bulk, SMS read, number lookup, account balance, price profiles) under a different token model and without DLR webhooks or SMPP. Still online for backwards compatibility — start all new work on Transactional. ## Combining APIs in the same application Most non-trivial integrations use two APIs together. Three common pairings: - **Ingest + Product** — a sync worker uses an Ingest token to push contacts and events; a separate service uses a Product token (read scopes) to query audiences, segments and analytics. The split means the write worker's credentials can't read PII. - **Product + Transactional** — Product manages the customer record and sends tracked messages as part of the lifecycle; Transactional handles stateless system messages (OTPs, alerts) that shouldn't go through the audience pipeline. - **Legacy + Transactional** — a gradual migration: Transactional for new code paths, Legacy for the code you haven't rewritten yet. Lookup, balance and pricing are available on both, so the migration moves one endpoint at a time without being blocked on any of them. A single token never spans two APIs; each API issues its own. ## Side by side | | Product API | Ingest API | Transactional API | Legacy API | | ------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **Main job** | Manage projects and audiences; send, read and analyse messaging (direct, campaigns, automations). | Push contacts and events into a datasource. | SMS wholesale surface: single (`/sms`), bulk (`/sms/bulk`), read, HLR lookup, balance, pricing. | Same endpoint set as Transactional, first-generation (backwards compatibility). | | **Transport** | HTTP | HTTP | HTTP, SMPP | HTTP | | **Project type** | Standard | Standard | API SMS | n/a (org-wide) | | **Token scope** | Org or project; fine-grained scopes. | Datasource; write-only. | Org or API-SMS project. | Org-wide. | | **Auth** | Bearer token. | Bearer token. | Bearer token (HTTP); system\_id/password (SMPP). | Bearer token. | | **DLRs** | Tracked as events on the audience contact. | n/a | Webhook per token. | Polling only. | | **Messages as events** | Yes — every send is written to the contact and feeds analytics. | n/a | No | No | | **Campaign / automation reads** | Yes — list, view, and their sent messages with stats. | No | No | No | | **Contact tracking** | Yes — tied to audience. | Writes only; no read. | No | No | | **Number lookup (HLR)** | No | No | Yes (`/lookup`) | Yes (`/lookup`) | | **Status for new work** | Recommended | Recommended | Recommended | Backwards compatibility only | ## Common pitfalls - **Using Product for OTPs.** It works, but you pay in setup cost (you need an audience contact) and in write scope (`PROJECT_DIRECT_WRITE`). For a one-shot code that doesn't need to live on a customer timeline, Transactional is the correct answer. - **Using Transactional for customer-lifecycle messages you want to analyze.** If the business cares about who got what and what they did next, you need the message in the audience timeline. That means Product direct messaging, not Transactional. - **Thinking Transactional is "just for OTPs".** It is Instasent's SMS wholesale API. Bulk sends, API-driven campaigns, HLR lookup, balance and pricing all live here — not only on Legacy. - **Assuming Lookup only lives on Legacy.** It is on [Transactional](/transactional-api/overview) too, at the same path. New code should call Lookup on Transactional. - **Starting new work on Legacy.** Transactional is the evolution of Legacy — same endpoints, plus DLR webhooks, SMPP and per-project tokens. There is no SMS feature that justifies starting fresh on Legacy. - **One token for everything.** A Product API token with every scope granted is a liability. Split by workload: one token per worker, minimum scopes, rotate independently. - **Skipping the Ingest API because Product has the same endpoints.** The narrower token is a feature, not a limitation — it stops a compromised sync worker from reading PII. ## What to read next - [Product API — Guide](/product-api/guide) - Control plane: organizations, projects, audiences, events. - [Ingest API — Quickstart](/ingest-api/quickstart) - Push a contact and an event in under five minutes. - [Transactional API — Quickstart](/transactional-api/http/quickstart) - Send your first SMS over HTTP. - [Legacy API — Overview](/legacy-api/overview) - What's still here, and when to migrate.