Getting Started

FREESTYLE API Reference

The FREESTYLE API gives you programmatic access to your FREESTYLE Telecom Technologies account — campaigns, agents, activity, and more. All API access is over HTTPS and all responses are JSON.

This reference covers every endpoint, parameter, and response schema. Contact your account manager with questions.

Early Access — The API is in early access. Endpoints may change before general availability. Breaking changes will be communicated in advance.

Base URL

All endpoints are relative to:

https://api.freestyleteletech.com/v1

All requests must be made over HTTPS. Plain HTTP is not supported.

Authentication

API Keys

The FREESTYLE API authenticates requests using API keys. Your key is unique to your client account and carries full access to your data — never expose it in client-side code or version control.

Obtaining an API Key

API keys are provisioned by a FREESTYLE administrator from your client profile. Once generated, the full key is shown exactly once — store it immediately in a secure location such as an environment variable or secrets manager.

Treat your API key like a password. If you believe it has been compromised, contact your account manager to have it regenerated. The previous key is invalidated immediately upon regeneration.

Making Requests

Pass your API key in the X-API-Key header on every request:

🔑 X-API-Key: ft_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Required headers

Header	Required	Description
X-API-Key	Required	Your 64-character hex API key.
Content-Type	Conditional	Required for POST / PATCH requests. Value: `application/json`
Accept	Optional	Recommended: `application/json`

Errors

The API uses standard HTTP status codes. All error responses include a JSON body with a machine-readable code and a human-readable message.

Error response format

{
  "error": {
    "code":    "unauthorized",
    "message": "Invalid or missing API key."
  }
}

HTTP status codes

200OK — Request succeeded.

400Bad Request — Invalid parameters. See the error message for details.

401Unauthorized — API key is missing or invalid.

403Forbidden — API key does not have permission for this resource.

404Not Found — The requested resource does not exist.

500Server Error — Something went wrong on our side. Try again or contact support.

Error codes

Code	Description
unauthorized	API key is missing, malformed, or invalid.
api_disabled	API access is disabled for this client account.
not_found	The requested resource was not found.
invalid_parameter	One or more parameters failed validation.
server_error	An unexpected server-side error occurred.

Dial Campaigns

List Campaigns

Returns a paginated list of dial campaigns associated with your client account.

GET https://api.freestyleteletech.com/v1/dial-campaigns

Shared access — If another client has shared this endpoint with your account, the response includes their campaigns alongside your own. Each campaign object is identified by its own id regardless of which client owns it.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Results per page. Default `25`, max `100`.
status	string	Optional	Filter by status: `active`, `paused`, `completed`, `draft`.

Response

Returns an object with a data array of campaign objects and a meta pagination object.

{
  "data": [
    {
      "id":           "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name":         "Q2 Outreach — Ontario",
      "status":       "active",
      "created_at":   "2026-03-15T14:22:00Z",
      "updated_at":   "2026-05-01T09:10:00Z",
      "total_leads":  4820,
      "dialed":       3104,
      "remaining":    1716
    }
  ],
  "meta": {
    "page":        1,
    "per_page":    25,
    "total":       8,
    "total_pages": 1
  }
}

Campaign object fields

Field	Type	Description
id	string	Unique campaign identifier.
name	string	Campaign display name.
status	string	One of `active`, `paused`, `completed`, `draft`.
created_at	string	ISO 8601 creation timestamp (UTC).
updated_at	string	ISO 8601 last-modified timestamp (UTC).
total_leads	integer	Total leads in the campaign.
dialed	integer	Leads dialed at least once.
remaining	integer	Leads not yet dialed.

Response Codes

200Campaign list returned successfully.

401Invalid or missing API key.

403API access is disabled for this account.

Dial Campaigns

Update Campaign Status

Start or pause a dial campaign. Only active and paused are settable — completed and draft are computed states derived from lead progress.

PATCH https://api.freestyleteletech.com/v1/dial-campaigns/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Request Body

Send Content-Type: application/json.

Field	Type	Required	Description
status	string	Required	Target status. One of `active`, `paused`.

Response

Returns the updated campaign object under a data key.

Response Codes

200Campaign updated successfully.

