# Smstome — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse temporary phone numbers from countries around the world and read incoming SMS messages in real time. List available numbers by country, retrieve messages sorted newest to oldest, and search message history by sender or content.

**Category:** Developer Tools | **Website:** [smstome.com/](https://smstome.com/) | **Docs:** [parse.bot/marketplace/17baabba-90c1-4eb2-afad-aa4ee1a47aed/smstome-com-api](https://parse.bot/marketplace/17baabba-90c1-4eb2-afad-aa4ee1a47aed/smstome-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/smstome/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get messages

Get SMS messages received by a specific phone number. Messages are displayed newest to oldest, 10 per page. Use list_phone_numbers first to get the number, sms_id, and country parameters. Returns an empty messages array when no messages exist or for out-of-range pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | Yes | Country slug (e.g. 'poland', 'netherlands'). |
| `number` | string | Yes | Phone number without + prefix (e.g. '3197058045359'). From list_phone_numbers results. |
| `page` | integer | No | Page number for pagination (10 messages per page, newest first). |
| `sms_id` | string | Yes | SMS ID from list_phone_numbers response (e.g. '16709'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/smstome/get-messages \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","number":"<string>","page":"<integer>","sms_id":"<string>"}'
```

### List countries

List all available countries that have temporary phone numbers on smstome.com. Returns deduplicated country entries with slugs usable in other endpoints. The set is small (currently 6 countries) and returned in a single page.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/smstome/list-countries \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List phone numbers

List temporary phone numbers available for a specific country. Returns phone numbers with their country code, when they were added, and the sms_id needed to fetch messages. Returns 20 numbers per page. Use the returned number and sms_id to call get_messages or search_messages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Country slug from list_countries endpoint. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/smstome/list-phone-numbers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","page":"<integer>"}'
```

### Search messages

Search for messages matching any query on a specific phone number. Scans through multiple pages looking for messages where the sender or message content contains the search term (case-insensitive). Results are returned newest to oldest. Scanning stops when max_pages is reached or no more messages exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | Yes | Country slug (e.g. 'poland', 'netherlands'). |
| `max_pages` | integer | No | Maximum number of pages to scan (10 messages per page). |
| `number` | string | Yes | Phone number without + prefix. From list_phone_numbers results. |
| `query` | string | Yes | Search term to match against sender name or message content (case-insensitive). |
| `sms_id` | string | Yes | SMS ID from list_phone_numbers response. |
| `start_page` | integer | No | Page to start scanning from (1 = newest messages). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/smstome/search-messages \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","max_pages":"<integer>","number":"<string>","query":"<string>","sms_id":"<string>","start_page":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.