Queries & Recordings

Services for fetching call data (CDR), downloading a single recording, getting call metadata, creating a manual call record and managing Google Ads offline conversions.

---

cdr_query

Fetch call data using a query that you build. The service accepts a read-only statement against the public data view that Maskyoo exposes to its customers, and returns the rows in JSON or XML.

Endpoint: /api/?service=cdr_query

Prerequisite

This function requires basic knowledge of SQL.

Parameters

Parameter	Type	Required	Description
sql	string	YES	A valid read-only statement (see rules below). Max 8192 bytes.
format	string	NO	json / xml.

Query rules

• The statement must start with SELECT and must select FROM webserviceview — the public view of the account. Direct access to the underlying tables is rejected.
• One statement per request only: no statement stacking (;), no subqueries and no UNION (exactly one SELECT keyword is allowed).
• Write operations, schema operations and system queries are not allowed (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, RENAME, GRANT, REVOKE, LOAD_FILE, INTO OUTFILE, information_schema, and similar).
• SQL comments (--, #, /* */), system variables (@@), the assignment operator (:=) and timing functions (SLEEP(), BENCHMARK(), GET_LOCK()) are not allowed.
• The statement is limited to 8192 bytes.
• If the statement is rejected, the reason is returned in the description field.

Fields you can select

The webserviceview view exposes the following columns:

Field	Type	Description
id	int	Internal row ID of the call record
start_call	datetime	Call start time
end_call	datetime	Call end time
call_duration	int	Call duration in seconds
cdr_ani	varchar	Caller number (ANI)
cdr_ddi	varchar	The Maskyoo number that was dialed
user_phone	varchar	The destination number that received the call
user_name	varchar	The description of the Maskyoo number (business name)
call_status	varchar	Call status: ANSWER, NOANSWER, BUSY, CALLER CANCEL, NOT ACTIVE, Black List, OUT OF TIME
onetouch	varchar	Call rating (as given by the answering agent)
cdr_uniqueid	varchar	Unique call ID — use it with get_record_by_call_uuid and get_cdr_metadata_by_call_uuid
cdr_meta_data	text	Marketing metadata collected for the call (pixel data), when available
gclid	varchar	Google Click Identifier of the call, when available

In addition, the field name record_file_exists may be selected as an alias (for example 1 AS record_file_exists). When it is part of the selected fields, Maskyoo checks for every returned row whether a recording file actually exists for that call and empties the value when it does not.

Error codes

Code	Description
1011	sql is missing
1012	The statement was rejected (the reason is in description)
1013	No results / invalid statement

Examples

Fetch the answered calls of a given day, newest first:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/" \
     --data-urlencode "service=cdr_query" \
     --data-urlencode "sql=SELECT start_call, end_call, call_duration, cdr_ani, cdr_ddi, user_phone, user_name, call_status, cdr_uniqueid FROM webserviceview WHERE start_call BETWEEN '2026-08-01 00:00:00' AND '2026-08-01 23:59:59' AND call_status = 'ANSWER' ORDER BY start_call DESC LIMIT 100" \
     -d "format=json"

Fetch calls of a single Maskyoo number, including whether a recording exists:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/" \
     --data-urlencode "service=cdr_query" \
     --data-urlencode "sql=SELECT start_call, cdr_ani, call_status, call_duration, cdr_uniqueid, 1 AS record_file_exists FROM webserviceview WHERE cdr_ddi = '972776670000' ORDER BY start_call DESC LIMIT 50" \
     -d "format=json"

Response example

{
  "service": "cdr_query",
  "status": { "code": 200, "description": "ok" },
  "result": [
    {
      "start_call": "2026-08-01 09:14:22",
      "end_call": "2026-08-01 09:16:05",
      "call_duration": 103,
      "cdr_ani": "972527905005",
      "cdr_ddi": "972776670000",
      "user_phone": "972521231231",
      "user_name": "Business Website",
      "call_status": "ANSWER",
      "cdr_uniqueid": "1756712062.15423"
    }
  ]
}

note

A heavy statement may run for up to 10 minutes. Always filter by a time range and add LIMIT to keep the response fast.

---

cdr_subunique_query

An aggregated report of the calls that were answered within a given time range, including the number of calls per unique caller. Returns up to 2000 rows.

Endpoint: /api/?service=cdr_subunique_query

Parameters

Parameter	Type	Required	Description
start_time	string	YES	Y-m-d H:i:s.
end_time	string	YES	Y-m-d H:i:s.
format	string	NO	json / xml.

Error codes

Code	Description
1001	start_time is missing / invalid
1002	end_time is missing / invalid
1003	No results

---

get_record_by_call_uuid

Download the recording file of a single call.

Endpoint: /api/?service=get_record_by_call_uuid

Parameters

Parameter	Type	Required	Description
call_uuid	string	YES	The unique call ID.
type	string	NO	wav (default) / mp3.
format	string	NO	json / xml (relevant to error responses only).

The system converts the recording to the requested format on the fly. A successful request returns the audio file only; a status response in JSON/XML is returned on error.

Error codes

Code	Description
3001	call_uuid is missing
3002	The recording does not exist

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -o call.mp3 \
     "https://[MASKYOO_URL]/api/?service=get_record_by_call_uuid&call_uuid=XXXXXXX&type=mp3"

---

get_cdr_metadata_by_call_uuid

Return extended information about a single call, including pixel data, Google Ads data and transcription (when available).

Endpoint: /api/?service=get_cdr_metadata_by_call_uuid

Parameters

Parameter	Type	Required	Description
call_uuid	string	YES	The unique call ID.
format	string	NO	json / xml.

Response structure

The response contains the following sections (subject to data availability):

• cdr – the call data.
• pixel_data – pixel data collected for the call.
• adwords_data – the Google Ads data related to the call.
• adwords_call_extension_data – Google Ads Call Extension data.
• speech_recognition – call transcription (if transcription is enabled for the account).

Error codes

Code	Description
1014	call_uuid is missing
1015	No results

---

get_google_ads_offline_conversion

Read the offline conversion value stored on a call, together with the last update time.

Endpoint: /api/?service=get_google_ads_offline_conversion

Parameters

Parameter	Type	Required	Description
call_uuid	string	YES	The unique call ID.
format	string	NO	json / xml.

Error codes

Code	Description
1015	call_uuid is missing
1116	call_uuid has an invalid format (must be numeric)
1115	No results for this call

---

set_google_ads_offline_conversion

Store or update the offline conversion value of a call. The value is sent to Google Ads on the next synchronization cycle.

Endpoint: /api/?service=set_google_ads_offline_conversion

Parameters

Parameter	Type	Required	Description
call_uuid	string	YES	The unique call ID.
conversion_value	number	YES	The conversion value (must be numeric).
format	string	NO	json / xml.

Error codes

Code	Description
1015	call_uuid is missing
1016	conversion_value is missing
1017	conversion_value is not numeric
1125	No call was found for the given ID
1126	Saving failed

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/?service=set_google_ads_offline_conversion" \
     -d "call_uuid=XXXXXXX" \
     -d "conversion_value=150.00" \
     -d "format=json"

---

create_maskyoo_cdr

Create a manual call record — suitable for integrations with external IVR systems or for importing calls from another source. After the record is added, the system automatically runs the end-of-call automation rules and the pixel mechanisms.

Endpoint: /api/?service=create_maskyoo_cdr

Parameters

Parameter	Type	Required	Description
cdr_ddi	string	YES	The Maskyoo number (must exist in the account).
cdr_start_call	string	NO	Y-m-d H:i:s (default: the time of the API call).
cdr_totac_sec	int	NO	Call duration in seconds. When sent it must be in the range 1–3599; when omitted the default is 0. The end time is calculated automatically.
cdr_ani	string	NO	Caller number (must be a valid Israeli number).
cdr_destination	string	NO	Destination number (same validation).
cdr_metadata	string	NO	A valid JSON string that is stored as the call metadata.
format	string	NO	json / xml.

Response

On success the cdr_uniqueid is returned — a unique ID that is generated automatically for the call.

Error codes

Code	Description
2022	cdr_start_call is not in Y-m-d H:i:s format
2024	cdr_totac_sec is not numeric / out of range
2027	cdr_ani is invalid
2028	cdr_destination is invalid / cdr_ddi is missing or unknown
2029	cdr_metadata is not valid JSON
2031	Saving the call failed

System impact

The query and recording services touch the CDR and the Google Ads integration directly:

• CDR queries — cdr_query runs SELECT only against the public view; it may run for up to 10 minutes, so filters and LIMIT are recommended for performance
• Recordings — get_record_by_call_uuid downloads the recording file directly (WAV/MP3); fetching archived files may take a while
• Manual CDR — create_maskyoo_cdr immediately runs the end-of-call automation rules and the pixel mechanisms, as if the call had gone through the telephony platform
• Google Ads offline conversion — set_google_ads_offline_conversion stores a value that is sent to Google on the next synchronization cycle; it affects campaign ROI reporting
• Metadata — get_cdr_metadata_by_call_uuid returns the same pixel and Google Ads data that is visible in the call detail report

See also

• Call Detail Report
• Automation Events
• Google Campaign Calls Report
• Maskyoo Management