API Documentation

Getting Started

The FineSpeak API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

https://api.finespeak.net/v1

SDK Libraries

PHP

composer require finespeak/sdk

Node.js

npm install finespeak

Python

pip install finespeak

Authentication

The FineSpeak API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

API Key Authentication

Include your API key in the Authorization header:

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Keep your API keys secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Phone Numbers

List Available Numbers

Search for available phone numbers to purchase.

GET /numbers/available

curl https://api.finespeak.net/v1/numbers/available?country=US&area_code=415 \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Purchase a Number

Purchase a phone number for your account.

POST /numbers/purchase

curl -X POST https://api.finespeak.net/v1/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Support Line"
  }'
                    

List Your Numbers

Retrieve a list of phone numbers belonging to your account.

GET /numbers

curl https://api.finespeak.net/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Calls

Make a Call

Initiate an outbound call.

POST /calls

curl -X POST https://api.finespeak.net/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "callback_url": "https://yourdomain.com/call-status"
  }'
                    

Retrieve Call Details

Get information about a specific call.

GET /calls/{call_id}

curl https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

End a Call

Terminate an active call.

DELETE /calls/{call_id}

curl -X DELETE https://api.finespeak.net/v1/calls/CA123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Messaging

Send SMS

Send an SMS message.

POST /messages

curl -X POST https://api.finespeak.net/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "+14155555678",
    "body": "Hello from FineSpeak!"
  }'
                    

List Messages

Retrieve message history.

GET /messages

curl https://api.finespeak.net/v1/messages?limit=50 \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Webhooks

FineSpeak uses webhooks to notify your application when events happen in your account. Webhooks are particularly useful for asynchronous events like incoming calls and messages.

Webhook Events

call.initiated - A call has been initiated
call.answered - A call has been answered
call.completed - A call has ended
message.received - An SMS message has been received
message.delivered - An SMS message has been delivered

Webhook Payload Example

{
  "event": "message.received",
  "timestamp": "2025-12-04T10:30:00Z",
  "data": {
    "message_id": "SM123456789",
    "from": "+14155555678",
    "to": "+14155551234",
    "body": "Hello!",
    "status": "received"
  }
}
                    

Error Codes

FineSpeak uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'to' parameter is required",
    "param": "to"
  }
}
                    

Quick Navigation