Offline Numbers API

Introduction #

The Optico Offline Numbers API manages static tracking phone numbers, permanently assigned to specific destination numbers for offline media such as print ads, billboards, business cards, and catalogues. Unlike online tracking numbers (assigned dynamically per web visitor), offline numbers are persistent and tied to a named campaign or destination.

Transport & Conventions

Authentication #

Every request must include the key parameter, the Offline Numbers API key for the domain. This key is available in your domain settings in the Optico backend.

/offline-numbers-api?key=offl_b7e2c8a14f9dcdef&action=check&tracking_number=0899123456

Errors #

Response envelope

Every request returns 200 OK with a JSON envelope. Branch on the status field; on error, the error field carries the reason.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456" }

{ "status": "error",
  "error": "No tracking number available" }

Common error messages

Idempotency

Read actions (check, /list) are safe to call repeatedly. Write actions (assign, unassign, reassign, redirect_setup) return the current state on success; re-issuing an unassign or redirect_setup after success is a no-op. assign allocates a new number from the pool each time it succeeds; do not retry blindly on timeout, call check first.

Retries & timeouts

Use a 5-second client timeout. Retry on network timeout or HTTP 5xx only for read actions. For assign, treat a timeout as "unknown" and call check with the destination phone_number to discover whether a number was allocated before retrying.

Rate limits

No fixed public rate limit is enforced. These endpoints are administrative; typical use is a handful of requests per day, not per second. Contact support before scripting bulk reassignments.

Endpoints #

GET /offline-numbers-api #

Common Parameters

Type and Prefix Reference

Success Response Fields

Action: assign #

Assign a tracking number from the domain's private pool to a destination phone number.

/offline-numbers-api?key=offl_key&action=assign&phone_number=0612345678&description=Magazine+Ad&type=1&allow_redirect=1

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456", "allow_redirect": "1" }

Action: unassign #

Release a tracking number back to the private pool. Provide either tracking_number or phone_number.

/offline-numbers-api?key=offl_key&action=unassign&tracking_number=0899123456

Action: reassign #

Change the destination phone number for an existing tracking number.

Action: check #

Query the current status of a tracking number or destination phone. Provide either tracking_number or phone_number.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456", "allow_redirect": "1" }

Action: redirect_setup #

Update the call forwarding redirect flag and/or the timetable for an existing tracking number.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456",
  "allow_redirect": "1", "timetable": [{ "day": "mon", "from": "09:00", "to": "18:00" }] }

GET /offline-numbers-api/list #

Returns all tracking numbers (both assigned offline numbers and unassigned pool numbers) associated with the domain.

Parameters

{
  "0899123456": "0612345678",
  "0899789012": "0698765432"
}

{
  "tracking_number_details": [{
    "tracking_phone": "0899123456",
    "destination_phone": "0612345678",
    "description": "Magazine Ad",
    "product_name": "example.com",
    "last_update": "2019-10-01 12:00:00"
  }]
}