Sender IDs

This API manages the sender Ids, Associates them to Apps or Customers or the Overall Tuku Environment.

Overview

Managing Sender IDs is a crucial feature for users (customers or app owners) who wish to send SMS messages under a branded name. A Sender ID represents the name that appears as the sender when SMS messages are sent. The process ensures compliance with regulations, validates ownership, and facilitates proper identification.

Key Features:

1. KYC Submission

   • Users must provide KYC documentation for the requested Sender ID.

   • Required documents include certificates of incorporation, tax documents, identification documents, etc.

2. Sender ID Proposals

   • Users propose up to 5 names for the Sender ID during the application process.

3. Payment

   • Users pay a predefined amount (e.g., KES 15,000) for Sender ID registration.

4. Approval Workflow

   • Tuku Pay reviews the application, purchases the Sender ID on behalf of the user, and maps it to their account.

5. Types of Sender IDs

   • Global: Accessible by all apps in the ecosystem.

   • App Global: Restricted to the admin(s) of a specific app.

   • User Specific: Only accessible to the user who applied for it.

6. Status Management

   • Sender IDs can be activated or deactivated.

7. Notifications

   • Users receive an SMS notification once the Sender ID is approved and ready for use.

---

Endpoint: Apply for a Sender ID

• Method: POST

• URL: /api/sender-id/apply

Request Body:

{
  "appId": "app123",
  "userId": "user456",
  "proposedNames": ["TUKUPAY", "TUKUMONEY", "TUKUAPP", "TUKUSMS", "TUKUGLOBAL"],
  "kycDetails": {
    "certificateOfIncorporation": "https://example.com/documents/certificate.pdf",
    "taxCertificate": "https://example.com/documents/tax.pdf",
    "idDocument": "https://example.com/documents/id.pdf"
  },
  "paymentDetails": {
    "amountPaid": 15000,
    "transactionReference": "TXN78901"
  }
}

Request Body Fields:

Field	Type	Required	Description
appId	string	Yes	The ID of the app applying for the Sender ID.
userId	string	Yes	The user ID of the applicant.
proposedNames	array	Yes	List of up to 5 proposed Sender ID names.
kycDetails	object	Yes	Links to KYC documents.
kycDetails.certificateOfIncorporation	string	Yes	Link to the Certificate of Incorporation.
kycDetails.taxCertificate	string	Yes	Link to the tax certificate.
kycDetails.idDocument	string	Yes	Link to the identification document.
paymentDetails	object	Yes	Details of the payment for Sender ID registration.
paymentDetails.amountPaid	number	Yes	The amount paid for registration (e.g., 15000).
paymentDetails.transactionReference	string	Yes	The transaction reference for the payment.

---

Endpoint: Retrieve Sender IDs

• Method: GET

• URL: /api/sender-id/list

Query Parameters:

Field	Type	Required	Description
appId	string	Yes	The ID of the app to retrieve Sender IDs for.
userId	string	No	Optional filter to retrieve user-specific IDs.
status	string	No	Filter by status (active or inactive).

Response Example:

[
  {
    "senderId": "TUKUPAY",
    "type": "appGlobal",
    "status": "active",
    "mappedTo": {
      "appId": "app123",
      "userId": "user456"
    },
    "createdAt": "2024-12-01T10:00:00Z"
  },
  {
    "senderId": "TUKUMONEY",
    "type": "userSpecific",
    "status": "inactive",
    "mappedTo": {
      "userId": "user789"
    },
    "createdAt": "2024-12-02T12:00:00Z"
  }
]

---

Endpoint: Update Sender ID Status

• Method: PUT

• URL: /api/sender-id/update-status

Request Body:

{
  "senderId": "TUKUPAY",
  "status": "inactive"
}

Request Body Fields:

Field	Type	Required	Description
senderId	string	Yes	The Sender ID to update.
status	string	Yes	The new status (active or inactive).

---

Endpoint: Notify User of Approved Sender ID

• Method: POST

• URL: /api/sender-id/notify

Request Body:

{
  "userId": "user456",
  "senderId": "TUKUPAY",
  "message": "Your Sender ID 'TUKUPAY' has been approved and is now active."
}

Request Body Fields:

Field	Type	Required	Description
userId	string	Yes	The user ID to notify.
senderId	string	Yes	The approved Sender ID.
message	string	Yes	The message to send to the user.

---

Sender ID Data Model

Field	Type	Description
senderId	string	The unique Sender ID name (e.g., TUKUPAY).
type	string	The type of Sender ID: global, appGlobal, or userSpecific.
status	string	The status of the Sender ID: active or inactive.
mappedTo	object	The app or user this Sender ID is mapped to.
createdAt	datetime	The timestamp when the Sender ID was created.