Build on Senpede
A REST API for reading and creating contacts, and reading campaigns, in your Senpede organization. JSON over HTTPS, versioned, rate-limited, and authenticated with an API key you control.
Base URL
https://api.senpede.com
Version
/api/v1
Format
application/json
Authentication
Every request needs an API key, sent as a bearer token:
Generate a key from your organization's Settings → API Keys page (you'll need a Senpede account). The full key is shown once, at creation, then only a hash is stored, so keep it somewhere safe.
Each key is scoped to exactly what it's allowed to do:
| contacts:read | List and fetch contacts. |
| contacts:write | Create contacts (includes read access). |
| campaigns:read | List and fetch campaigns. |
Rate limits
Every key defaults to 120 requests per minute, and can be configured up to 6,000 per minute when you create it. Requests over the limit get a 429 response — back off and retry.
Endpoints
Contacts
Create a contact. fullName is required; everything else is optional.
curl https://api.senpede.com/api/v1/public/contacts \
-H "Authorization: Bearer sen_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Ama Boateng",
"email": "ama@example.com",
"phone": "+233241234567",
"tags": [
"newsletter"
]
}'List contacts, with optional search.
curl https://api.senpede.com/api/v1/public/contacts?page=1&pageSize=20&q=ama \
-H "Authorization: Bearer sen_your_api_key"Campaigns
Read-onlyList and inspect campaigns created in the dashboard. Creating or sending a campaign through the API isn't available yet — composing a campaign involves choosing an audience, a channel, and a message, which today is a dashboard flow. It's on the roadmap.
curl https://api.senpede.com/api/v1/public/campaigns?status=COMPLETED \
-H "Authorization: Bearer sen_your_api_key"Errors
Errors share one shape, with a stable code you can branch on and a requestId to reference if you need help:
{
"error": {
"code": "VALIDATION_ERROR",
"category": "VALIDATION",
"message": "Validation failed.",
"retryable": false,
"validationIssues": [
{ "field": "fullName", "message": "fullName is required." }
],
"requestId": "req_01hx..."
}
}Webhooks
Webhook is one of Senpede's messaging channels: configure a destination URL on a channel in your workspace, and outbound deliveries are POSTed there, signed with an HMAC-SHA256 signature you can verify. A general events API for subscribing to account-level events (contact created, campaign sent, and so on) isn't available yet.
More endpoints are coming
This page covers what's available today. A full interactive reference is on the way — until then, reach out if you need something this page doesn't cover.