# Intellipush SMS API developer guide

Canonical URL: https://www.intellipush.com/en/developer-guide/

A runnable path from OAuth 2.0 client credentials to one created SMS.

## Token

POST to https://api.intellipush.com/restv2/token with the API ID and API Secret as HTTP Basic credentials, Content-Type application/x-www-form-urlencoded and grant_type=client_credentials.

## Create SMS

POST to https://api.intellipush.com/restv2/sms/create with the bearer token and the message, countrycode and phonenumber JSON fields. The call creates a real SMS and may use SMS credits.

## Production

Begin with your own test number and a low volume. Tokens are opaque, last 3,600 seconds and have no refresh token. Handle HTTP 400, 401, 403, 405, 409 and 5xx; distinguish these from delivery codes. status_message is not a stable machine code. Creation is not delivery: use the returned ID with POST /restv2/sms/status and id_array. Check /capabilities before optional features. With documented idempotency, persist one unique key per logical send and reuse the same key and identical payload for retries within 24 hours. Do not automatically retry uncertain creation requests. Keep secrets out of client-side code.

## Obtain a token and create one SMS

These examples follow the current OpenAPI contract. Replace only the environment variables and use a test number you control.

### Store credentials as secrets

Use the API ID and API Secret issued for the account. Store them in secure environment variables — never in public client-side code or a public repository.

```sh
export INTELLIPUSH_API_ID="your_api_id"
export INTELLIPUSH_API_SECRET="your_api_secret"
```

### Obtain an OAuth 2.0 token

The token endpoint uses HTTP Basic with the API ID as the username and API Secret as the password. The response contains a time-limited access token.

```sh
curl --request POST \
  --url https://api.intellipush.com/restv2/token \
  --user "$INTELLIPUSH_API_ID:$INTELLIPUSH_API_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials"
```

#### Example token response

```json
{
  "access_token": "ip_at_example_opaque_token_not_for_authentication",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": ""
}
```

### Create one SMS

Put the access token in the environment variable below. This call creates a real SMS and may use SMS credits, so begin with your own number and a low volume.

```sh
export INTELLIPUSH_ACCESS_TOKEN="your_access_token"
# Persist one unique key per logical send; reuse only for the same payload.
export INTELLIPUSH_IDEMPOTENCY_KEY="your_persisted_unique_send_key"

curl --request POST \
  --url https://api.intellipush.com/restv2/sms/create \
  --header "Idempotency-Key: $INTELLIPUSH_IDEMPOTENCY_KEY" \
  --header "Authorization: Bearer $INTELLIPUSH_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "Your appointment is confirmed.",
    "countrycode": "+47",
    "phonenumber": "12345678"
  }'
```

#### Example accepted response

```json
{
  "success": true,
  "data": {
    "id": 1210966,
    "message": "Your appointment is confirmed.",
    "countrycode": "+47",
    "phonenumber": "+4712345678",
    "sent": 0,
    "failed": 0,
    "deleted": 0
  },
  "status_message": "SMS was created successfully."
}
```

### Distinguish creation from delivery

An accepted creation response means the message has been registered. Use the returned ID with the status endpoint when the workflow needs delivery information.

```sh
curl --request POST \
  --url https://api.intellipush.com/restv2/sms/status \
  --header "Authorization: Bearer $INTELLIPUSH_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"id_array":[1210966]}'
```

### The same contract in Node.js and Python

The examples use environment variables and send one real SMS. Persist one unique key per logical send before the first attempt; reuse it only with an identical request.

#### Node.js 18+

```javascript
const apiId = process.env.INTELLIPUSH_API_ID;
const apiSecret = process.env.INTELLIPUSH_API_SECRET;
const basic = Buffer.from(`${apiId}:${apiSecret}`).toString('base64');

const tokenResponse = await fetch('https://api.intellipush.com/restv2/token', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${basic}`,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({ grant_type: 'client_credentials' }),
  signal: AbortSignal.timeout(30000)
});
if (!tokenResponse.ok) throw new Error(`Token request failed (${tokenResponse.status})`);
const { access_token } = await tokenResponse.json();

const sendKey = process.env.INTELLIPUSH_IDEMPOTENCY_KEY;
if (!sendKey) throw new Error('Missing persisted send key');
const smsResponse = await fetch('https://api.intellipush.com/restv2/sms/create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${access_token}`,
    'Idempotency-Key': sendKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Your appointment is confirmed.',
    countrycode: '+47',
    phonenumber: '12345678'
  }),
  signal: AbortSignal.timeout(30000)
});
if (!smsResponse.ok) throw new Error(`SMS request failed (${smsResponse.status})`);
const result = await smsResponse.json();
if (result.success === false) throw new Error('SMS request rejected');
console.log('SMS request accepted'); // Do not log recipient data or message bodies.
```

#### Python 3

```python
import base64
import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

api_id = os.environ['INTELLIPUSH_API_ID']
api_secret = os.environ['INTELLIPUSH_API_SECRET']
basic = base64.b64encode(f'{api_id}:{api_secret}'.encode()).decode()

token_request = Request(
    'https://api.intellipush.com/restv2/token',
    data=urlencode({'grant_type': 'client_credentials'}).encode(),
    headers={'Authorization': f'Basic {basic}', 'Content-Type': 'application/x-www-form-urlencoded'},
    method='POST'
)
with urlopen(token_request, timeout=30) as response:
    access_token = json.load(response)['access_token']

sms_request = Request(
    'https://api.intellipush.com/restv2/sms/create',
    data=json.dumps({
        'message': 'Your appointment is confirmed.',
        'countrycode': '+47',
        'phonenumber': '12345678'
    }).encode(),
    headers={'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json',
             'Idempotency-Key': os.environ['INTELLIPUSH_IDEMPOTENCY_KEY']},
    method='POST'
)
with urlopen(sms_request, timeout=30) as response:
    result = json.load(response)
if result.get('success') is False:
    raise RuntimeError('SMS request rejected')
print('SMS request accepted')  # Do not log recipient data or message bodies.
```

### Before production use

Handle 400, 401 and 5xx responses explicitly, protect credentials and treat the documentation as authoritative. Retain X-Request-ID for troubleshooting. Check /capabilities before using optional features; idempotency for create requests requires the capability to be enabled and the integration to supply its own Idempotency-Key.

[Read the operating plan for 409 responses, uncertain outcomes and delivery status](https://www.intellipush.com/en/sms-api-operations/)

The token is opaque, valid for 3,600 seconds, with no refresh token. HTTP status is authoritative; status_message is not a stable machine code. Distinguish HTTP status from delivery codes. Also handle 403, 405 and 409. Do not automatically retry an uncertain creation request without documented idempotency: persist one unique key per logical send and reuse the same key and identical payload for retries within 24 hours.

## Documentation

We serve businesses in Norway and Europe. SMS destinations, sender types and optional features must be checked for the country and account setup you intend to use.

Technical source checked 30 October 2026: Intellipush REST API 1.8.0, OpenAPI 3.1.2.

[Interactive API reference](https://api.intellipush.com/restv2/developer/)

[OpenAPI YAML](https://api.intellipush.com/restv2/developer/intellipush.yaml)