400Invalid or missing status value.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Dial Campaigns

Upload Campaign Data

Upload a batch of contact records to a dial campaign. Records are appended to the campaign's existing dataset and the campaign's total lead count is updated automatically. Up to 1,000 records per request.

POST https://api.freestyleteletech.com/v1/dial-campaigns/{id}/data

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Request Body

Send Content-Type: application/json with a top-level records array. Each element is a contact object.

Contact Object Fields

Field	Type	Required	Description
phone1	string	Required	Primary phone number. Digits only, 10-digit North American format. A leading country code `1` is stripped automatically.
phone2 – phone10	string	Optional	Additional phone numbers, same format as `phone1`.
account_id	string	Optional	Primary account identifier (up to 100 chars).
account_name	string	Optional	Contact display name (up to 50 chars).
email	string	Optional	Email address.
street	string	Optional	Street address.
city	string	Optional	City.
province_state	string	Optional	Province or state.
postal_zip	string	Optional	Postal or ZIP code.
dob	string	Optional	Date of birth.
amount	number	Optional	Primary balance or amount.
amount_secondary	number	Optional	Secondary balance or amount.
account_id_secondary	string	Optional	Secondary account identifier.
datetime	string	Optional	Primary date/time (ISO 8601 or Unix timestamp).
datetime_secondary	string	Optional	Secondary date/time.
language	string	Optional	Preferred language code: `en`, `fr`, etc.
external_name	string	Optional	External reference name.
data1 – data6	string	Optional	Custom data fields (up to 120 chars each).
timezone_id	integer	Optional	Timezone ID for scheduling.
client_name	string	Optional	Client label for this record.

Response

Returns a summary of the operation — how many records were inserted, how many were skipped due to validation errors, and the campaign's updated total lead count.

Response Codes

200Records uploaded successfully.

400Missing or invalid fields; exceeds 1,000 record limit.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Dial Campaigns

Get Call Results

Returns a paginated list of individual call result records for a campaign. Each record represents one call attempt, including the disposition, agent, timing, and lead details.

GET https://api.freestyleteletech.com/v1/dial-campaigns/{id}/results

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Query Parameters

Parameter	Type	Required	Description
from	string	Optional	Start date filter (YYYY-MM-DD). Filters by call completion time.
to	string	Optional	End date filter (YYYY-MM-DD). Inclusive.
disposition	integer	Optional	Filter by disposition type ID.
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Records per page, max `200`. Defaults to `50`.

Response

Returns a data array of result objects and a meta object for pagination. Results are ordered by call completion time descending.

Result Object Fields

Field	Type	Description
result_id	integer	Unique identifier for this call result.
campaign_data_id	integer	ID of the lead record that was called.
account_id	string	Lead's account identifier.
account_name	string	Lead's name.
phone_dialed	string	The phone number that was dialed for this attempt.
phone_number_index	integer	Phone slot index (0 = phone1, 1 = phone2, …).
disposition	object	Disposition details: `id`, `name`, `code`, `contacted` (bool).
agent_id	integer	ID of the agent who handled the call.
dialed_at	string	RFC 3339 timestamp when the call was dialed.
connected_at	string	RFC 3339 timestamp when the call connected (null if no answer).
completed_at	string	RFC 3339 timestamp when the call was dispositioned.
talk_seconds	integer	Seconds from connection to completion. Null if not connected.
total_seconds	integer	Seconds from dial to completion.
amount	number	Amount collected or recorded during the call, if applicable.
dtmf	string	DTMF keypad input captured during the call.
recording_id	string	Call recording reference ID, if recorded.
new_phone	string	Updated phone number captured during the call.
new_email	string	Updated email address captured during the call.

Response Codes

200Results returned successfully.

400Invalid query parameter.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Dial Campaigns

Results Summary

Returns aggregate call statistics for a campaign, broken down by disposition type. Useful for dashboards and reporting — includes total calls, contact rate, and talk time.

GET https://api.freestyleteletech.com/v1/dial-campaigns/{id}/results/summary

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Query Parameters

Parameter	Type	Required	Description
from	string	Optional	Start date filter (YYYY-MM-DD).
to	string	Optional	End date filter (YYYY-MM-DD). Inclusive.

