Pintel SMS API – Documentation

Pintel • SMS API

All timestamps are UTC unless noted • DND respected

Overview

The Pintel SMS API lets you send messages, simulate inbound webhooks, schedule future messages, and manage a full contact book with search and CRUD. Responses are JSON and the API is secured via an API key header. Each customer uses their own subdomain base URL like {subdomain}.pintelsms.com.

Content-Type

application/json

Auth Header

X-API-Key: <YOUR_API_KEY>

Rate limits

Reasonable per account; contact support for bursts.

Status

Account must be active

Phone format

E.164 (e.g. +15551234567)

Max body

1,600 characters

Conversations

Created automatically as needed

Case-insensitive across name/phone/email

Authentication

Send your API key in the X-API-Key header with every request. Example:

curl -H "X-API-Key: YOUR_API_KEY" https://{subdomain}.pintelsms.com/api/whoami

Tip: store your key in an environment variable like $PINTEL_API_KEY and use -H "X-API-Key: $PINTEL_API_KEY".

Base URL

https://{subdomain}.pintelsms.com/api

Replace {subdomain} with your assigned account subdomain (e.g., meir.pintelsms.com).

Messages

GET

Who Am I

/whoami

Returns account metadata and DND window.

curl -X GET https://{subdomain}.pintelsms.com/api/whoami \
  -H "X-API-Key: $PINTEL_API_KEY"

Sample response

{
  "account": {
    "id": "account_id",
    "name": "Account Name",
    "subdomain": "meir",
    "timezone": "America/New_York",
    "dndStart": "22:00",
    "dndEnd": "08:00",
    "dndAutoReply": "We're currently unavailable...",
    "status": "active"
  }
}

POST

Send Message

/external/messages/send

Field	Type	Required	Description
`to`	string (E.164)	Yes	Recipient phone number.
`body`	string	Yes	SMS content (≤1,600 chars).
`conversationId`	string	No	Attach to an existing conversation.

curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{
    "to": "+15551234567",
    "body": "Hello! This is a test message from the API.",
    "conversationId": "optional_conversation_id"
  }'

Sample response

{
  "success": true,
  "messageId": "generated_message_id",
  "conversationId": "conversation_id"
}

Inbound & Webhooks

Use this endpoint to simulate inbound messages (useful for testing your webhook pipeline).

POST

Simulate Receive

/external/messages/receive

Field	Type	Required	Description
`from`	string (E.164)	Yes	Sender phone number.
`body`	string	Yes	Incoming message text.
`timestamp`	ISO-8601	No	Defaults to now; UTC recommended.

curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/receive \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{
    "from": "+13473138764",
    "body": "This is a test incoming message",
    "timestamp": "2025-01-21T20:20:00.000Z"
  }'

Sample response

{
  "success": true,
  "messageId": "generated_message_id"
}

When enabled, real inbound/outbound events are forwarded to your configured webhook URL.

Scheduling

POST

Schedule Message

/external/messages/schedule

Field	Type	Required	Description
`to`	string (E.164)	Yes	Recipient phone number.
`body`	string	Yes	SMS content.
`scheduledFor`	ISO-8601	Yes	UTC recommended.
`conversationId`	string	No	Optional conversation binding.

curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/schedule \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{
    "to": "+15551234567",
    "body": "This is a scheduled message test",
    "scheduledFor": "2025-01-21T20:30:00.000Z"
  }'

Sample response

{
  "success": true,
  "scheduledMessageId": "generated_scheduled_message_id",
  "conversationId": "conversation_id"
}

Contacts

Manage your address book. IDs are 24‑char MongoDB ObjectIds. Duplicate phone numbers are prevented; phone numbers are normalized and validated.

GET

List Contacts

/external/contacts

curl -X GET https://{subdomain}.pintelsms.com/api/external/contacts \
  -H "X-API-Key: $PINTEL_API_KEY"

POST

Create Contact

/external/contacts

Field	Type	Required	Description
`id`	string	No	Optional custom ObjectId (must be valid/unique).
`firstName`	string	Yes	First name.
`lastName`	string	No	Last name.
`phone`	string (E.164)	Yes	Primary phone.
`email`	string	No	Email address.
`notes`	string	No	Freeform notes.

