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"
}

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

There is no limit on how many apps you can hold. App names are checked only against your active apps, so removing an app makes its name available for reuse.

🚀 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)

💡 Best Practice: Send numbers with the country code (5511999999999 or +5511999999999). Without it, the length decides: 10 or 11 digits are a national number and get 55 in front — area code 55 included, so 55991234567 is sent as 5555991234567. See API Limits for the validation rules.

🔄 Asynchronous Processing

Every send (SMS, voice, RCS and AI calls) is an asynchronous operation:

• Response: 200 OK for SMS and voice, 202 Accepted for RCS and AI calls (the request is queued, not yet delivered)
• Tracking: Use the campaign.status webhooks; GET /v1/campaigns/{campaign_id}/recipients also lists SMS recipients
• Real-time Updates: Webhooks, configured per app in the client area or per send with webhook_url — see How to Receive Webhooks

🏗️ 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 (async operations: RCS and AI calls; SMS and voice answer 200)
• 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
• Handle errors carefully: retry a 429; after a 5xx or a timeout, check what went out before resending a send — see API Limits

🆘 Support

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