Favorites

The Favorites API allows you to manage customer favorite numbers, including adding, updating, removing, and checking favorite numbers. All favorite operations require authentication and respect cooloff periods.

Get Customer Information

Get customer information from VCare API.

Endpoint

GET /v1/favorites/customer-info/{customer_phone_number}

Authentication

This endpoint requires authentication with a valid Bearer token.

Path Parameters

Parameter	Type	Required	Description
customer_phone_number	`string`	Yes	Customer's phone number

Example Request

curl -X GET https://fav3.vibemobi.com/v1/favorites/customer-info/+1-1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

Returns customer information from the VCare API (structure varies based on external API).

Add Favorite Number

Add a new favorite number for a customer. Only customers with valid plans can add favorite numbers.

Endpoint

POST /v1/favorites/

Authentication

This endpoint requires authentication with a valid Bearer token.

Request Body

Parameter	Type	Required	Description
customer_phone_number	`string`	Yes	Customer's phone number in format: +{Country Code}-{PhoneNumber}
phone_number	`string`	Yes	Phone number to add as favorite in format: +{Country Code}-{PhoneNumber}
label	`string`	Yes	Label for the favorite number (1-50 characters)

Example Request

curl -X POST https://fav3.vibemobi.com/v1/favorites/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone_number": "+1-1234567890",
    "phone_number": "+1-0987654321",
    "label": "Mom"
  }'

Response

{
    "phone_number": "+1-0987654321",
    "label": "Mom",
    "is_active": true,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscription_id": "456e7890-e89b-12d3-a456-426614174001",
    "country_id": "789e0123-e89b-12d3-a456-426614174002",
    "last_modified_at": "2023-12-01T10:00:00Z",
    "created_at": "2023-12-01T10:00:00Z",
    "is_in_cooloff_period": false,
    "cooloff_expires_at": null
}

Update Favorite Label

Update the label of an existing favorite number. This operation respects the 14-day cooloff period.

Endpoint

PUT /v1/favorites/

Authentication

This endpoint requires authentication with a valid Bearer token.

Request Body

Parameter	Type	Required	Description
customer_phone_number	`string`	Yes	Customer's phone number in format: +{Country Code}-{PhoneNumber}
phone_number	`string`	Yes	Phone number to update in format: +{Country Code}-{PhoneNumber}
new_label	`string`	Yes	New label for the favorite number (1-50 characters)

Example Request

curl -X PUT https://fav3.vibemobi.com/v1/favorites/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone_number": "+1-1234567890",
    "phone_number": "+1-0987654321",
    "new_label": "Mother"
  }'

Response

{
    "phone_number": "+1-0987654321",
    "label": "Mother",
    "is_active": true,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscription_id": "456e7890-e89b-12d3-a456-426614174001",
    "country_id": "789e0123-e89b-12d3-a456-426614174002",
    "last_modified_at": "2023-12-01T10:30:00Z",
    "created_at": "2023-12-01T10:00:00Z",
    "is_in_cooloff_period": true,
    "cooloff_expires_at": "2023-12-15T10:30:00Z"
}

Remove Favorite Number

Remove (deactivate) a favorite number. This operation respects the cooloff period.

Endpoint

DELETE /v1/favorites/

Authentication

This endpoint requires authentication with a valid Bearer token.

Request Body

Parameter	Type	Required	Description
customer_phone_number	`string`	Yes	Customer's phone number in format: +{Country Code}-{PhoneNumber}
favorite_phone	`string`	Yes	Favorite phone number to remove in format: +{Country Code}-{PhoneNumber}

Example Request

curl -X DELETE https://fav3.vibemobi.com/v1/favorites/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone_number": "+1-1234567890",
    "favorite_phone": "+1-0987654321"
  }'

Response

{
    "message": "Favorite number removed successfully"
}

Check Favorite Number

Check if a target phone number is in a customer's favorites. Only works for customers with valid plans.

Endpoint

GET /v1/favorites/check

Authentication

This endpoint requires authentication with a valid Bearer token.

Request Body

Parameter	Type	Required	Description
customer_phone	`string`	Yes	Customer's phone number in format: +{Country Code}-{PhoneNumber}
target_phone	`string`	Yes	Phone number to check in format: +{Country Code}-{PhoneNumber}

Example Request

curl -X GET https://fav3.vibemobi.com/v1/favorites/check \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "+1-1234567890",
    "target_phone": "+1-0987654321"
  }'

