# Instasent - legacy-api (full documentation)

> Autocontained dump of every page under /legacy-api. Paste this into an AI assistant or feed it to an agent as context for legacy-api integration work.

Source: https://docs.instasent.com/
OpenAPI spec: https://docs.instasent.com/openapi/legacy.openapi.yaml


---

URL: https://docs.instasent.com/legacy-api/overview

# Overview

The Legacy API is Instasent's first-generation SMS surface. It is superseded by the Transactional API, which exposes the same endpoint set plus DLR webhooks, SMPP and per-project tokens. Legacy stays online for backwards compatibility with existing integrations.

The Legacy API is the first-generation version of Instasent's SMS surface: sending, reading, HLR lookup, account balance and price profiles over REST at `https://api.instasent.com/`. It remains online so that existing integrations keep working unchanged.

> **Warning**: The [**Transactional API**](/transactional-api/overview) is the evolution of this one. It exposes the same endpoints (including `POST /sms/bulk`, `POST /lookup`, `GET /organization/account`, price profiles) and adds DLR webhooks, SMPP and per-project `api_sms` tokens. **All new integrations should go there — there is no SMS feature that is Legacy-only.**

## What it covers

- **Send SMS** — single message (`POST /sms`) or bulk batch (`POST /sms/bulk`).
- **Read SMS** — collection (`GET /sms`) and single-message lookup (`GET /sms/{id}`).
- **Number lookup** — HLR-style checks (`POST /lookup`, `GET /lookup/{id}`).
- **Account** — current balance and details (`GET /organization/account`).
- **Price profiles** — per-country pricing for SMS and Lookup.

Every one of these is also available on the [Transactional API](/transactional-api/overview) under the same paths. The full list of parameters, request bodies and response shapes lives in the [Legacy API Reference](/legacy-api/reference) — identical to the Transactional reference for the overlapping endpoints.

## Should I migrate?

If your integration is healthy and you are not adding new surface area, there is no pressure to move. The Legacy API will continue to deliver messages through the same carrier routes as the rest of the platform.

Migrate to [Transactional](/transactional-api/overview) when:

- You want **DLR webhooks** (Legacy exposes status via polling; Transactional pushes them).
- You need **SMPP** for carrier-grade throughput.
- You want **per-project tokens** (`api_sms`) rather than account-wide credentials — smaller blast radius, easier rotation.
- You are planning a larger feature that will touch the integration anyway — it is cheaper to do both at once.

There is no endpoint that lives only on Legacy, so the migration is always a straight swap of base-URL semantics and token scope, not a feature trade-off.

## What to read next

- [Authentication](/legacy-api/authentication) - Bearer token in the `Authorization` header.
- [API Reference](/legacy-api/reference) - Every endpoint, every parameter.
- [Transactional API](/transactional-api/overview) - The recommended target for new integrations.


---

URL: https://docs.instasent.com/legacy-api/authentication

# Authentication

The Legacy API authenticates each request with a bearer token issued in the dashboard. Send it in the Authorization header.

Every request to the Legacy API carries a bearer token. Tokens are created in the dashboard and passed in the `Authorization` header.

## Getting a token

Sign in to the [Instasent dashboard](https://dashboard.instasent.com), open **API tokens** and create one for the account that will send the traffic. Copy the value right away — it is shown once.

> **Warning**: Treat tokens as production secrets. Keep them in an environment variable or a secrets manager; never commit them to the repo or embed them in client-side code.

## Sending the token

```bash
curl https://api.instasent.com/sms \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Instasent", "to": "+34600000000", "text": "Hello" }'
```

A missing, malformed or revoked token returns `401 Unauthorized`.

## Rotating a token

Tokens do not expire. Rotate them whenever a member of the team leaves, whenever a secret might have been exposed, and at least once a year as a hygiene measure.

#### 1. Issue the replacement

Create a new token in the dashboard **before** revoking the old one so traffic keeps flowing while you redeploy.

#### 2. Roll it out

Update your secrets store and redeploy the workers that call the API.

#### 3. Revoke the old token

Once the replacement is live everywhere, delete the old token in the dashboard. Any request still using it will fail with `401 Unauthorized`.

## What's next

- **[API Reference](/legacy-api/reference)** — every endpoint and response code.
- **[Transactional API](/transactional-api/overview)** — the modern alternative for new integrations.