About

Get Started

This document outlines the resources and corresponding operation interfaces of the PortSIP PBX RESTful APIs.

You cannot run the sample requests in this guide as-is. Replace call-specific parameters, such as tokens and IDs, with your own values.

Schema

Access

The API is accessible at http(s)://[hostname]/api/.

Data Format

• All data is exchanged in JSON (JavaScript Object Notation) format.

• Blank fields are explicitly included as null values to ensure consistency.

Timestamps

• All timestamps returned by the API follow the RFC 3339 format: YYYY-MM-DDTHH:MM:SSZ.

• This format specifies the year, month, day, hour, minute, second, and a mandatory "Z" character indicating Coordinated Universal Time (UTC).

• For detailed information on timestamps in RFC 3339, refer to RFC 3339, section 5.6.

Authentication and Authorization

PortSIP REST API uses Bearer Token Authentication:

• Communication with the PortSIP REST API requires authentication.

• The API utilizes Bearer token authentication, also known as token authentication.

• A bearer token is a unique, opaque string generated by the server in response to a successful login request.

• Clients must include this token in the Authorization header for accessing protected resources.

Obtaining an Access Token

• The Account Login API endpoint is used to acquire an access token.

• Upon successful login, the server sends a JSON response containing the access token within the access_token, refresh_tokne fields, along with additional details like expiry information and user role.

Example Access Token Response:

{
    "access_token": "NGMZZGRMZMQTNJG4YS0ZMJY3LWI1MTUTNWZJYTDIZDA4ODAY",
    "expires_in": 3600,
    "refresh_token": "NTU4Y2UXODATYJYZZC01OGI3LTKZMTATZGQ5ZGM1ODCZMDDM",
    "token_type": "Bearer"
}

Access Token Lifetime and Refresh

• Access tokens have a limited lifespan indicated by either expires_at or expires_in fields in the response.

• The expires_in value represents the duration in seconds until the token expires (e.g., 3600 seconds for one hour).

• Before expiration, refresh the access_token using the refresh token API with the refresh_token to obtain a new one.

• Re-use the access token until it expires to optimize API calls.

HTTP verbs

The PortSIP REST API supports both GET and POST HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources.
POST	Used for creating, replacing or deleting resources.

Summary Representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource. Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.

Resource ID

Each resource has a corresponding ID, for example, NzAwNTUxOTA5NzczMTQ4MTYw. After successfully creating the resource, the user will receive the returned ID and must provide this ID when accessing the resource. Clients should treat this ID as an opaque string and should never attempt to assemble it. This document imposes no constraints on the format, and clients should never impose any.

Query Options Overview

A query option is a set of query string parameters applied to a resource that can help control the amount of data being returned for the resource in the URL. Essentially, a query option requests that a service perform a set of transformations, such as filtering or sorting, on its data before returning the results.

Filter

The filter query option allows clients to filter a collection of resources addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response. Resources for which the expression evaluates to false or null, or which reference properties unavailable due to permissions, are omitted from the response. You can find details on filter specification in the OData spec filter options section.

Examples:

• All CDRs with a caller equal to ‘101’: http://host/api/cdrs?filter=caller eq '101'

• All CDRs with a caller not equal to ‘101’: http://host/api/cdrs?filter=caller ne '101'

• All CDRs with a caller greater than ‘101’: http://host/api/cdrs?filter=caller gt '101'

• All CDRs with a caller greater than or equal to ‘101’: http://host/api/cdrs?filter=caller ge '101'

• All CDRs with a caller less than ‘101’: http://host/api/cdrs?filter=caller lt '101'

• All CDRs with a caller less than or equal to ‘101’: http://host/api/cdrs?filter=caller le '101'

• All CDRs with the caller ‘101’ that also have a start time greater than ‘2022-01-01T00:00:00Z’: http://host/api/cdrs?filter=caller eq '101' and started_at gt '2022-01-01T00:00:00Z'

• All CDRs that either have the caller ‘101’ or have a start time less than ‘2022-01-01T00:00:00Z’: http://host/api/cdrs?filter=caller eq '101' or started_at lt '2022-01-01T00:00:00Z'

• All CDRs that have a caller that starts with ‘10’: http://host/api/cdrs?filter=startswith(caller,'10')

• All CDRs that have a caller that ends with ‘01’: http://host/api/cdrs?filter=endswith(caller,'01')

• All CDRs that have a caller that contains ‘0’: http://host/api/cdrs?filter=contains(caller,'0')

OrderBy

• The orderby system query option allows clients to request resources in a particular order.

Example:

• Return all CDRs ordered by caller in ascending order, then by start time in descending order: GET http://host/api/cdrs?orderby=caller asc, started_at desc

Top and Skip

The top system query option requests the number of items in the queried collection to be included in the result. The skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining top and skip. Note that skip numbering is 1-based and that omitting the skip parameter will return the first page.

Examples:

• Get top 100 CDRs: http://host/api/cdrs?top=100