Response

Returns a single data object with top-level totals and a dispositions array ranked by call count.

Response Fields

Field	Type	Description
total_calls	integer	Total number of call attempts.
total_contacts	integer	Calls where a live contact was reached.
contact_rate	number	Contact rate as a percentage (0–100).
total_talk_seconds	integer	Sum of connected talk time across all calls.
total_dial_seconds	integer	Sum of total call duration (dial to completion) across all calls.
first_call_at	string	RFC 3339 timestamp of the earliest call in the result set.
last_call_at	string	RFC 3339 timestamp of the most recent call in the result set.
date_range	object	The `from` and `to` filters applied (null if not provided).
dispositions	array	Breakdown by disposition: `id`, `name`, `code`, `contacted`, `count`, `percentage`.

Response Codes

200Summary returned successfully.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Dial Campaigns

Activity Log

Returns a paginated log of campaign-level activity events: records imported, records recycled, and campaign started/stopped events. Corresponds to the Campaign Report in the admin portal.

GET https://api.freestyleteletech.com/v1/dial-campaigns/{id}/activity

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Query Parameters

Parameter	Type	Required	Description
from	string	Optional	Start date filter (YYYY-MM-DD).
to	string	Optional	End date filter (YYYY-MM-DD). Inclusive.
type	integer	Optional	Filter by activity type ID (see table below).
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Records per page, max `200`. Defaults to `50`.

Activity Types

ID	Name	Count Fields Included
1	Records Imported	`imported_count`, `recycled_count` (duplicates), `excluded_count`, `total_count`
2	Campaign Stopped	All counts are `null`
3	Campaign Started	All counts are `null`
4	Records Recycled	`recycled_count` (reset back to unworked), `total_count` (total evaluated); other counts are `null`

Response

Returns a data array of activity event objects and a meta object for pagination. Events are ordered by timestamp descending.

Activity Object Fields

Field	Type	Description
activity_id	integer	Unique identifier for this activity event.
type	object	Activity type: `id` and `name`.
imported_count	integer	Number of new records added. Null for non-import events.
recycled_count	integer	Duplicate records skipped on import, or records reset to unworked on a recycle run.
excluded_count	integer	Records excluded during import (invalid or suppressed). Null for non-import events.
total_count	integer	Total records processed in this event (imported + recycled + excluded for imports; total evaluated for recycle runs).
created_at	string	RFC 3339 timestamp when the event occurred.

Response Codes

200Activity log returned successfully.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Dial Campaigns

Get Contact by Phone

Looks up a single active contact record within a campaign by phone number. Searches all ten phone number slots (Phone1–Phone10), matching on the last 10 digits, and returns the record where the earliest phone slot matches. Returns 404 if no active record is found for that number.

GET https://api.freestyleteletech.com/v1/dial-campaigns/{id}/contact

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The campaign ID (e.g. `a1b2c3d4-...`).

Query Parameters

Parameter	Type	Required	Description
phone	string	Required	The phone number to search for. Non-numeric characters are stripped and the last 10 digits are used for matching.

Response

Returns a single data object containing the matched contact record fields.

Contact Object Fields

Field	Type	Description
campaign_id	string	The ID of the campaign this record belongs to.
campaign_name	string	The name of the campaign. May be `null`.
account_name	string	The account name on the contact record. May be `null`.
amount	number	The monetary amount associated with this record. May be `null`.
datetime	string	The scheduled date/time associated with this record. May be `null`.

Response Codes

200Contact record returned successfully.

400Missing or invalid phone parameter — must contain at least 10 digits.

401Invalid or missing API key.

403Your API key does not have access to this endpoint.

404Campaign not found, or no active contact matches that phone number in this campaign.

SMS Campaigns

List SMS Campaigns

Returns a paginated list of SMS campaigns on your account, including run counts and latest scheduled run timestamp.

GET https://api.freestyleteletech.com/v1/sms-campaigns

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter to campaigns that have at least one run in this status: `scheduled`, `running`, `completed`, `cancelled`.
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Records per page, max `100`. Defaults to `50`.

Response