curl -X POST https://{subdomain}.pintelsms.com/api/external/contacts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+1987654321",
    "email": "jane@example.com",
    "notes": "VIP customer"
  }'

GET

Get Contact

/external/contacts/{id}

curl -X GET https://{subdomain}.pintelsms.com/api/external/contacts/{id} \
  -H "X-API-Key: $PINTEL_API_KEY"

PUT

Update Contact

/external/contacts/{id}

curl -X PUT https://{subdomain}.pintelsms.com/api/external/contacts/{id} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith Updated",
    "phone": "+1987654321",
    "email": "jane.updated@example.com",
    "notes": "Updated VIP customer"
  }'

DELETE

Delete Contact

/external/contacts/{id}

curl -X DELETE https://{subdomain}.pintelsms.com/api/external/contacts/{id} \
  -H "X-API-Key: $PINTEL_API_KEY"

GET

Search Contacts

/external/contacts/search?q=...

curl -X GET "https://{subdomain}.pintelsms.com/api/external/contacts/search?q=Jane" \
  -H "X-API-Key: $PINTEL_API_KEY"

Error Handling

Status	Meaning	Notes
`400`	Bad Request	Validation error (e.g., missing fields, invalid phone, invalid custom ID).
`401`	Unauthorized	Missing/invalid API key.
`404`	Not Found	Resource/Contact not found.

# Examples
curl -X GET https://{subdomain}.pintelsms.com/api/whoami            # → 401 (no key)
curl -H "X-API-Key: invalid" https://{subdomain}.pintelsms.com/api/whoami  # → 401
curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/send \
  -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
  -d '{"body": "Missing to"}'                                 # → 400
curl -X GET https://{subdomain}.pintelsms.com/api/external/contacts/507f...999 \
  -H "X-API-Key: $PINTEL_API_KEY"                               # → 404

Behavior & Notes

Phone numbers must be E.164; duplicates are prevented in contacts.
Scheduled timestamps should be ISO‑8601 (UTC recommended).
Webhooks include firstName, lastName, and notes when available.
Names are stored as firstName + lastName; a combined name field is derived automatically.
Search is case‑insensitive and scans name, phone, and email.

Quick Test Sequences

Messages

# 1) WhoAmI
curl -X GET https://{subdomain}.pintelsms.com/api/whoami -H "X-API-Key: $PINTEL_API_KEY"
# 2) Send
curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/send \
 -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
 -d '{"to":"+13473138764","body":"Quick test message"}'
# 3) Schedule
curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/schedule \
 -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
 -d '{"to":"+13473138764","body":"Scheduled test","scheduledFor":"2025-01-21T20:30:00.000Z"}'
# 4) Inbound simulate
curl -X POST https://{subdomain}.pintelsms.com/api/external/messages/receive \
 -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
 -d '{"from":"+13473138764","body":"Simulated inbound","timestamp":"2025-01-21T20:20:00.000Z"}'

Contacts

# 1) List
curl -X GET https://{subdomain}.pintelsms.com/api/external/contacts -H "X-API-Key: $PINTEL_API_KEY"
# 2) Create
curl -X POST https://{subdomain}.pintelsms.com/api/external/contacts \
 -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
 -d '{"firstName":"Test","lastName":"Contact","phone":"+15551234567","email":"test@example.com"}'
# 3) Search
curl -X GET "https://{subdomain}.pintelsms.com/api/external/contacts/search?q=Test" -H "X-API-Key: $PINTEL_API_KEY"
# 4) Update
curl -X PUT https://{subdomain}.pintelsms.com/api/external/contacts/REPLACE_ID \
 -H "Content-Type: application/json" -H "X-API-Key: $PINTEL_API_KEY" \
 -d '{"firstName":"Updated","lastName":"Test Contact","notes":"Updated"}'
# 5) Delete
curl -X DELETE https://{subdomain}.pintelsms.com/api/external/contacts/REPLACE_ID -H "X-API-Key: $PINTEL_API_KEY"