API Documentation | Aéllo Copilot Customer API

Version 1.0 — create and sync leads into Aéllo Copilot from your own systems.

1. Getting Started

1.1 Environments

The Aéllo Copilot API is available in the following environments:

Sandbox. Your test environment. Entities are persisted temporarily and it is isolated from your dealership's real environment.

Production. Your dealership's production environment. Be careful with production endpoints, as you are touching real data: users may get notifications, automations may be triggered and other data may be updated. Do not use this environment to test your integration.

1.2 Base URL

All API requests should be made to the base URL of your environment.

Sandbox

https://api.customers.sandbox.aello-copilot.com

Production

https://api.customers.aello-copilot.com

Important: contact us at tech@aello-group.com to get an Aello-Api-Key for your sandbox environment.

1.3 Authorization

The Aéllo Copilot API uses API keys to authenticate requests. Your API key is provided by the admin user in the application. To authenticate, include your API key in the request header:

Aello-Api-Key: your-api-key-here

Important: keep your API key secure and never share it publicly. Store it in environment variables or a secure configuration management system.

2. Guide

2.1 Creating a Lead

To create a lead in Aéllo Copilot, send a POST request to the /leads endpoint with the lead details.

Example request

POST /leads
Content-Type: application/json
Aello-Api-Key: your-api-key-here

{
  "externalId": "external-id-12345679",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe123@email.com",
    "phoneCountryCode": "352",
    "phoneNumber": "612345679",
    "companyName": "Company XYZ"
  },
  "product": {
    "link": "https://example.com/product",
    "image": "https://example.com/image.jpg",
    "title": "Product Title",
    "reference": "10864675",
    "price": 45000
  },
  "message": "Hello world!"
}

Example response

HTTP/1.1 202 Accepted

3. API Reference

3.1 Leads — Create Lead

POST /leads

Creates a new lead in the Aéllo Copilot system. If the contact does not exist, a new contact is created. If the product reference does not exist in your dealership, a new product is created. If there is an existing lead sent by the same contact and the same product within the last 30 days, a new message is created under that lead instead.

Headers

Name	Type	Required	Description
`Aello-Api-Key`	string	Yes	Your API key for authentication
`Content-Type`	string	Yes	`application/json`

Request body

Field	Type	Required	Description
`externalId`	string	No	The lead identifier in your own internal system
`contact`	object	Yes	Contact information
`contact.firstName`	string	Yes	First name of the contact
`contact.lastName`	string	No	Last name of the contact
`contact.email`	string	No if phone is provided	Email address of the contact
`contact.phoneCountryCode`	string	No if email is provided	Phone country code (e.g. "352")
`contact.phoneNumber`	string	No if email is provided	Phone number without country code
`contact.companyName`	string	No	Company name
`product`	object	No	Product information
`product.link`	string	No	URL to the product
`product.image`	string	No	URL to the product image
`product.title`	string	No	Product title
`product.reference`	string	Yes if any product information is provided	Product reference number
`product.price`	number	No	Product price
`message`	string	No	Additional message or notes

Example request

{
  "externalId": "external-id-12345679",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe123@email.com",
    "phoneCountryCode": "352",
    "phoneNumber": "612345679",
    "companyName": "Company XYZ"
  },
  "product": {
    "link": "https://www.via-mobilis.fr/.../ts-vi10864675",
    "image": "https://photo.static-viamobilis.com/.../10864675.jpg",
    "title": "Camion remorque plateau standard occasion Renault Midlum 190.08",
    "reference": "10864675",
    "price": 45000
  },
  "message": "Hello world!"
}

Responses

202 Accepted The lead was successfully sent to processing. This does not mean a lead is created, but that we accepted it and will process it. Processing verifies and decides whether the contact, product, lead and message should be created, updated or added.

400 Bad Request Invalid request body or missing required fields.

{
  "error": "Invalid email",
  "code": "ERR-EMAIL-INVALID_OR_MALFORMED_EMAIL"
}

401 Unauthorized Missing or invalid API key.

{
  "error": "Unauthorized. HTTP request does not contain API key"
}

422 Unprocessable Entity The request syntax is correct, but the instructions could not be processed.

{
  "error": "Dealership not found",
  "code": "ERR-CREATE_LEAD-DEALERSHIP_NOT_FOUND"
}

500 Internal Server Error A server error occurred.

{
  "error": "Internal Server Error"
}

Need help?

If you have any questions about the API or need assistance, contact our team:

Email: tech@aello-group.com
Address: Aéllo Sàrl, 17 rue des Jardiniers, L-1835 Luxembourg

Aéllo Copilot Customer API