Evon
Docs
Leads API

Leads API

Create and manage leads through the API with product associations.

The Leads API allows you to create new leads (contacts) and associate them with products in your organization.

Create Lead

Create a new lead with optional product associations.

Endpoint

POST /api/leads

Headers

X-API-Key: your_api_key_here
Content-Type: application/json

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "locale": "EN_US",
  "products": [
    {
      "productId": "uuid-of-product",
      "frequency": "MONTHLY",
      "locale": "EN_US"
    }
  ]
}

Parameters

FieldTypeRequiredDescription
firstNamestringYesLead's first name
lastNamestringYesLead's last name
emailstringYesValid email address
phonestringYesPhone number
localestringNoLanguage locale (default: EN_US)
productsarrayNoArray of product associations

Supported Locales

  • EN_US - English (United States)
  • ES_ES - Spanish (Spain)
  • ES_MX - Spanish (Mexico)
  • FR_FR - French (France)
  • DE_DE - German (Germany)
  • IT_IT - Italian (Italy)
  • PT_BR - Portuguese (Brazil)
  • RU_RU - Russian (Russia)
  • ZH_CN - Chinese (China)
  • JA_JP - Japanese (Japan)

Product Frequencies

  • MONTHLY - Monthly billing
  • QUARTERLY - Quarterly billing
  • BIANNUAL - Bi-annual billing
  • ANNUAL - Annual billing

Success Response

{
  "success": true,
  "data": {
    "id": "uuid-of-created-lead",
    "firstName": "John",
    "lastName": "Doe",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "stage": "LEAD",
    "products": [
      {
        "id": "uuid-of-contact-product",
        "frequency": "MONTHLY",
        "locale": "EN_US",
        "startDate": null,
        "product": {
          "id": "uuid-of-product",
          "name": "Premium Plan",
          "description": "Our premium offering",
          "price": 99.99,
          "type": "SUBSCRIPTION",
          "category": "SOFTWARE"
        }
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Example Request

curl -X POST "https://dev.api.evoncrm.com/api/leads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@company.com",
    "phone": "+1-555-987-6543",
    "locale": "EN_US",
    "products": [
      {
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "frequency": "ANNUAL"
      }
    ]
  }'

Error Responses

400 Bad Request - Validation Error

{
  "error": "Datos inválidos",
  "details": [
    {
      "code": "invalid_string",
      "expected": "string",
      "message": "El nombre es requerido",
      "path": ["firstName"]
    }
  ]
}

404 Not Found - Invalid Product

{
  "error": "Uno o más productos no fueron encontrados o están inactivos"
}

409 Conflict - Duplicate Email

{
  "error": "Ya existe un contacto con este email"
}

Use Cases

  • Lead Capture Forms: Convert website visitors to leads
  • CRM Integration: Sync leads from external systems
  • Marketing Campaigns: Create leads from campaign responses
  • Sales Automation: Automatically create leads from various touchpoints

Best Practices

  1. Validate Email: Ensure email format is correct before sending
  2. Check Duplicates: Handle 409 responses gracefully
  3. Product Validation: Verify product IDs exist before associating
  4. Locale Consistency: Use consistent locale across lead and products
  5. Error Handling: Implement retry logic for 500 errors
Forms APIMagic Links API