API Data

Récupérez les enregistrements détaillés d'appels et de SMS pour vos numéros trackés. Accédez aux données brutes des appels, aux agrégats journaliers et aux logs SMS de manière programmatique pour alimenter vos propres tableaux de bord, CRM et pipelines de reporting.

#1 Introduction

L'API Optico Data permet de récupérer les enregistrements d'appels et de SMS pour vos numéros de téléphone trackés. Interrogez les détails d'appels individuels ou des agrégats journaliers sur une plage de dates. Les résultats sont paginés et renvoyés en JSON.

Transport & conventions

#2 Authentification

Chaque requête doit inclure votre api_key en paramètre de query string. La clé est rattachée à un domaine et est délivrée à la création de votre compte sur www.optico.fr.

https://www.optico.fr/data-api?api_key=d4t4_5f4dcc3b5aa765d61d8327deb882cf99&...

#3 Erreurs

Toutes les réponses d'erreur partagent la même enveloppe :

{
  "status": "ERROR",
  "errors": [
    "Invalid api key",
    "Missing parameter `type`"
  ]
}

#4 Endpoints

#5 GET /data-api

Paramètres obligatoires

Paramètres optionnels

Pagination

Les résultats sont paginés. La réponse inclut un champ total_results et, lorsqu'il y a d'autres pages, un champ next_page. Itérez en incrémentant page jusqu'à ce que next_page soit absent.

#6 Types

#6.1 Appels (type=calls)

Renvoie les enregistrements d'appels individuels dans la plage de dates demandée. Vous pouvez optionnellement regrouper les résultats par jour en utilisant group_by_day=true.

6.1.1 Enregistrements d'appels individuels

Le mode par défaut (group_by_day=false). Chaque élément du results représente un appel.

Flux

Réponse en cas de succès

Champs de l'objet appel

Exemple

curl "https://www.optico.fr/data-api?api_key=d4t4_5f4dcc3b&type=calls&start_date=2026-01-01&end_date=2026-01-31&page=1&limit=50"

{
  "status": "OK",
  "total_results": 123,
  "next_page": 2,
  "results": [
    {
      "start_date":        "17/01/2026 14:30:45",
      "caller":            "+33612345678",
      "tracking_number":   "+33912345678",
      "phone":             "+33987654321",
      "trigger_type":      1,
      "source":            "Google Ads",
      "url":               "https://www.mysite.com/contact",
      "referer":           "google.com",
      "keyword":           "plumber paris",
      "call_path":         "https://www.mysite.com/
https://www.mysite.com/contact",
      "status":            "SUCCESS",
      "duration":          245,
      "billing_duration":  300,
      "revenue":           1.50,
      "postcode":          "75001",
      "keypad":            "1",
      "is_redirect":       false,
      "expired_redirect":  false,
      "answer_time":       8
    }
  ]
}

6.1.2 Appels agrégés par jour (group_by_day=true)

Lorsque group_by_day=true, les résultats sont condensés en une ligne par jour. Ce mode est utile pour construire des tableaux de bord et des graphiques de tendance sans récupérer chaque appel individuel.

Champs des résultats agrégés

Exemple

curl "https://www.optico.fr/data-api?api_key=d4t4_5f4dcc3b&type=calls&start_date=2026-01-01&end_date=2026-01-07&page=1&limit=100&group_by_day=true"

{
  "status": "OK",
  "results": [
    { "date": "2026-01-01", "calls": 45, "duration": 12350.5, "revenue": 67.89 },
    { "date": "2026-01-02", "calls": 38, "duration": 9870.0,  "revenue": 55.20 }
  ]
}

#6.2 SMS (type=sms)

Renvoie les SMS reçus sur vos numéros de tracking dans la plage de dates demandée. La pagination fonctionne de la même manière que pour les appels.

Champs de l'objet SMS

Exemple

curl "https://www.optico.fr/data-api?api_key=d4t4_5f4dcc3b&type=sms&start_date=2026-01-01&end_date=2026-01-31&page=1&limit=100"

{
  "status": "OK",
  "results": [
    {
      "sent_date":       "2026-01-17 14:30:45",
      "caller_phone":    "+33612345678",
      "tracking_phone":  "+33912345678",
      "id":              789,
      "message_content": "Hello, I'd like more information"
    }
  ]
}

#Annexe A : valeurs de statut d'appel

Le champ status d'un enregistrement d'appel décrit l'issue de l'appel. Utilisez ces valeurs avec le paramètre de filtre status (séparées par des virgules pour plusieurs valeurs).

#Annexe B : types de déclenchement

Le champ trigger_type indique comment un appel a été initié.