Esperanza
Developers

API Reference

Technical reference for integrating with the Esperanza platform APIs. Securely access platform functionality through authenticated requests.

Overview

The Esperanza API allows approved clients to securely access platform functionality through authenticated requests. All API access is over HTTPS, and data is sent and received as JSON.

Base URL
https://api.esperanza.et/v1

Authentication

Authenticate your API requests by including your API key in the Authorization header of every request.

bash
# Structure
Authorization: Bearer YOUR_API_KEY

Endpoints

Get Account Details

Retrieve information about the authenticated user account.

GET
https://api.esperanza.et/v1/account
Response
200 OKapplication/json
{
  "id": "acc_123456",
  "email": "user@example.com",
  "status": "active"
}

List Referrals

Get a list of users referred by the authenticated account.

GET
https://api.esperanza.et/v1/referrals
Response
200 OKapplication/json
{
  "data": [
    {
      "referral_id": "ref_001",
      "status": "verified"
    }
  ]
}

List Campaigns

Retrieve a list of all active and inactive marketing campaigns.

GET
https://api.esperanza.et/v1/campaigns
Response
200 OKapplication/json
{
  "data": [
    {
      "campaign_id": "cmp_789",
      "name": "Winter Promotion"
    }
  ]
}

Create Campaign

Create a new marketing campaign.

POST
https://api.esperanza.et/v1/campaigns
Response
200 OKapplication/json
{
  "campaign_id": "cmp_790",
  "status": "created"
}

Error Codes

Code
Description
400
Bad Request - The request was unacceptable, often due to missing a required parameter.
401
Unauthorized - No valid API key provided.
403
Forbidden - The API key doesn't have permissions to perform the request.
429
Rate Limit Exceeded - Too many requests hit the API too quickly.
500
Server Error - Something went wrong on Esperanza's end.