Returns a data array of campaign objects and a meta object for pagination. Campaigns are ordered alphabetically by name.

Campaign Object Fields

Field	Type	Description
id	string	Unique campaign identifier (e.g. `sc_uuid...`).
name	string	Campaign display name.
from_number	string	Twilio sender phone number in E.164 format.
total_runs	integer	Total number of runs ever scheduled for this campaign.
running_count	integer	Runs currently in progress.
scheduled_count	integer	Runs scheduled and not yet started.
completed_count	integer	Runs that completed successfully.
cancelled_count	integer	Runs that were cancelled.
last_run_at	string	RFC 3339 timestamp of the most recently scheduled run. Null if no runs.
created_at	string	RFC 3339 timestamp when the campaign was created.
updated_at	string	RFC 3339 timestamp when the campaign template was last updated. Null if never updated.

Response Codes

200List returned successfully.

400Invalid query parameter.

401Invalid or missing API key.

SMS Campaigns

Get SMS Campaign

Returns a single SMS campaign by ID, including its message template and full run summary counts.

GET https://api.freestyleteletech.com/v1/sms-campaigns/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The SMS campaign ID (e.g. `sc_uuid...`).

Additional Response Fields

Returns all fields from the list response, plus:

Field	Type	Description
template	string	The SMS message template text. Supports placeholders: `{Name}`, `{Balance}`, `{DueDate}`, `{CompanyCode}`, `{Account}`.

Response Codes

200Campaign returned successfully.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

SMS Campaigns

Get Campaign Runs

Returns a paginated list of runs (scheduled send batches) for a given SMS campaign, ordered by scheduled time descending. Each run represents one CSV upload and its delivery progress.

GET https://api.freestyleteletech.com/v1/sms-campaigns/{id}/runs

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The SMS campaign ID (e.g. `sc_uuid...`).

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter by run status: `scheduled`, `running`, `completed`, `cancelled`.
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Records per page, max `100`. Defaults to `50`.

Run Statuses

Status	Meaning
scheduled	Queued and waiting for the scheduled send time.
running	Currently sending messages.
completed	All messages have been processed.
cancelled	Run was cancelled before completion.

Run Object Fields

Field	Type	Description
run_id	integer	Unique identifier for this run.
status	string	Current run status (see table above).
scheduled_at	string	RFC 3339 timestamp when the run was scheduled to begin.
started_at	string	RFC 3339 timestamp when sending started. Null if not yet started.
completed_at	string	RFC 3339 timestamp when the run completed. Null if still in progress.
total	integer	Total number of phone numbers in this run.
processed	integer	Number of numbers processed so far.
sent	integer	Messages delivered successfully.
failed	integer	Messages that failed to deliver.
progress_pct	number	Percentage of messages processed (0–100).
notes	string	Internal notes on this run. Null if none.
created_at	string	RFC 3339 timestamp when the run was created.

Response Codes

200Runs returned successfully.

400Invalid query parameter.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

SMS Campaigns

Get Campaign Messages

Returns a paginated log of individual SMS messages sent or received for a campaign, linked through campaign runs. Includes delivery status, error details, cost per message, and the reference ID from the original upload CSV. Corresponds to the SMS Report in the admin portal.

GET https://api.freestyleteletech.com/v1/sms-campaigns/{id}/messages

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The SMS campaign ID (e.g. `sc_uuid...`).

Query Parameters

Parameter	Type	Required	Description
from	string	Optional	Start date filter (YYYY-MM-DD). Filters by message send time.
to	string	Optional	End date filter (YYYY-MM-DD). Inclusive.
run_id	integer	Optional	Filter to messages from a specific campaign run.
status	string	Optional	Filter by Twilio delivery status (e.g. `delivered`, `failed`, `undelivered`, `sent`).
direction	string	Optional	Filter by message direction: `sent` or `received`.
page	integer	Optional	Page number. Defaults to `1`.
per_page	integer	Optional	Records per page, max `200`. Defaults to `50`.

Response

Returns a data array of message objects, a summary object with totals, and a meta object for pagination. Messages are ordered by send time descending.

Message Object Fields

