API Overview
Permanent Link provides a RESTful API, allowing developers to interact with our platform over standard HTTP methods in a predictable, resource-oriented manner. This makes integration simple, scalable, and language-independent.
What is a REST API?
A REST API (Representational State Transfer) is an architectural style for building web services. It uses standard HTTP methods like:
GET– Retrieve data (e.g., fetch a shortened link)POST– Create new resources (e.g., generate a new permalink)PUT– Update existing resourcesDELETE– Remove resources
REST APIs are stateless, meaning each request contains all the information needed
to process it — no session is stored on the server. Responses are typically returned in
JSON format for easy parsing.
Why REST for Permanent Link?
We chose REST for its simplicity, scalability, and wide adoption. Whether you’re building a web app, mobile app, or server-side integration, the REST architecture makes it easy to create, manage, and access your permalinks programmatically.
API Versioning
To ensure stability and backward compatibility, the API is versioned. Each major update that introduces breaking changes will be assigned a new version.
Current Version
The current stable version is:
v1
All endpoints are accessible via:
https://api.permanentlink.co.za/v1/Example with Versioning
Request:
GET https://api.permanentlink.co.za/v1/domains/available?domain=example.comHeaders:
Authorization: Bearer <your_token_here>Why Versioning?
Versioning allows developers to:
- Integrate with a consistent set of features.
- Avoid breaking changes when new features or improvements are introduced.
- Upgrade when ready, while older versions remain available for a period.
Future Versions
When a new version (e.g., v2) is released, older versions will be maintained for a limited time before deprecation. Notices will be provided in advance.
Example Request
GET https://api.permanentlink.co.za/v1/domains/available?domain=example.com
Host: api.permanentlink.co.za
Authorization: Bearer <token>Example Response
{
"uuid": 123,
"results": "success",
"is_available": true,
"message": "Domain is available."
}Authentication
To use the APIs, you must first have an active Permanent Link developer account. If you don't have one yet, you can sign up here.
Only users with a valid account can request a token to authenticate API requests.
All endpoints (except token request) require a valid Bearer token (JWT) in the
Authorization header.
1. Request a Token
POST https://api.permanentlink.co.za/v1/auth/login
2. Making Requests with a Token
Include the JWT in the Authorization header of all subsequent requests:
Authorization: Bearer <token>Example Request to Protected Endpoint:
GET https://api.permanentlink.co.za/v1/domains/domain=example.com
Headers:
Content-Type: application/json
Authorization: Bearer <token>Request Headers:
Content-Type: application/json
Authorization: Bearer <token>
Request Body:
{
"email": "user@example.com",
"password": "your_password"
}Successful Response:
{
"token": "eyJ0eXAiOiJKV1QiLC...", // expires in 1 hour
}Error Response (credentials not supplied):
{
"error": "Email and password are required"
}Error Response (invalid credentials):
{
"error": "Invalid credentials"
}Error Response (invalid headers):
{
"error": "Missing or invalid Authorization header"
}Error Response (invalid token):
{
"error": "Invalid or expired token"
}Explore Our APIs
Cloud Database
Store and manage your data in real time with our scalable cloud database API. Ideal for applications that need high availability, quick access, and secure storage.
Send SMS
Use our SMS API to send text messages directly to mobile numbers across various networks. Perfect for OTPs, alerts, marketing, and transactional messaging.
Send Email
Integrate reliable email sending into your applications with our email API. Great for transactional emails like confirmations, password resets, and notifications.
Domains
Check domain availability, register domains, and manage DNS settings using our Domains API. Simplifies domain lifecycle management from a single platform.
Example Request:
GET
https://api.permanentlink.co.za/{api-version}/{api}/{action}Headers:
Content-Type: application/json
Authorization: Bearer <token>Cloud Database
API Documentation Coming Soon: Full documentation for this endpoint will be available shortly. Please check back soon or contact support if you need immediate assistance.
Example Request:
GET
https://api.permanentlink.co.za/{api-version}/{api}/{action}Headers:
Content-Type: application/json
Authorization: Bearer <token>Send Email API
Use this endpoint to send transactional or personalized emails through the Permanent Link email service.
Request Body Parameters
The POST body must be a valid JSON object with the following structure:
{
"messages": {
"recipient": "user@example.com",
"subject": "Subject Here",
"message": "Hello {name}, your order {order_id} is confirmed.",
"replyto": "support@example.com",
"replytoName": "Support Team",
"from": "noreply@example.com",
"fromName": "Company Name"
},
"data": {
"{name}": "John",
"{order_id}": "123456"
}
}
Top-Level Keys
messages: (object, required) – Contains all the email message details.data: (object, optional) – Key-value pairs for template placeholder replacement in the message body.
Required Fields in messages
| Field | Type | Description |
|---|---|---|
recipient |
string | The email address of the recipient. |
subject |
string | The subject of the email. |
message |
string | The message body. You can include template tags (e.g. {name}) that will be replaced by values from data. You can also add this as an html string. |
replyto |
string | Email address for replies. |
replytoName |
string | Display name for the reply-to address. |
from |
string | Email address from which the message is sent. |
fromName |
string | Display name shown as the sender. |
Optional Field: data
This object contains key-value pairs used to dynamically substitute placeholders in the message content.
Each key should match a placeholder in the message string, for example, we have the '{name}' key with curly braces, therefore, the key in data should also have the curly brackets.
Example cURL
curl -X POST https://api.permanentlink.co.za/v1/email/send_messages \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
"messages": {
"recipient": "young.cet@gmail.com",
"subject": "Order Confirmation",
"message": "Hello {name}, your order {order_id} has been confirmed.",
"replyto": "support@permanentlink.co.za",
"replytoName": "Permanent Link Support",
"from": "noreply@permanentlink.co.za",
"fromName": "Permanent Link"
},
"data": {
"{name}": "Yung",
"{order_id}": "0000000"
}
}'Response
{
"uuid":"70fc957d1ee0955dd30f",
"results":"success",
"messages":[{
"recipient":"young.cet@gmail.com",
"status":"success"
}]
}Error Responses
{
"error": "Missing required parameters",
"code": 400
}Send SMS API
This API allows you to send SMS messages to a mobile number using a simple JSON payload.
Request Body Parameters
The POST body must be a valid JSON object with the following structure:
| Field | Type | Required | Description |
|---|---|---|---|
cellNumber |
string | Yes | The recipient's mobile number in international format (e.g. +27...). |
body |
string | Yes | The message content to be sent via SMS. |
testEnvironment |
boolean | No | If true, the message will be sent as a test message especially during development. |
Important Notes
- SMS credits are required to send messages. You can send an email to support@permanentlink.co.za to get pricing and purchase SMS credits.
Example cURL
curl -X POST https://api.permanentlink.co.za/v1/sms/send \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
"cellNumber": "+270600000000",
"body": "Hello, this is a test message",
"testEnvironment": true
}'
Response
{
"uuid":"70fc957d1ee0955dd30f",
"results":"success",
"sms_status":{
"status":"queued",
"sid":"SM7f3d561102880f38d4056a0d8ca77fa5"
}
}Error Responses
{
"error": "An error has occured. Please contact your
administrator and quote this error [sms-error-70fc957d1ee0955dd30f]",
"code": 400
}Domain Availability
This endpoint allows you to check whether a domain is available for registration.
Query Parameters
- domain
(required): The domain name you want to check (e.g.,example.com).
Notes
- Ensure the domain name is properly formatted (e.g., contains no spaces or invalid characters).
- This endpoint supports standard domain extensions such as
.com,.net,.org, and others.
Example cURL
curl -X GET "https://api.permanentlink.co.za/v1/domains/available/?domain=example.com" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>"
Response
{
"uuid":"70fc957d1ee0955dd30f",
"results":"success",
"is_available":true,
"message": "Domain is available"
}Error Responses
Status: 400 Bad Request
{
"error": "Missing or invalid domain parameter"
}
Status: 401 Unauthorized
{
"error": "Invalid or missing token"
}