Data API

Retrieve detailed call and SMS records for your tracked numbers. Access raw call data, daily aggregates and SMS logs programmatically to power your own dashboards, CRMs and reporting pipelines.

#1 Introduction

The Optico Data API lets you retrieve call and SMS records for your tracked phone numbers. Query individual call details or daily aggregates over a date range. Results are paginated and returned as JSON.

Base URL https://www.optico.fr/data-api

Transport & Conventions

Method	All endpoints use `GET`
Parameters	Passed as URL query string parameters
Response format	`application/json`
Parameter names	`snake_case` in requests, `camelCase` in responses
Date format	`YYYY-MM-DD`
Pagination	1-based page index; `page=1` is the first page

#2 Authentication

Every request must include your api_key as a query string parameter. The key is tied to a domain and is issued when your account is created on www.optico.fr.

GET

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

⚠

If the api_key is missing, invalid, or the domain is inactive, the API returns an ERROR response with the message Invalid api key.

#3 Errors

All error responses share the same envelope:

json

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

Error message	Cause
`Invalid api key`	The `api_key` is missing, does not exist, or the domain is inactive.
`Missing parameter <name>`	A required parameter was not included in the request.
`Invalid date <value>`	The date is not a valid calendar date or is not in `YYYY-MM-DD` format.
`Limit must be between 10 and 5000`	The `limit` value is outside the allowed range.
`Invalid parameter type`	The `type` parameter is not `calls` or `sms`.
`Cannot handle request`	An unexpected server-side error occurred.

ℹ

Multiple validation errors can be returned in the same response; inspect the full errors array.

#4 Endpoints

Endpoint	Method	Purpose
`/data-api`	GET	Retrieve call and SMS records for your tracked phone numbers, paginated.

#5 GET /data-api

Required Parameters

Parameter	Type	Description
`api_key`required	string	Your Data API key.
`type`required	string	`calls` to retrieve call records, `sms` to retrieve SMS records.
`start_date`required	string	Start of the date range (inclusive). Format: `YYYY-MM-DD`.
`end_date`required	string	End of the date range (inclusive, through 23:59:59). Format: `YYYY-MM-DD`.
`page`required	integer	Page number, starting at `1`.
`limit`required	integer	Results per page. Min `10`, max `5000`.

Optional Parameters

Parameter	Type	Default	Description
`phone`optional	string	-	Filter results by destination phone number.
`tracking_phone`optional	string	-	Filter results by tracking (surtax) phone number.
`caller_phone`optional	string	-	Filter results by caller phone number.
`status`optional	string	-	Filter by call status. Comma-separated for multiple values. See Appendix A.
`offline_phone_description`optional	string	-	Filter by offline phone source description.
`group_by_day`optional	boolean	`false`	When `true`, returns one aggregated row per day instead of individual records.

Pagination

Results are paginated. The response includes a total_results field and, when more pages exist, a next_page field. Iterate by incrementing page until next_page is absent.

ℹ

Pages are 1-based. Always start with page=1. The next_page field is only present when additional results exist beyond the current page.

#6 Data types

#6.1 Calls (`type=calls`)

Returns individual call records within the requested date range. Optionally group the results by day using group_by_day=true.

6.1.1 Individual Call Records

The default mode (group_by_day=false). Each item in results represents one call.

Flow

→ You sends GET /data-api with type=calls, start_date, end_date, page, limit to Optico API

← Optico API returns status, total_results, [next_page], results[]

Repeat with page=next_page until next_page is absent to retrieve all records.

Success Response

Field	Type	Description
`status`	string	OK
`total_results`	integer	Total number of records matching the query across all pages.
`next_page`	integer	The next page number. Absent when on the last page.
`results`	array	Array of call objects (see fields below).

Call Object Fields

