REST API Reference

Fast lookup endpoints for customers, subscriptions, services, and leads

These APIs are served from the CRM application. Authenticated v1 endpoints use API key authentication through the X-API-Key header or a Bearer token in the Authorization header.

Base URL

https://crm.avinox.ir/api
01

Authentication

How it works

  • Authenticated /api/v1/* endpoints use the custom auth.api middleware.
  • Send your API key in X-API-Key or as Authorization: Bearer YOUR_KEY.
  • Invalid, missing, or expired keys return 401 Unauthorized.
  • Authenticated routes are rate-limited with the leads-api limiter.
GET /api/v1/customers/by-phone?phone=09123456789
Host: crm.avinox.ir
X-API-Key: YOUR_API_KEY
Accept: application/json

# or
Authorization: Bearer YOUR_API_KEY
02

Customer APIs

POST /api/v1/customers

Creates a new customer using the existing authenticated customer creation API.

GET /api/v1/customers/by-phone

Finds a customer by exact phone value and returns the customer with all subscriptions, plus service details for each subscription.

Query Parameters

  • phone - required, exact customer phone number
curl --request GET \
  --url 'https://crm.avinox.ir/api/v1/customers/by-phone?phone=09123456789' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'
03

Subscription APIs

GET /api/v1/subscriptions/by-pppoe

Finds a single subscription directly by pppoe_username and returns the subscription, service, and customer snapshot.

Query Parameters

  • pppoe_username - required, exact PPPoE username
curl --request GET \
  --url 'https://crm.avinox.ir/api/v1/subscriptions/by-pppoe?pppoe_username=john.doe' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'
04

Service APIs

GET /api/v1/services

Returns all services with their related packages and key commercial and technical fields such as price, duration, rates, package type, technology, and status.

Authentication

  • Requires X-API-Key or Authorization: Bearer YOUR_API_KEY
  • No query parameters are required
curl --request GET \
  --url 'https://crm.avinox.ir/api/v1/services' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'
{
  "success": true,
  "message": "Services retrieved successfully",
  "data": {
    "services": [
      {
        "id": 7,
        "name": "100Mbps Fiber",
        "price": 850000,
        "duration_value": 1,
        "duration_unit": "month",
        "package_type": "Shared Package",
        "tech_code": "PPP",
        "download_rate": 100,
        "upload_rate": 50,
        "status": "active",
        "packages": [
          {
            "id": 4,
            "name": "Starter",
            "price": 850000
          }
        ]
      }
    ]
  }
}
05

Lead APIs

GET

/api/v1/leads

List leads.

POST

/api/v1/leads

Create a lead.

GET

/api/v1/leads/{lead}

Show a single lead.

PUT

/api/v1/leads/{lead}

Update a lead.

DELETE

/api/v1/leads/{lead}

Delete a lead.

POST

/api/v1/leads/{lead}/verify-email

Verify lead email.

POST

/api/v1/leads/{lead}/resend-verification

Resend verification email.

GET

/api/v1/leads/check-duplicate

Check duplicate lead by email or phone.

POST

/api/v1/leads/{lead}/convert

Convert a lead into a customer.

GET

/api/v1/leads/analytics/report

Return lead analytics reporting data.

Public lead endpoints

These endpoints are available without API key auth and use the public rate limiter: /api/v1/leads/public, /api/v1/leads/{lead}/status, and /api/v1/leads/{lead}/verify-email.

06

Responses & Errors

200 / 201

Successful responses use a consistent JSON structure with success, message, and optional data.

401

Returned when the API key is missing, invalid, or expired.

404 / 422

404 is returned for missing customer/subscription records. 422 is returned when required query parameters are missing or invalid.

{
  "success": false,
  "message": "API key is required",
  "error": "Missing API key. Please provide your API key in the X-API-Key header or Authorization header."
}