Press8 Phone System API

Press8 phone service includes a JSON API. If you are building your own software (a case-management system, a CRM, a reporting dashboard), you can use the API to pull your call history, caller details, missed calls and voicemails, see calls that are in progress, and receive call events as they happen.

This page is a curated guide to the parts of the API that are most useful to customers. It covers read-only functions only.

Getting started

Get an API login

API calls are made with a user login on your Press8 account. Ask the administrator on your Press8 account to create a dedicated API user in the phone system portal and give it the permissions your integration needs (each function below lists the permission it requires). Please do not share a staff member’s personal login with your software.

What your login can see

Your API user’s credentials determine what you can reach. Every request is answered only with your own account’s data: your calls, voicemail, users, phones and numbers.

Your credentials also determine which functions you can call. Each function below lists the permission it needs. If your login does not have that permission, the API returns code 402 (“Your role does not allow this”). If the item you ask for does not exist on your account, it returns code 404. If you need a function your login cannot use, contact the administrator on your Press8 account to add that permission to your API user.

Base URL

All requests go to:

https://manage.press8.com/api/json/<category>/<action>/

Some functions have a longer path, such as calls/missed/list/. Always use HTTPS.

Making a request

The API is not strictly a REST API, but it works in a similar way. You can use HTTP GET (parameters in the URL) or HTTP POST (parameters sent as a form). GET parameters may be separated by & or ;.

We recommend POST, so that your password or token is not written into URLs, browser history or proxy logs. The GET examples on this page are for readability only.

Authentication

There are two ways to authenticate:

1. Username and password on every request. Send auth_username and auth_password with each call.
2. Token. Call user/login once with token=1. The response includes an auth_token value. Send that as the auth_token parameter on later calls instead of the username and password. Tokens are short-lived: the login response also includes auth_token_expires (a Unix timestamp). When the token expires, log in again to get a new one.

Keep API credentials on your server. Never put them in a web page or mobile app that your users can inspect.

Responses

Every response is a JSON document with a responses array. Each entry has a code, a key and a message. If there is data to return, it is in a data element: an array of records for list functions, or a single record for get functions.

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":{ "id":123, "name":"example", ... } }

On an error there may be several responses (for example, one per invalid parameter) and usually no data. The key is a stable identifier you can match on in your code; the message is English text.

Two things to design for:

• The order of fields and the formatting of the JSON are not guaranteed.
• New fields and new optional parameters can be added at any time. Your code should ignore fields it does not recognise.

Response codes

Code	Meaning
200	Success, and data is being returned.
204	Success, and no data is being returned.
400	Invalid input parameters. Check the key and message fields for details.
401	The authentication details provided are invalid.
402	Your role does not allow this.
403	Your rate plan does not allow this.
404	The object does not exist, or you do not have permission to view it.
500	An error occurred within the server. Check the key and message fields for details.

Note that the code is inside the JSON responses array. Check it there rather than relying on the HTTP status of the request.

Times

Dates and times are Unix timestamps (seconds since 1 January 1970 UTC). Where a function takes start and end, it returns records at or after start and before end.

Which function do I need?

You want	Use
Call history (inbound, outbound, internal)	cdrs/list, cdrs/get
Missed calls	calls/missed/list
Voicemails and faxes	mailboxes/list, messages/list, messages/get
Calls in progress right now	calls/active/list
Calls as they happen, pushed to you	Call events (see below)
Your users, extensions and phone numbers	people/list, phones/list, numbers/list

Reference

Every function below also takes the authentication parameters described above (auth_username and auth_password, or auth_token). They are not repeated in each table. Some rarely used or administrative parameters are left out.

user/login

Gets the login data for the authenticated user. Use it to check a login works, and with token=1 to get an authentication token.

Requires the user role privilege.

Parameter	Type	Description	Default
token	Integer	1 to get an authentication token, 0 not to.	0

Example

https://manage.press8.com/api/json/user/login/?auth_username=USER&auth_password=PASSWORD&token=1

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":{ "id":123, "username":"user", ... } }

The data is the fields of your user. With token=1 it also includes auth_token and auth_token_expires.

cdrs/list: call history

Gets the records of completed calls (CDRs) for your account.

Requires the cdrs or callshop role privilege.

Always send start and end. Leaving them out asks for every call ever made on the account, which is slow and puts a heavy load on the system. For regular syncing, ask for a small window (for example, the last hour or the last day) and page through with limit and offset.