Response

{
    "is_favorite": true,
    "customer_phone": "+1-1234567890",
    "target_phone": "+1-0987654321",
    "message": "Number is in favorites"
}

Response (Not a Favorite)

{
    "is_favorite": false,
    "customer_phone": "+1-1234567890",
    "target_phone": "+1-0987654321",
    "message": "Number is not in favorites"
}

Get Customer Favorites

Get all favorite numbers for a specific customer.

Endpoint

GET /v1/favorites/{customer_phone}

Authentication

This endpoint requires authentication with a valid Bearer token.

Path Parameters

Parameter	Type	Required	Description
customer_phone	`string`	Yes	Customer's phone number

Example Request

curl -X GET https://fav3.vibemobi.com/v1/favorites/+1-1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
    "customer_phone": "+1-1234567890",
    "subscription_id": "456e7890-e89b-12d3-a456-426614174001",
    "country": {
        "country_name": "United States",
        "country_code": "US",
        "phone_prefix": "+1",
        "is_active": true,
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "created_at": "2023-01-01T00:00:00Z"
    },
    "favorites": [
        {
            "phone_number": "+1-0987654321",
            "label": "Mother",
            "is_active": true,
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "subscription_id": "456e7890-e89b-12d3-a456-426614174001",
            "country_id": "789e0123-e89b-12d3-a456-426614174002",
            "last_modified_at": "2023-12-01T10:30:00Z",
            "created_at": "2023-12-01T10:00:00Z",
            "is_in_cooloff_period": true,
            "cooloff_expires_at": "2023-12-15T10:30:00Z"
        },
        {
            "phone_number": "+1-1122334455",
            "label": "Work",
            "is_active": true,
            "id": "234e5678-e89b-12d3-a456-426614174003",
            "subscription_id": "456e7890-e89b-12d3-a456-426614174001",
            "country_id": "789e0123-e89b-12d3-a456-426614174002",
            "last_modified_at": "2023-11-15T14:20:00Z",
            "created_at": "2023-11-15T14:20:00Z",
            "is_in_cooloff_period": false,
            "cooloff_expires_at": null
        }
    ],
    "active_count": 2,
    "remaining_slots": 3
}

Cooloff Period

The favorites system implements a 14-day cooloff period for certain operations to prevent abuse:

What Triggers Cooloff

Adding a favorite number: Puts the number in cooloff period
Updating a favorite label: Extends the cooloff period
Removing a favorite number: May trigger cooloff depending on system settings

Cooloff Restrictions

During the cooloff period: - The favorite number cannot be modified again - The number cannot be removed - Any attempts to modify will return an error

Cooloff Response Fields

Field	Type	Description
is_in_cooloff_period	`boolean`	Whether the favorite is currently in cooloff
cooloff_expires_at	`string`	ISO 8601 timestamp when cooloff expires (null if not in cooloff)

Error Responses

Customer Not Found

{
    "detail": "Customer not found or does not have a valid plan"
}

Invalid Phone Number

{
    "detail": [
        {
            "loc": ["body", "phone_number"],
            "msg": "ensure this value has at least 8 characters",
            "type": "value_error.any_str.min_length"
        }
    ]
}

Cooloff Period Active

{
    "detail": "Cannot modify favorite number during cooloff period. Cooloff expires at 2023-12-15T10:30:00Z"
}

Maximum Favorites Reached

{
    "detail": "Maximum number of favorite numbers reached for this customer"
}

Favorite Not Found

{
    "detail": "Favorite number not found for this customer"
}

Duplicate Favorite

{
    "detail": "This phone number is already in the customer's favorites"
}

Business Rules

Important Business Rules

Plan Validation - Only customers with valid, active plans can manage favorite numbers - Plan validation is performed against the VCare API

Cooloff Period - 14-day cooloff period applies to most favorite operations - During cooloff, favorites cannot be modified or removed - Cooloff period can be configured via system settings

Limits - Each customer has a maximum number of favorite slots (typically 5) - The remaining_slots field shows how many more favorites can be added

Phone Number Validation - Phone numbers must be in format: +{Country Code}-{PhoneNumber} - Example: +1-1234567890, +91-9876543210 - Numbers are validated for format and existence - Duplicate favorites are not allowed per customer

Rate Limiting

Favorite operations may be rate-limited to prevent abuse. If you encounter rate limiting errors, implement exponential backoff in your client applications.