Call Tracking API

Introduction #

The Optico Call Tracking API lets you replace the phone numbers on your site with tracking numbers for generating extra income and tracking purposes. You make calls to the API with your visitor information and phone numbers, and the API responds with the tracking numbers to display. Throughout this documentation the API is referred to as OSP.

How It Works

Your system transfers visit information to OSP with each page load: page URL, referer URL, IP address. OSP uses these to group calls into page views and visits, and monitor traffic sources, keywords and mobile traffic. A visit represents a user session and can contain one or more page views. Each page view can generate one or more calls.

OSP tracks how views convert to calls and exposes the stats in the client interface. For visitors coming from a search engine or Google Ads campaign, the originating keyword is recorded against the call, so you can see which keywords lead to the most profitable conversations.

Transport & Conventions

Getting Started #

1. Create an account on www.optico.fr: you will receive a username, password, API key, and access to the backend platform for management.
2. Integrate the API to get tracking numbers associated with your phones. Call /ospView on every page and use the tracking numbers returned.

Authentication #

Every request must include your api_key as a POST field.

api_key=osp_3a8f1c5d7b2e4906a8c1f5d3b9e7042c

The API key is issued when you register at www.optico.fr. Each registered domain has its own unique key.

Errors #

All error responses share the same structure regardless of endpoint:

{ "status": "AUTHENTICATION_ERROR", "errorMessage": "Invalid API key" }

Endpoints #

Concepts #

The visitId Cookie

Store the visitId returned by ospView in a cookie and send it on every subsequent request for the same session.

Display modes #

There are two strategies for showing tracking numbers to visitors. Both can coexist on the same website, but keep the same mode for a given page. The mode is controlled by the direct_display parameter of /ospView.

POST /ospView #

Direct Display

All phone numbers on the page are replaced with tracking numbers at page-load time. Set direct_display=true and pass the original phones in the phones parameter. OSP responds with a map of original phones to tracking numbers in surtaxPhones. This requires enough available tracking numbers to assign a unique one per visitor per phone number.

Flow

Click Display

With click display (direct_display=false), by default no phone number is shown on the page: instead a text such as "Click to show number" appears in place of each number. When a visitor clicks that link, an AJAX call is made to your server, which requests a tracking number from /ospClick and returns it to the browser for display.

You can use click display with or without tracking visit information. If you want only a tracking number for a phone without visit statistics, call /ospClick directly (omitting view_id). If you want full visit tracking, call /ospView first to record the page view and get a viewId, then pass that viewId to /ospClick.

Flow

Required Parameters

Direct Display: Additional Parameters

Optional Parameters

Success Response

Examples

Direct Display

curl -X POST https://www.optico.fr/ospView   -d "api_key=osp_3a8f1c5d7b2e4906a8c1f5d3b9e7042c"   -d "visit_id=0"   -d "ip=84.72.113.98"   -d "url=http://www.mysite.com/contact"   -d "page_title=Contact Us"   -d "is_mobile=false"   -d "referer_url=http://www.google.com/"   -d "nr_phones=2"   -d "direct_display=true"   -d "phones=0490260716,0450982756"   -d "user_agent=Mozilla/5.0 ..."
# → { "status": "OK", "visitId": 42, "surtaxPhones": { "0490260716": { "surtaxPhoneNumber": "01.02.03.04.05" } } }

Click Display

# Step 1: page load
curl -X POST https://www.optico.fr/ospView \
  -d "api_key=osp_..." \
  -d "direct_display=false" \
  -d "visit_id=0" \
  -d "ip=84.72.113.98" \
  -d "url=http://www.mysite.com/contact" \
  -d "page_title=Contact Us" \
  -d "is_mobile=false" \
  -d "referer_url=http://www.google.com/" \
  -d "nr_phones=1" \
  -d "user_agent=Mozilla/5.0 ..."
# → { "status": "OK", "visitId": 42, "viewId": 101 }

# Step 2: on click
curl -X POST https://www.optico.fr/ospClick \
  -d "api_key=osp_..." \
  -d "view_id=101" \
  -d "phone=0490260716"
# → { "status": "OK", "surtaxPhone": { "surtaxPhoneNumber": "01.02.03.04.05" } }

POST /ospClick #

Called server-side when a visitor clicks to reveal a tracking number. Returns a tracking number assigned on demand for the given phone. For the full two-step integration pattern, see Click Display.

Required Parameters

Optional Parameters

Success Response

POST /ospExpiration #

Use ospExpiration to extend or immediately release a tracking number that is currently assigned.

Required Parameters

Optional Parameters

Success Response

Example

# Extend by 10 minutes
curl -X POST https://www.optico.fr/ospExpiration \
  -d "api_key=osp_..." \
  -d "surtax_phone=08.90.12.34.56" \
  -d "expiration=600"
# → { "status": "OK", "surtaxPhone": "08.90.12.34.56", "expiresAt": "2026-03-13 14:30:00" }

# Release immediately
curl -X POST https://www.optico.fr/ospExpiration \
  -d "api_key=osp_..." \
  -d "surtax_phone=08.90.12.34.56" \
  -d "expiration=0"
# → { "status": "OK", "surtaxPhone": "08.90.12.34.56", "expiresAt": "2026-03-13 13:47:02" }

Appendix: Tracking Type Prefix Table #

The type parameter selects which phone number pool to draw from. Only needed when your domain is configured with multiple pools.