Parameter	Type	Description	Default
start	Integer	Start Unix timestamp. Recommended.	0
end	Integer	End Unix timestamp. Recommended.	Now
detail	String	“call” to return a list of calls, “leg” to return a list of call legs.	“leg”
direction	String	“in” (inbound only), “out” (outbound only), “internal” (internal only), “in_out” (inbound or outbound). Empty for all calls.	Empty
callid	String	Call ID. Empty for any.	Empty
phone	String	Source telephone line. Empty for any.	Empty
snumber, smatch	String	Source (calling) number, and how to match it.	Empty, “contains”
cnumber, cmatch	String	Called number, and how to match it.	Empty, “contains”
dnumber, dmatch	String	Destination number, and how to match it.	Empty, “contains”
stype, ctype, dtype	String	Source, called and destination type. Empty for any.	Empty
callername_number, callername_match	String	Caller name, and how to match it.	Empty, “contains”
status	String	Call status. Empty for any.	Empty
talktime_minimum	Integer	Minimum talk time in seconds.	0
talktime_maximum	Integer	Maximum talk time in seconds. -1 for no limit.	-1
archive	Integer	1 to include archived calls, 0 not to.	0
limit	Integer	Maximum results to return. 0 for all.	0
offset	Integer	The result to start at. 0 for the first.	0
sort	String	Field to sort by: “callid”, “cnumber”, “cost”, “ctype”, “dcustomer”, “direction”, “dnumber”, “dtype”, “end”, “name”, “peer”, “scustomer”, “snumber”, “start”, “status”, “stype”, “talktime”, “totaltime” or “uniqueid”.	“start”
descending	Integer	1 to sort descending, 0 not to.	0

The match parameters accept “contains”, “start”, “end” or “exact”.

Example

https://manage.press8.com/api/json/cdrs/list/?auth_token=TOKEN&start=1759000000&end=1759086400&direction=in

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "uniqueid":"1234567890.123456", "start":1234567890, ... },
    { "uniqueid":"1234567890.123457", "start":1234567890, ... }
  ] }

By default there is one row per call leg; a single phone call that rings several phones or is transferred can have several legs. Each leg has its own uniqueid. All legs of one call share the same callid. Use detail=call if you want one row per call.

Fields returned: A complete field list is not published for this function. The example shows uniqueid and start, and the sort values above are field names. The easiest way to see everything is to run a small query against your own account and inspect the result.

cdrs/get: one call

Gets the fields of one completed call.

Requires the cdrs or callshop role privilege.

Parameter	Type	Description	Default
uniqueid	String	Required. Unique ID of the call to get.

Example

https://manage.press8.com/api/json/cdrs/get/?auth_token=TOKEN&uniqueid=1234567890.123456

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":{ "uniqueid":"1234567890.123456", "start":1234567890, ... } }

Returns 404 if the call does not exist or you do not have permission to view it.

calls/missed/list: missed calls

Lists missed calls.

Requires the user, residential or wholesale role privilege.

Parameter	Type	Description	Default
start	Integer	Start Unix timestamp. Recommended.	0
end	Integer	End Unix timestamp. Recommended.	Now
dtype	String	Destination type. Recommended. Empty for any.	Empty
dnumber	String	Destination number. Recommended. Empty for any.	Empty
cnumber	String	The caller ID to match.	Empty
cmatch	String	How to match the caller ID: “exact”, “contains”, “start” or “end”.	“contains”
sort	String	“callerid” or “time”.	“time”
descending	Integer	1 to sort descending, 0 not to.	0

Leaving out start, end, dtype and dnumber can make the request slow.

Example (missed calls to telephone line 1234567)

https://manage.press8.com/api/json/calls/missed/list/?auth_token=TOKEN&start=1759000000&end=1759086400&dtype=phone&dnumber=1234567

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "time":1234567890, "callerid":"2125551234", ... },
    { "time":1234567891, "callerid":"2125551234", ... }
  ] }

A complete field list is not published for this function beyond time and callerid shown above.

mailboxes/list: your voicemail boxes

Gets the fields of all mailboxes visible to the user. Use this to find the mailbox numbers you need for messages/list.

Requires the user, features or residential role privilege. No extra parameters are needed.

Example

https://manage.press8.com/api/json/mailboxes/list/?auth_token=TOKEN

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "mailbox":"1234", "customer":2, ... },
    { "mailbox":"1235", "customer":2, ... }
  ] }

A single mailbox can be fetched with mailboxes/get and the mailbox parameter.

messages/list: voicemails and faxes in a mailbox