Field	Type	Description
message_id	integer	Unique message identifier.
run_id	integer	The campaign run this message belongs to.
direction	string	`sent` or `received`.
phone_number	string	The other party's phone number.
from_number	string	Sender's number (Twilio E.164 format).
to_number	string	Recipient's number (Twilio E.164 format).
message	string	Full SMS message body.
status	string	Twilio delivery status: `queued`, `sent`, `delivered`, `failed`, `undelivered`.
error_code	string	Twilio error code if delivery failed. Null on success.
error_message	string	Human-readable error description. Null on success.
segments	integer	Number of SMS segments used (160 chars per segment).
cost	number	Billed cost for this message.
reference_id	string	Reference or account ID from the original upload CSV. Null if not provided.
sent_at	string	RFC 3339 timestamp when the message was sent.

Summary Object Fields

Field	Type	Description
total	integer	Total messages matching the current filters.
sent_count	integer	Outbound messages.
received_count	integer	Inbound replies.
total_cost	number	Sum of billed cost across all matching messages.

Response Codes

200Messages returned successfully.

400Invalid query parameter.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Billing

Usage & Cost

Returns per-campaign call duration and billing cost for a given date range. Duration is summed from all conference calls on the campaign; cost is calculated from your account's gross hourly rate (GHR). Corresponds to the Cost Report in the admin portal.

GET https://api.freestyleteletech.com/v1/billing

Query Parameters

Parameter	Type	Required	Description
from	string	Optional	Start date filter (YYYY-MM-DD). Filters by conference start time.
to	string	Optional	End date filter (YYYY-MM-DD). Inclusive.
campaign	string	Optional	Filter to a specific campaign (e.g. `a1b2c3d4-...`). Defaults to all campaigns on your account.

Response

Returns a data array with one entry per campaign, and a summary object with account-level totals. Results are ordered by duration descending.

Campaign Object Fields

Field	Type	Description
campaign_id	string	Campaign identifier (e.g. `a1b2c3d4-...`).
campaign_name	string	Campaign display name.
duration_seconds	integer	Total conference call duration in seconds for the date range.
hourly_rate	number	Your account's gross hourly rate (GHR) applied to this campaign.
cost	number	Calculated cost: `(duration_seconds / 3600) × hourly_rate`.

Summary Object Fields

Field	Type	Description
total_duration_seconds	integer	Sum of duration across all campaigns in the response.
total_cost	number	Sum of cost across all campaigns in the response.
date_range	object	The `from` and `to` filters applied (null if not provided).

Response Codes

200Usage data returned successfully.

401Invalid or missing API key.

404Campaign not found or does not belong to your account.

Account

Get Account

Returns the account profile associated with your API key, including contact information and location.

GET https://api.freestyleteletech.com/v1/account

Response

Returns a single data object representing the authenticated client's account.

Account Object Fields

Field	Type	Description
id	string	Unique client identifier (UUID).
name	string	Account display name.
status	string	Account status. One of: `prospect`, `onboarded`, `declined`, `qualified_lead`, `commitment`.
description	string	Optional account description. Null if not set.
contacts	object	Contact details grouped by role: `primary`, `technical`, `billing`. Each has `name`, `email`, and `phone`.
location	object	Account location with `country` and `province_state`. Null if not set.
created_at	string	ISO 8601 timestamp when the account was created.

Response Codes

200Account data returned successfully.

401Invalid or missing API key.

403API access is disabled for this account.

Account

Phone Numbers

Returns all phone numbers assigned to your account, including type and Neustar Branded Call Display status.

GET https://api.freestyleteletech.com/v1/account/phone-numbers

Response

Returns a data array with one entry per phone number and a meta object with the total count.

Phone Number Object Fields

Field	Type	Description
phone_number_id	integer	Unique phone number record ID.
phone_number	string	The phone number in E.164 format.
type	object	Phone number type with `id` (integer) and `name` (string).
description	string	Optional label or description. Null if not set.
neustar_branded_call_display	boolean	Whether this number is enrolled in Neustar Branded Call Display.
created_at	string	ISO 8601 timestamp when this number was added to the account.

Response Codes

200Phone numbers returned successfully.

401Invalid or missing API key.

403API access is disabled for this account.