Field	Type	Description
`start_date`	string	Call start datetime. Format: `DD/MM/YYYY HH:MM:SS`.
`caller`	string	Caller phone number. May be masked depending on domain privacy settings.
`tracking_number`	string	The tracking (surtax) number that was called.
`phone`	string	The destination phone number the call was forwarded to.
`trigger_type`	integer	How the call was triggered. See Appendix B.
`source`	string	Traffic source attribution (e.g. `Google Ads`, `Organic`).
`url`	string	Page URL where the tracking number was displayed.
`referer`	string	Referrer URL.
`keyword`	string	Search keyword that led to the visit, if available.
`call_path`	string	Newline-separated list of page URLs visited before the call.
`status`	string	Call outcome. See Appendix A.
`duration`	integer	Actual call duration in seconds.
`billing_duration`	integer	Billed call duration in seconds (may differ from actual duration).
`revenue`	float	Revenue or cost value attributed to this call.
`postcode`	string	Postcode entered by the caller via IVR, if applicable.
`keypad`	string	Keys pressed by the caller during the call, if applicable.
`is_redirect`	boolean	`true` if the call was redirected.
`expired_redirect`	boolean	`true` if the call was redirected due to an expired tracking number.
`answer_time`	integer	Time in seconds before the call was answered.
`visit_id`	string	ID of the website visit session associated with this call, if available.
`gclid`	string	Google Click ID (gclid) from the visit session associated with this call, if available.
`client_data`	string	Custom client data passed via the tracking script at the time of the visit, if available.

Example

bash

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"

json (response)

{
  "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 Daily Aggregated Calls (`group_by_day=true`)

When group_by_day=true, results are collapsed to one row per day. This mode is useful for building dashboards and trend charts without retrieving every individual call.

ℹ

Pagination parameters (page, limit) are still required but total_results and next_page are not present in the response. All days in the range are returned.

Aggregated Result Fields

Field	Type	Description
`date`	string	Date of the aggregated period. Format: `YYYY-MM-DD`.
`calls`	integer	Total number of calls on that day.
`duration`	float	Total call duration in seconds for that day.
`revenue`	float	Total revenue for that day.

Example

bash

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"

json (response)

{
  "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`)

Returns SMS records received on your tracking numbers within the requested date range. Pagination works the same as for calls.

SMS Object Fields

Field	Type	Description
`sent_date`	string	Date and time the SMS was received. Format: `YYYY-MM-DD HH:MM:SS`.
`caller_phone`	string	Sender phone number.
`tracking_phone`	string	Tracking number that received the SMS.
`id`	integer	Unique identifier for the SMS record.
`message_content`	string / array	Message body. Returns a plain string for standard SMS, or a JSON array for unicode/multi-part SMS.

Example

bash

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"

json (response)

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

#Appendix A: Call Status Values

The status field on a call record describes the outcome of the call. Use these values with the status filter parameter (comma-separated for multiple values).

Value	Description
`SUCCESS`	Call completed successfully.
`ANOMALY`	Call ended with an anomaly.
`BUSY`	Destination number was busy.
`NORESPONSE`	Destination did not respond.
`EXPIRED`	The tracking number had already expired when the call was made.
`INTERRUPTED`	Call was interrupted before connecting.
`ERR_SVI_STOP`	Call stopped during IVR postcode entry.
`NOTASSIGNED`	The original phone number was not assigned to any tracking number.
`ERR_CALLER_MSG`	Caller hung up while listening to a message.
`CALLER_PHONE_BLACKLISTED`	The caller's number is on the blocklist.

#Appendix B: Trigger Types

The trigger_type field indicates how a call was initiated.

Value	Description
`1`	Normal: standard inbound call on a tracking number.
`2`	Webcall: call initiated via the web widget (click-to-call).
`3`	Rule: call triggered by a routing rule.
`4`	Triggered: call triggered programmatically via the API.

Data API

#1 Introduction

Transport & Conventions

#2 Authentication

#3 Errors

#4 Endpoints

#5 GET /data-api

Required Parameters

Optional Parameters

Pagination

#6 Data types

#6.1 Calls (type=calls)

6.1.1 Individual Call Records

Flow

Success Response

Call Object Fields

Example

6.1.2 Daily Aggregated Calls (group_by_day=true)

Aggregated Result Fields

Example

#6.2 SMS (type=sms)

SMS Object Fields

Example

#Appendix A: Call Status Values

#Appendix B: Trigger Types

#6.1 Calls (`type=calls`)

6.1.2 Daily Aggregated Calls (`group_by_day=true`)

#6.2 SMS (`type=sms`)