Lists the messages (voicemails, faxes and text messages) in a mailbox folder. The audio or fax files themselves are not included; use messages/get for those.

Requires the user, features or messages role privilege.

Parameter	Type	Description	Default
mailbox	String	Required. Mailbox containing the messages.
folder	String	Required. Folder containing the messages. Most commonly “INBOX”.
type	String	“voicemail”, “fax” or “text”. Empty for any.	Empty
caller	String	Only return messages whose caller ID or caller name contains this text.	Empty
start	Integer	Only return messages received at or after this Unix timestamp.	0
end	Integer	Only return messages received before this Unix timestamp.	Now
duration_minimum	Integer	Only return voicemails at least this many seconds long.	0
duration_maximum	Integer	Only return voicemails at most this many seconds long. -1 for no limit.	-1
sort	String	“caller”, “duration” or “time”. Empty for unsorted.	Empty
descending	Integer	1 to sort descending, 0 not to.	0

Example

https://manage.press8.com/api/json/messages/list/?auth_token=TOKEN&mailbox=1234&folder=INBOX&type=voicemail

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "name":"msg0001", "time":1234567890, ... },
    { "name":"msg0002", "time":1234567891, ... }
  ] }

Returns 404 if the mailbox does not exist. A complete field list is not published for this function beyond name and time shown above.

messages/get: download a voicemail or fax

Gets the fields of one voicemail or fax message, including the message file.

Requires the user, features or messages role privilege.

Important: by default this function marks the message as listened to, so it will no longer show as new. If your software is only copying messages, send listened=0.

Parameter	Type	Description	Default
mailbox	String	Required. Mailbox containing the message.
folder	String	Required. Folder containing the message. Most commonly “INBOX”.
message	String	Required. Message file to get (the name from messages/list).
listened	Integer	1 to mark the message as listened to, 0 not to.	1
encoding	String	“base64” to return the file base64 encoded, “raw” to return raw data.	“raw”
wrap	String	“json” to return the file in a JSON object, “none” to return the plain file.	“json”

Example

https://manage.press8.com/api/json/messages/get/?auth_token=TOKEN&mailbox=1234&folder=INBOX&message=msg0001&listened=0&encoding=base64

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":{ "name":"msg0001", "mimetype":"audio/x-wav", ... } }

calls/active/list: calls in progress

Lists calls that are active right now, one row per call leg.

Requires the user, telephone line reports or callshop role privilege.

Parameter	Type	Description	Default
direction	String	“in”, “out”, “internal” or “in_out” (inbound and outbound, not internal). Empty for all.	Empty
callid	String	The call ID of a specific call.	Empty
names	Integer	1 to set number names, 0 not to.	0
sort	String	“cnumber”, “ctype”, “direction”, “dnumber”, “dtype”, “machine”, “peer”, “scustomer”, “snumber”, “stype” or “uniqueid”.	“start”
descending	Integer	1 to sort descending, 0 not to.	0

Example

https://manage.press8.com/api/json/calls/active/list/?auth_token=TOKEN

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "uniqueid":"1234567890.123456", "start":1234567890, ... },
    { "uniqueid":"1234567890.123457", "start":1234567890, ... }
  ] }

Commonly used fields:

Field	Type	Description
uniqueid	String	A unique identifier for the call leg.
callid	String	A unique identifier for the call. All legs of the same call have the same callid.
start	Integer	Unix timestamp the call started at.
answered	Integer	Unix timestamp the call was answered at. 0 if unanswered.
status	String	The current status of the call.
snumber, stype	String	Source number and source type the call came from.
cnumber	String	Called number.
dnumber, dtype	String	Destination number and type the call is routed to.
callerid_external, callername_external	String	Caller ID number and name sent if routed to an external destination.
callerid_internal, callername_internal	String	Caller ID number and name sent if routed to an internal destination.
recording	String	Empty if the call is not being recorded.

people/list and people/get: users

people/list gets all users on your account. Passwords are not included. people/get gets one user.

Requires the user role privilege.

Parameter (people/list)	Type	Description	Default
count	Integer	1 to return a count, 0 to return full data.	0
limit	Integer	Maximum results to return. 0 for all.	0
offset	Integer	The result to start at. 0 for the first.	0
sort	String	“forename”, “fullname”, “surname” or “username”.	“username”
descending	Integer	1 to sort descending, 0 not to.	0

Parameter (people/get)	Type	Description	Default
id	Integer	ID of the person to get.	0
username	String	User name of the person to get.
email	String	Email address of the person to get.	Empty

