Skip to main content

​
Karibu Campaign API Documentation

The Karibu Campaign API allows developers to create, list, retrieve, and update SMS campaigns within developer-accessible workspaces. This API is designed for organizing bulk messaging efforts efficiently and securely.

​
Authentication

All API endpoints require an X-API-Key header for authentication.
HeaderTypeRequiredDescription
X-API-KeystringYesYour API key.

​
Endpoints Overview

The Karibu Campaign API supports the following endpoints:
EndpointMethodDescription
/v1/campaign/create/POSTCreates a new campaign in a workspace.
/v1/campaign/all/GETRetrieves all campaigns for the authenticated user.
/v1/campaign/{campaign_id}/GETRetrieves details of a specific campaign.
/v1/campaign/update/{campaign_id}PATCHUpdates an existing campaign.

​
1. Create Campaign

Create a new campaign in a developer-accessible workspace owned by the authenticated user.

​
Endpoint

POST /v1/campaign/create/

​
Request Body

FieldTypeRequiredDescription
workspace_idstring (UUID)YesID of the workspace for the campaign.
namestringYesName of the campaign.
descriptionstring or nullNoDescription of the campaign.
launch_datestring (date-time)YesCampaign launch date (ISO 8601 format).

​
Request Example

{
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "name": "Summer Sale 2025",
  "description": "Promotional campaign for summer discounts",
  "launch_date": "2019-08-24T14:15:22Z"
}

​
Response Example

{
  "success": true,
  "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "name": "Summer Sale 2025",
  "description": "Promotional campaign for summer discounts",
  "launch_date": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
2. List Campaigns

Retrieve all campaigns for the authenticated user in developer-accessible workspaces they own.

​
Endpoint

GET /v1/campaign/all/

​
Response Example

{
  "success": true,
  "campaigns": [
    {
      "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",
      "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
      "name": "Summer Sale 2025",
      "description": "Promotional campaign for summer discounts",
      "launch_date": "2019-08-24T14:15:22Z",
      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
3. Get Campaign Details

Retrieve details of a specific campaign in a developer-accessible workspace owned by the user.

​
Endpoint

GET /v1/campaign/{campaign_id}/

​
Path Parameters

FieldTypeRequiredDescription
campaign_idstringYesUnique campaign ID.

​
Response Example

{
  "success": true,
  "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "name": "Summer Sale 2025",
  "description": "Promotional campaign for summer discounts",
  "launch_date": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
4. Update Campaign

Update an existing campaign in a developer-accessible workspace owned by the user.

​
Endpoint

PATCH /v1/campaign/update/{campaign_id}

​
Path Parameters

FieldTypeRequiredDescription
campaign_idstringYesUnique campaign ID.

​
Request Body

FieldTypeRequiredDescription
namestring or nullNoUpdated name of the campaign.
descriptionstring or nullNoUpdated description of the campaign.
launch_datestring or nullNoUpdated launch date (ISO 8601 format).

​
Request Example

{
  "name": "Updated Summer Sale 2025",
  "description": "Updated promotional campaign with extended offers",
  "launch_date": "2019-08-24T14:15:22Z"
}

​
Response Example

{
  "success": true,
  "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "name": "Updated Summer Sale 2025",
  "description": "Updated promotional campaign with extended offers",
  "launch_date": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 200
}

​
Error Response (422)

{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}

​
Standard Response Format

Unless specified otherwise, successful responses follow this JSON format: 
{
  "success": true,
  "message": "string",
  "data": {},
  "status_code": 200
}
Error responses (e.g., 422 Validation Error) follow this format: 
{
  "success": false,
  "message": "Validation error",
  "data": {},
  "status_code": 422
}
⌘I