Getting Started with LigueLead

Base URL & Authentication

Base URL:

https://api.liguelead.com.br/v1

Messaging requests require dual header authentication:

* The app management endpoints (/v1/apps) are the one exception: they authenticate with api-token alone. Requiring an app-id to create your first app would be circular.

Getting Your Credentials

Get Your Credentials: Access your LigueLead account at areadocliente.liguelead.app.br and navigate to Integrations → API Token.

Managing Apps Programmatically

With an api-token, you can create, list, and remove apps without returning to the dashboard. These three endpoints—and only these endpoints—authenticate with api-token alone, without the app-id header, because requiring one to create your first app would be circular.

Create an App

Create an app with POST /v1/apps.

Authentication: Send api-token only. Do not send app-id, because this endpoint creates the app identifier.

curl -X POST "https://api.liguelead.com.br/v1/apps" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My ERP Integration"
  }'

A successful request returns 201 Created:

{
  "message": "App created successfully",
  "data": {
    "id": "6f1c9d24-3b7e-4a02-9f88-2c1de4b7a910",
    "name": "My ERP Integration"
  }
}

Send the returned id as the app-id header on every messaging request from that point forward. It is the same value with two names: id in this response and app-id in the header.

List Apps

List your apps with GET /v1/apps.

Authentication: Send api-token only. Do not send app-id, because this endpoint manages app identifiers.

curl -X GET "https://api.liguelead.com.br/v1/apps" \
  -H "api-token: YOUR_API_TOKEN"

A successful request returns 200 OK:

{
  "message": "Success",
  "data": [
    {
      "id": "6f1c9d24-3b7e-4a02-9f88-2c1de4b7a910",
      "name": "My ERP Integration"
    },
    {
      "id": "a3e57c81-04b9-4d6f-b2aa-95f0e1c73d42",
      "name": "Checkout Notifications"
    }
  ]
}

This endpoint lists only active apps belonging to your account. The account is resolved from the token, never from data sent in the request.

Remove an App

Remove an app with DELETE /v1/apps/{id}.

Authentication: Send api-token only. Do not send app-id, because this endpoint manages app identifiers.

curl -X DELETE "https://api.liguelead.com.br/v1/apps/6f1c9d24-3b7e-4a02-9f88-2c1de4b7a910" \
  -H "api-token: YOUR_API_TOKEN"

A successful request returns 200 OK:

{
  "message": "App removed successfully",
  "data": {
    "id": "6f1c9d24-3b7e-4a02-9f88-2c1de4b7a910"
  }
}

Removal takes effect immediately: the app stops authenticating requests as soon as the call returns, while messages already sent by it remain in reports. An app that is not yours returns 404, the same response as an app that never existed.

Status Codes

Errors

Errors include the reason in an error field:

{
  "error": "An app with this name already exists, or the app limit for this client was reached"
}

Validation errors are the exception: error is a list so you can identify the field:

{
  "error": [
    {
      "field": "name",
      "message": "Name is required"
    }
  ]
}

name is the only accepted field when you create an app. Any other field is rejected, not ignored.

Limits

Both limits apply only to active apps: you can have up to 50 active apps per client, and each name must be unique among them. Removing an app frees its slot and its name.

🚀 Quick Start

1. Test Your Authentication

curl -X GET "https://api.liguelead.com.br/v1/voice/uploads" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID"

2. Send Your First SMS

curl -X POST "https://api.liguelead.com.br/v1/sms" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First SMS",
    "message": "Hello from LigueLead!",
    "phones": ["11999999999"]
  }'

📱 Phone Number Format

Important: The API accepts phone numbers both with and without country code (DDI):

✅ Accepted: "11999999999" (national format)
✅ Accepted: "+5511999999999" or "5511999999999" (with DDI)

For best compatibility, the national 11-digit format is recommended, but numbers with country code are also supported.

🔄 Asynchronous Processing

Both SMS and Voice message sending are asynchronous operations:

• Response: 202 Accepted (request queued for processing)
• Tracking: Use the Campaign endpoints to monitor delivery status
• Real-time Updates: Consider implementing webhooks (contact support)

🏗️ API Structure

The LigueLead API is organized into logical groups:

🛡️ Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 201 - Created (for uploads)
• 202 - Accepted (for async operations)
• 400 - Bad Request
• 401 - Unauthorized
• 404 - Not Found
• 409 - Conflict
• 422 - Unprocessable Entity
• 429 - Rate Limited
• 500 - Server Error

📋 Next Steps

1. Send a Voice Message - Learn the two-step process
2. Send an SMS - Quick SMS delivery
3. API Limits - Understand rate limits and constraints

💡 Best Practices

• Test with small batches before scaling up
• Store audio IDs from uploads for reuse
• Use groups to organize related campaigns
• Handle rate limits gracefully in your application

🆘 Support

Need help? Contact our support team through the LigueLead Client Area.