• Skip first 100 items: http://host/api/cdrs?$skip=100

Count

The count system query option allows clients to request a count of the matching resources included with the resources in the response. The count query option has a Boolean value of true or false.

Example:

• Return, along with the results, the total number of CDRs in the collection: http://host/api/cdrs?count=true

Search

The search system query option allows clients to request items within a collection matching a free-text search expression. The search query option can be applied to a URL representing a collection of entity, complex, or primitive typed instances. If both search and filter are applied to the same request, the results include only those items that match both criteria.

Example:

• All CDRs that are 101 or 102. It is up to the service to decide what makes a CDR 101 or 102: http://host/api/cdrs?search=101 or 102

Detailed representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource. Note that authorization sometimes influences the amount of detail included in the representation.

Timezones

Some requests that create new data allow you to provide time zone information when specifying or generating timestamps. We use RFC 3339 timestamps to determine time zone information for API calls.

API Response

PortSIP PBX API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource.

Error Handling

Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses in a JSON response body. One or more errors will be returned in the following format:

{
  "errors": [
    {
      "code": "<error identifier>",
      "message": "<message describing condition>",
      "detail": "<unstructured>"
    }
  ]
}

• The code field will be a unique identifier, all caps with underscores by convention.

• The message field will be a human-readable string.

• The optional detail field may contain arbitrary JSON data providing information the client can use to resolve the issue. While the client can take action on certain error codes, the registry may add new error codes over time. All client implementations should treat unknown error codes as UNKNOWN, allowing future error codes to be added without breaking API compatibility. For the purposes of the specification, error codes will only be added and never removed.

Errors

The error codes encountered via the API are enumerated in the following table:

Code	Message	Description
UNKNOWN	unknown error	Generic error returned when the error does not have an API classification
VALIDATE_FAILED	field validation failed	This error code may be returned if a field validation fails.

Resource Synchronization

PortSIP PBX RESTful APIs allow a client to request only resources that have changed. The high-level process is as follows:

• Client requests a sync token from the server.

• Server reports token 001.

• Some time passes.

• Client makes a sync request on the resource and supplies token 001.

• Server returns resources that have been created, updated, or deleted and returns token 002. As you can see, after the initial sync, only items that have been created, updated, or deleted will be sent. This has several advantages. The transmitted HTTP response bodies can generally be much shorter, and it is easier on both the client and server in terms of memory and CPU usage because only a limited set of items need to be compared.

Note that a server is free to "forget" any sync tokens that have been previously issued. In this case, a full sync may be needed again. If the supplied sync token is not recognized by the server, an HTTP status code 403 is returned.

Personal Contacts Synchronization

The process for synchronizing personal contacts is as follows:

1. Client gets a sync token from the server by sending a POST request to /api/user/contacts/sync_tokens.

2. Server reports token 001.

3. Some time passes.

4. Client performs a sync operation by sending a POST request to /api/user/contacts/sync_tokens/{token}, supplying token 001.

5. Server returns contacts that have been created, updated, or deleted and returns token 002.

Getting the First Sync Token

Initially, request a sync token for contacts:

curl -X POST 'https://HOSTNAME:PORT/api/user/contacts/sync_tokens'

This would return something like the following:

{
  "token": "001"
}

Receiving Changes

After a sync token has been obtained, the client can request all changes since the token was issued. This is done with a request that may look like this:

curl -X POST 'https://HOSTNAME:PORT/api/user/contacts/sync_tokens/001'

This would return something like the following:

{
  "token": "002",
  "items": [
    {
      "id": "CREATED-ITEM-ID",
      "name": "...",
      "email": "...",
      "company": "...",
      "title": "...",
      "business": "...",
      "business2": "...",
      "mobile_phone": "...",
      "mobile_phone2": "...",
      "home_phone": "...",
      "home_phone2": "...",
      "other": "...",
      "business_fax": "...",
      "home_fax": "...",
      "address": "...",
      "notes": "...",
      "favorite": "...",
      "change_type": "CREATED"
    },
    {
      "id": "UPDATED-ITEM-ID",
      "name": "...",
      "email": "...",
      "company": "...",
      "title": "...",
      "business": "...",
      "business2": "...",
      "mobile_phone": "...",
      "mobile_phone2": "...",
      "home_phone": "...",
      "home_phone2": "...",
      "other": "...",
      "business_fax": "...",
      "home_fax": "...",
      "address": "...",
      "notes": "...",
      "favorite": "...",
      "change_type": "UPDATED"
    },
    {
      "id": "DELETED-ITEM-ID",
      "name": "...",
      "email": "...",
      "company": "...",
      "title": "...",
      "business": "...",
      "business2": "...",
      "mobile_phone": "...",
      "mobile_phone2": "...",
      "home_phone": "...",
      "home_phone2": "...",
      "other": "...",
      "business_fax": "...",
      "home_fax": "...",
      "address": "...",
      "notes": "...",
      "favorite": "...",
      "change_type": "DELETED"
    }
  ]
}