API Integration Overview

Integrate directly with the Barid Sender API for full programmatic control over letter creation, management, and delivery.

Start

1. Get API Credentials

Request API Credentials from the Barid team

• apiClientId - Your client identifier
• apiClientSecret - Your client secret
• API Base URL (Production or Staging)
• Provide your IP addresses for whitelisting

2. Authenticate

Exchange your API credentials for a session token:

curl -X POST https://sender.api.barid.ae/api/v1/auth/login/api \
  -H "Content-Type: application/json" \
  -d '{
    "apiClientId": "YOUR_CLIENT_ID",
    "apiClientSecret": "YOUR_CLIENT_SECRET"
  }'

Response:

{
	"sessionId": "string",
	"senderId": "123e4567-e89b-12d3-a456-426614174000",
	"validUntilUtc": "2025-11-14T10:29:13.139Z",
	"isValid": true
}

API Endpoints

Base URLs

Production:

https://sender.api.barid.ae

Staging:

https://qa.sender.api.barid.ae

Core Endpoints

Method	Endpoint	Description
POST	/api/v1/letters	Create letter
POST	/api/v1/invoices	Create invoice

Authentication Examples

The API uses session-based authentication with API credentials. Sessions are valid for 30 minutes and can be refreshed.

Login to Get Session:

// Example: Login with API credentials
const login = async () => {
	const response = await fetch('https://sender.api.barid.ae/api/v1/auth/login/api', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({
			apiClientId: process.env.API_CLIENT_ID,
			apiClientSecret: process.env.API_CLIENT_SECRET
		})
	})

	const data = await response.json()
	return data.sessionId // Valid for 30 minutes
}

Making Authenticated Requests:

Include the session ID in the X-Session header:

const response = await fetch('https://sender.api.barid.ae/api/v1/letters', {
	headers: {
		'X-Session': sessionId
	}
})

Session Refresh:

Sessions can be refreshed within the 30-minute window:

const refreshSession = async (currentSessionId) => {
	const response = await fetch('https://sender.api.barid.ae/api/v1/auth/refresh', {
		method: 'POST',
		headers: {
			'X-Session': currentSessionId
		}
	})

	const data = await response.json()
	return data.sessionId // New session ID
}

Best Practices:

• Implement automatic session refresh before the 30-minute expiration
• Store session tokens securely in memory (not localStorage)
• Handle 401 responses by re-authenticating
• Monitor session expiration with the validUntilUtc timestamp

For detailed authentication documentation, see the Authentication Guide.

Error Handling

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Invalid/expired token
403	Forbidden - Insufficient permissions
404	Not Found
429	Too Many Requests - Rate limited
500	Internal Server Error

Error Response Format

All error responses follow this structure:

{
	"message": "A general or specific message about the error",
	"statusCode": 400,
	"errorCode": "INVALID_DATA",
	"traceId": "00-abc123def456..."
}

Fields:

• message - Human-readable error description
• statusCode - HTTP status code (matches response status)
• errorCode - Machine-readable error code for client-side handling (see error codes below)
• traceId - Unique identifier for request tracing and support

Common Error Codes:

Error Code	Description
INVALID_DATA	Invalid or missing required data
INVALID_SESSION	Session token is invalid or expired
INVALID_CREDENTIALS	Authentication credentials are incorrect
INSUFFICIENT_AUTHORIZATION	User lacks required permissions
ENTITY_NOT_FOUND	Requested resource does not exist
UNEXPECTED_ERROR	An unexpected server error occurred
SERVICE_UNAVAILABLE	Service is temporarily unavailable
IP_ADDRESS_UNAUTHORIZED	Request from unauthorized IP address
API_CLIENT_ID_REQUIRED	API client ID is missing
API_CLIENT_SECRET_REQUIRED	API client secret is missing

For a complete list of error codes, see the API Reference.

Use Sender Client

To see your data visually, you can use the Sender Client. Credentials will be provided when registered.

Next Steps

Complete API Reference

For detailed endpoint documentation, request/response schemas, and interactive testing, visit the API Reference link in the navigation menu above.

Support

• Email: support@barid.ae