API Reference

Complete reference for all YeboLink API endpoints. This page provides a comprehensive overview of available endpoints, grouped by functionality.

Base URL

Production: https://api.yebolink.com
Development: https://dev-api.yebolink.com

Authentication Methods

YeboLink supports two authentication methods:

• API Keys: For sending messages and accessing message data programmatically

  • Header: X-API-Key: ybk_...
  • Use for: Message sending, message retrieval

• JWT Tokens: For dashboard access and account management

  • Header: Authorization: Bearer <token>
  • Use for: Account management, API key creation, billing, webhooks

Endpoints Overview

Authentication

Method	Endpoint	Description	Auth Required
POST	/api/v1/auth/signup	Create new workspace account	None
POST	/api/v1/auth/login	Login to workspace	None
POST	/api/v1/auth/verify-email	Verify email address	None
POST	/api/v1/auth/forgot-password	Request password reset	None
POST	/api/v1/auth/reset-password	Reset password	None

Messages

Method	Endpoint	Description	Auth Required
POST	/api/v1/messages/send	Send a single message	API Key
POST	/api/v1/messages/bulk	Send bulk messages	API Key
GET	/api/v1/messages	Get message history	API Key
GET	/api/v1/messages/:id	Get message by ID	API Key

API Keys

Method	Endpoint	Description	Auth Required
POST	/api/v1/api-keys	Create new API key	JWT
GET	/api/v1/api-keys	List all API keys	JWT
DELETE	/api/v1/api-keys/:id	Deactivate API key	JWT

Contacts

Method	Endpoint	Description	Auth Required
POST	/api/v1/contacts	Create new contact	JWT
GET	/api/v1/contacts	List all contacts	JWT
GET	/api/v1/contacts/:id	Get contact by ID	JWT
PUT	/api/v1/contacts/:id	Update contact	JWT
DELETE	/api/v1/contacts/:id	Delete contact	JWT

Webhooks

Method	Endpoint	Description	Auth Required
POST	/api/v1/webhooks	Create webhook	JWT
GET	/api/v1/webhooks	List all webhooks	JWT
GET	/api/v1/webhooks/events	Get supported events	JWT
GET	/api/v1/webhooks/:id	Get webhook by ID	JWT
PUT	/api/v1/webhooks/:id	Update webhook	JWT
DELETE	/api/v1/webhooks/:id	Delete webhook	JWT
GET	/api/v1/webhooks/:id/deliveries	Get webhook deliveries	JWT

Billing

Method	Endpoint	Description	Auth Required
GET	/api/v1/billing/packages	Get credit packages	None
POST	/api/v1/billing/checkout	Create checkout session	JWT
GET	/api/v1/billing/transactions	Get transaction history	JWT
POST	/api/v1/billing/webhook	Stripe webhook endpoint	Stripe Signature

Request & Response Format

Standard Success Response

All successful API requests return a JSON response with this structure:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Standard Error Response

All error responses follow this structure:

{
  "success": false,
  "error": "Error message description"
}

Pagination

Endpoints that return lists support pagination with these query parameters:

Parameter	Type	Default	Max	Description
page	integer	1	-	Page number
limit	integer	50	100	Items per page

Paginated responses include:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 150,
      "page": 1,
      "pages": 3,
      "limit": 50
    }
  }
}

Rate Limits

Different endpoints have different rate limits:

Endpoint Type	Rate Limit
API Key endpoints	100 requests/minute
Bulk messaging	10 requests/minute
Authentication endpoints	5 attempts/15 minutes

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698960000

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 30 seconds."
}

Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
402	Payment Required	Insufficient credits
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Message Channels

YeboLink supports multiple messaging channels:

Channel	Value	Description
SMS	sms	Text messages via cellular networks
WhatsApp	whatsapp	Messages via WhatsApp Business API
Email	email	Email messages
Voice	voice	Voice calls (coming soon)

Message Status

Messages can have the following statuses:

Status	Description
queued	Message queued for sending
sent	Message sent to provider
delivered	Message delivered to recipient
failed	Message failed to send
read	Message read by recipient (WhatsApp only)

Credit Costs

Different channels have different credit costs:

Channel	Credits per Message/Unit
SMS	1 credit per message (160 chars)
WhatsApp	0.5 credits per message
Email	0.1 credits per email
Voice	2 credits per minute

TIP

Long SMS messages are automatically split into segments. Each segment costs 1 credit. For example, a 320-character SMS will cost 2 credits.

Health Check

Check API health status:

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-11-02T12:00:00Z",
  "services": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  }
}

Webhook Signature Verification

All webhook events include a signature header for verification:

X-YeboLink-Signature: sha256=...

See Webhook Verification for implementation details.

Need Help?

• Check our Quick Start Guide
• Read Error Handling documentation
• Contact support: support@yebolink.app