canonical: https://jentic.com/apis/pidj.co/pidj

# Pidj API

Jentic publishes the only available OpenAPI specification for Pidj API, keeping it validated and agent-ready. Pidj API enables business SMS messaging with contact management, user administration, and task orchestration. The API supports sending SMS messages, managing contact lists, configuring user accounts with pause/unpause controls, SSO integration, and initiating automated messaging tasks across business communication workflows.

## For AI agents

Send business SMS messages, manage contacts and user accounts, and orchestrate automated messaging tasks for customer communication.

## Scope

Does not handle email delivery, voice calls, or push notifications - use for business SMS messaging and contact management only.

## Capabilities

- Send SMS messages to contacts with delivery tracking
- Initiate automated messaging tasks for bulk outreach campaigns
- Manage contact records with phone number and profile data
- Administer user accounts with pause, unpause, and recovery controls
- Generate SSO URLs for single sign-on authentication flows
- Configure user permissions and account settings

## Use cases

### Business SMS Outreach

Send transactional and promotional SMS messages to customers through Pidj. The /send endpoint accepts recipient phone numbers and message content, delivering messages with status tracking. Businesses use this for appointment reminders, order confirmations, and marketing campaigns.

Example prompt: Send an SMS message to contact phone number +15551234567 with the text 'Your order has shipped' and confirm delivery status

### Automated Messaging Tasks

Orchestrate multi-step messaging campaigns by initiating tasks through the Pidj API. The `/task/initiate` endpoint triggers automated workflows that send sequences of messages to contact groups, enabling drip campaigns, follow-up sequences, and scheduled outreach without manual intervention.

Example prompt: Initiate a messaging task targeting contact group with automated follow-up sequence

### Contact and User Management

Maintain a central contact database and manage user accounts through the Pidj API. Create contacts with phone numbers and metadata, administer user access with pause and recovery controls, and configure SSO for team authentication.

Example prompt: Create a new contact with phone number +15559876543 and name 'Jane Doe', then list all active contacts

### AI Agent SMS Integration

AI agents use the Pidj API through Jentic to send SMS messages and manage contacts without manual API configuration. Agents search for messaging operations by intent, load the endpoint schema, and execute calls with Jentic handling Basic authentication and message formatting.

Example prompt: Search Jentic for 'send business SMS message', load the Pidj /send endpoint schema, and send a message to a customer contact

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/send` | Send an SMS message |
| POST | `/task/initiate` | Initiate an automated messaging task |
| GET | `/user/{id}` | Retrieve user account details |
| POST | `/user` | Create a new user account |
| POST | `/user/{id}/pause` | Pause a user account |
| POST | `/user/{id}/unpause` | Unpause a user account |
| GET | `/contact/{id}` | Retrieve a contact record |
| GET | `/sso/url` | Generate SSO authentication URL |

## Key resources

- **Messages** — Send SMS messages with delivery tracking
- **Tasks** — Initiate and manage automated messaging workflows
- **Users** — Create, pause, unpause, and recover user accounts
- **Contacts** — Manage contact records with phone and profile data
- **SSO** — Generate single sign-on URLs for authentication

## Why Jentic

- **Setup:** Wiring the Pidj API by hand means setting up its basic auth with your account key as the username and token as the password, then coding each SMS send, user, and contact call yourself. Through Jentic you install once, import Pidj from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Pidj puts the user and contact id in the URL path (`/user/{id}`, `/contact/{id}`), so a rule can pin your agent to one user: it can read that user and send messages. You choose the operations it may call, so state changes like pausing or unpausing a user are not included unless you add them.
- **Credential handling:** Your Pidj basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a business SMS' or 'look up a contact', and Jentic returns the matching Pidj operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Plivo API** — Plivo offers SMS and voice APIs with broader international coverage and more granular delivery reporting
- **ClickSend API** — ClickSend provides multi-channel messaging including SMS, email, and postal mail from a single API
- **TextMagic API** — TextMagic provides business SMS with scheduling, templates, and two-way messaging capabilities

## FAQ

### Why is there no official OpenAPI spec for Pidj API?

Pidj does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Pidj API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Pidj API use?

The Pidj API uses HTTP Basic authentication with your account credentials. Through Jentic, these credentials are stored encrypted in your Jentic One instance and agents receive scoped access without handling raw passwords directly.

### Can I send bulk SMS messages with the Pidj API?

Yes. The `/task/initiate` endpoint triggers automated messaging workflows that send messages to groups of contacts. For individual messages, use the /send endpoint with a single recipient phone number.

### How do I pause and resume a user account through the Pidj API?

Use POST `/user/{id}/pause` to temporarily suspend a user account and POST `/user/{id}/unpause` to reactivate it. The `/user/{id}/recover` endpoint handles account recovery scenarios.

### How do I send an SMS through the Pidj API using Jentic?

Search Jentic for 'send business SMS message', load the /send operation schema, and execute with recipient phone number and message body. Jentic injects Basic auth headers automatically and returns delivery status.

### Does the Pidj API support contact segmentation?

The API provides contact management through the /contact endpoints where you can create, retrieve, and update contact records. Contact grouping for targeted messaging is handled through the task initiation workflow.

### Can I limit what my agent is allowed to do with the Pidj API?

Yes. Jentic One runs self-hosted, so your own rules decide which Pidj operations and credentials the agent may use. Because Pidj carries the user and contact id in the URL path (`/user/{id}`, `/contact/{id}`), you can pin the agent to a single user and allow only read and send-message calls. State-changing operations like pausing or unpausing a user through `/user/{id}/pause` and `/user/{id}/unpause` stay out of reach unless you explicitly grant them.