One of id, username or email must be given. If more than one user shares an email address, people/get by email returns 409, so prefer id or username.

Example

https://manage.press8.com/api/json/people/list/?auth_token=TOKEN

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "id":1, "username":"user1@example.com", ... },
    { "id":2, "username":"user2@example.com", ... }
  ] }

phones/list and phones/get: telephone lines (extensions)

phones/list gets the telephone lines visible to the user. phones/get gets one line by its name. Both return an extra field, display, which is the name of the line for display purposes.

Requires the user or residential role privilege (phones/get also accepts wholesale).

Parameter (phones/list)	Type	Description	Default
owner	Integer	0: all lines for an administrator login, otherwise only lines owned by the calling user. -1: all lines. A person’s ID: lines owned by that person.	0
count	Integer	1 to return a count, 0 to return full data.	0
limit	Integer	Maximum results to return. 0 for all.	0
offset	Integer	The result to start at. 0 for the first.	0
sort	String	“description” or “name”.	“name”
descending	Integer	1 to sort descending, 0 not to.	0

These functions can also return the lines’ SIP passwords if asked to. Your integration should not need them; please leave that option off.

Example

https://manage.press8.com/api/json/phones/list/?auth_token=TOKEN&owner=-1

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "id":1, "name":"1234567", ... },
    { "id":2, "name":"1234568", ... }
  ] }

numbers/list: your phone numbers

Gets all phone numbers on your account, with where each one is routed.

Requires the user or wholesale role privilege.

Parameter	Type	Description	Default
callerid	Integer	1 to return numbers that can be used as caller ID (including caller-ID-only numbers), 0 to return all normal numbers.	0
count	Integer	1 to return a count, 0 to return full data.	0
limit	Integer	Maximum results to return. 0 for all.	0
offset	Integer	The result to start at. 0 for the first.	0
sort	String	“destination”, “dnumber” or “number”.	“number”
descending	Integer	1 to sort descending, 0 not to.	0

Example

https://manage.press8.com/api/json/numbers/list/?auth_token=TOKEN

{ "responses":[ { "code":"200", "key":"", "message":"OK" } ],
  "data":[
    { "number":"2125551234", "description":"example1", ... },
    { "number":"2125551235", "description":"example2", ... }
  ] }

Call event notifications

Your Press8 account can send a notification to a web address (URL) on your own server each time a call starts, is answered, or ends, including incoming calls. How the notifications work, what they contain and how to receive them is covered in Call Web URLs, which also covers Web URLs, where your server decides how individual calls are routed.

Per-call Web URLs are managed on the Web URLs page in the portal or with the urls API functions (urls/create, urls/update, urls/get, urls/list, urls/delete), which require the urls permission on your API user.

The API is how you set that web address. Use customers/update with your account ID (id) and the events_url parameter; an empty value turns notifications off. Your account ID is the customer field in the reply to user/login. This requires the administrator permission on your API user; if yours does not have it, contact the administrator on your Press8 account.

Important: customers/update treats a missing events_url as empty. Include your current events_url in every customers/update call, or notifications will stop. If the address does not take effect after a successful update, contact Press8 support to have the feature enabled on your account.

Because the address is itself a URL, encode it when passing it as a parameter. It can be up to 255 characters.

https://manage.press8.com/api/json/customers/update/?auth_token=TOKEN&id=ACCOUNT_ID&events_url=https%3A%2F%2Fyour.server.example%2Fpress8-events%3Fkey%3DYOUR_SECRET

For a list of missed calls after the fact, use calls/missed/list above.

Texting

Press8’s business texting service (SMS and MMS) is separate and is not covered by this API.

Help and good practice

• Use a dedicated API login, keep its credentials on your server, and prefer POST over GET.
• Always bound call history and missed call queries with start and end, and page large results with limit and offset.
• Use listened=0 when copying voicemails, so staff still see them as new.
• Ignore fields you do not recognise; the platform adds new ones over time.

For a new API user or additional permissions, contact the administrator on your Press8 account. If the API is not responding as described on this page, contact Press8 support.

Get notified of changes

Subscribe to receive an email each time these API instructions are revised. Subscriptions are available to contacts on a Press8 customer account.

Revision history

Each change to these API instructions is listed here with its revision number. The first part of the revision number is the phone system version the instructions apply to; the second is the date and time of the revision (YYYYMMDD-HHMM, US Central time), so revisions always increase.

Revision	What changed
4.2-20260929-1004	First publication.

Endpoint definitions courtesy of Integrics Ltd., our API integrator.