# Deywuro Sender ID API - Client Documentation

## Overview

The Deywuro Sender ID API allows you to programmatically submit, track, and manage Sender ID requests without manual intervention through the web console. This document provides all the information you need to integrate with the API.

## Authentication

All API requests require an API key which should be included in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Your API key is specific to your account and should be kept secure. If you need a new API key, please contact your account administrator.

## Base URL

```
http://api.deywuro.com/v1
```

## IP Whitelisting

For enhanced security, the API uses IP whitelisting. Only requests from whitelisted IP addresses will be accepted. Contact your administrator to whitelist your IP addresses.

## Endpoints

### Sender ID Management

#### 1. Create a Sender ID Request

Submit a new sender ID for approval.

```
POST /sender-id
```

**Request Body:**
```json
{
    "sender_id": "COMPANY",
    "user_name": "your_username",
    "password": "your_password",
    "IP": "127.0.0.1"
}
```

**Parameters:**
- `sender_id`: Your requested sender ID (3-11 alphanumeric characters)
- `user_name`: Your Deywuro account username
- `password`: Your Deywuro account password
- `IP`: The IP address making the request (optional, defaults to the request IP)

**Response (Success):**
```json
{
    "success": true,
    "data": {
        "request_id": "REQ_1617282930123",
        "sender_id": "COMPANY",
        "status": "PENDING",
        "created_at": "2025-06-11T17:29:17+00:00"
    }
}
```

**Response (Error):**
```json
{
    "success": false,
    "error": {
        "message": "Missing required fields",
        "code": "MISSING_FIELDS",
        "details": {
            "sender_id": "Field sender_id is required"
        }
    }
}
```

#### 2. Get All Sender ID Requests

Retrieve all sender ID requests associated with your account.

```
GET /sender-id
```

**Query Parameters:**
- `page`: Page number (default: 1)
- `limit`: Results per page (default: 20, max: 100)
- `status`: Filter by status (PENDING, APPROVED, REJECTED)
- `date_from`: Filter from date (YYYY-MM-DD)
- `date_to`: Filter to date (YYYY-MM-DD)

**Response:**
```json
{
    "success": true,
    "data": {
        "requests": [
            {
                "request_id": "REQ_1617282930123",
                "sender_id": "COMPANY",
                "status": "PENDING",
                "created_at": "2025-06-11T17:29:15+00:00",
                "updated_at": "2025-06-11T17:29:15+00:00",
                "rejection_reason": null,
                "username": "your_username"
            }
        ],
        "pagination": {
            "total": 1,
            "page": 1,
            "limit": 10,
            "pages": 1
        }
    }
}
```

#### 3. Get a Specific Sender ID Request

Retrieve details for a specific sender ID request by request ID.

```
GET /sender-id/request/{request_id}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "request_id": "REQ_1617282930123",
        "sender_id": "COMPANY",
        "status": "PENDING",
        "created_at": "2025-06-11T17:29:15+00:00",
        "updated_at": "2025-06-11T17:29:15+00:00",
        "rejection_reason": null,
        "username": "your_username"
    }
}
```

#### 4. Get Sender ID Requests by Sender ID

Retrieve all requests for a specific sender ID.

```
GET /sender-id/{sender_id}
```

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "request_id": "REQ_1617282930123",
            "sender_id": "COMPANY",
            "status": "PENDING",
            "created_at": "2025-06-11T17:29:15+00:00",
            "updated_at": "2025-06-11T17:29:15+00:00",
            "rejection_reason": null,
            "username": "your_username"
        }
    ]
}
```

## Status Codes and Error Handling

### HTTP Status Codes

- `200`: Success
- `201`: Resource created
- `400`: Bad request (validation error)
- `401`: Unauthorized (invalid API key)
- `403`: Forbidden (IP not whitelisted)
- `404`: Resource not found
- `429`: Rate limit exceeded
- `500`: Server error

### Error Response Format

```json
{
    "success": false,
    "error": {
        "message": "Error message",
        "code": "ERROR_CODE",
        "details": {} // Optional additional details
    }
}
```

### Common Error Codes

- `AUTH_FAILED`: Authentication failed
- `MISSING_FIELDS`: Required fields missing
- `INVALID_SENDER_ID`: Sender ID format invalid
- `DUPLICATE_SENDER_ID`: Sender ID already exists
- `UNAUTHORIZED_IP`: IP address not whitelisted
- `NOT_FOUND`: Resource not found
- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
- `SERVER_ERROR`: Internal server error

## Rate Limiting

The API implements rate limiting to prevent abuse. Default limits are:
- 100 requests per hour
- 1000 requests per day

Rate limit headers are included in responses:

```
X-RateLimit-Limit-Hour: 100
X-RateLimit-Remaining-Hour: 99
X-RateLimit-Reset-Hour: 1617282930

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 999
X-RateLimit-Reset-Day: 1617282930
```

## Sender ID Status Notifications

You will receive SMS notifications when the status of your sender ID requests changes (approved or rejected). Ensure your account has an up-to-date phone number.

## Best Practices

1. Always validate data before sending to the API
2. Implement proper error handling
3. Store request IDs for future reference
4. Use pagination parameters for large result sets
5. Implement exponential backoff for rate limited requests

## Frequently Asked Questions

**Q: How long does sender ID approval take?**
A: Sender IDs are typically reviewed within 24-48 business hours.

**Q: What if my sender ID is rejected?**
A: You can check the rejection reason through the API and submit a new request.

**Q: What characters are allowed in sender IDs?**
A: Sender IDs can contain letters, numbers, and spaces. They must be 3-11 characters long.

**Q: How do I update my whitelisted IPs?**
A: Contact your account administrator to update your whitelisted IPs.

## Support

For any questions or issues, please contact support at support@deywuro.com.