> For the complete documentation index, see [llms.txt](https://dantonia.gitbook.io/test/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dantonia.gitbook.io/test/master.md). # Opentact API Reference Sheet ## Introduction Opentact is a real-time communications platform with full, feature-rich functionality, making it quick and easy to set up and port numbers around the world, configure messaging, control VoIP and IP network functions, and define how and where communications can be used in real time. The Opentact API has the capability to support a host of specialty applications, from call tracking to cloud-based PBX, dynamic security, and authentication use cases. Our API Reference is organized by topics, such as Phone [Numbers](/test/telephone-number.md) API or [Messaging](/test/messaging.md) API. Each topic is prefaced with a general overview that describes how our API can be used within the context of that topic, followed by reference documentation of specific API endpoints. Opentact strives to create a developer-first platform with top tier documentation and 24/7 support. Explore our API capabilities, and please let us know how we can further empower your development team to better serve your customers. **BASE URLs** * `https://api.opentact.org` * `https://api.stage.opentact.org` **CLIENT LIBRARIES** * PHP * Python * Node * Go {% tabs %} {% tab title="PHP" %} ``` ``` {% endtab %} {% tab title="Python" %} ``` ``` {% endtab %} {% tab title="Node" %} ``` ``` {% endtab %} {% tab title="Go" %} ``` ``` {% endtab %} {% endtabs %} ## **Overview** **Protocols** Opentact HTTP or HTTPS endpoints are [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer), and consume and return [JSON](http://www.json.org/)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg). All HTTP/HTTPS endpoints require an API Key in the request header. More information on API Keys and Authorization headers in the [Authentication](/test/authentication.md) section. **Glossary** | TERM | DESCRIPTION | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Numbers | DIDs and toll-free numbers that can be purchased and managed in order to receive calls (inbound/origination) | | Messaging | Short Message Service (SMS) text messaging. Long code | | Porting | Transferring of DIDs and toll-free numbers onto the Opentact network from another carrier | | Connections | Provisions SIP trunks | | Call Control Applications | Configure webhooks and voice settings for call control. This resource provisions SIP trunks for call control use cases. | | Reports | Access Call and Messaging Detail Records, and generate usage reports | ## Authentication The Opentact API uses API Keys to authenticate requests. You can view and manage your API Keys by logging into your [Mission Control Portal](https://portal.telnyx.com/)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg) account and navigating to the Auth V2 tab in the "Auth" section. For information regarding API V1 Authentication please refer to [here](https://developers.telnyx.com/docs/api/v1/overview#authentication)API. Your API Keys carry many privileges, so be sure to keep them secure! Do not share your secret API Keys in publicly accessible areas such as GitHub, client-side code, and so forth. To use your API Key, assign it in your SDK as shown in this quickstart guide section. Using our RESTful API, you can also make requests by passing the API Key in the `Authorization` header: `Authorization: Bearer "`. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. {% content-ref url="/pages/-MKZjrjlGJD5eA5e5ipv" %} [Authentication](/test/authentication.md) {% endcontent-ref %} ## SIP Domain We offer free Peer to Peer and Group Chat, Call, and Video Conference. **CLIENT LIBRARIES** * PHP * Python * Node * Go {% tabs %} {% tab title="PHP" %} ``` ``` {% endtab %} {% tab title="Python" %} ``` ``` {% endtab %} {% tab title="Node" %} ``` ``` {% endtab %} {% tab title="Javascript" %} ``` npm install ``` {% endtab %} {% tab title="Go" %} ``` ``` {% endtab %} {% endtabs %} ## Parameters and Field Names The Parameter & Field Names section provides an overview of patterns for API request and response parameter and field names. **HTTP Headers** Date-times in HTTP headers follow [RFC-7231 §7.1.1.1](https://tools.ietf.org/html/rfc7231#section-7.1.1.1)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg)'s recommended "IMF-fixdate" format. > An example of the preferred format is > > Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate **Booleans** Boolean values are presented as `true` and `false` values. They will not be `1` or `0` nor will they be strings such as "true" and "false". **Date-times** All date-times are represented in UTC with precisely the following format: `YYYY-MM-DDThh:mm:ss.fffZ` where `fff` is the first three decimals of the fractional seconds (i.e., millisecond precision). API V2 accepts date-times in *at least* the following formats: * `YYYY-MM-DDThh:mm:ss.fffZ` * `YYYY-MM-DDThh:mm:ssZ` * `YYYY-MM-DDThh:mmZ` * The above with `-00`, `-0000`, or `-00:00` instead of the `Z` timezone identifier. **Times (no date portion)** All times are represented in UTC with precisely the following format: `hh:mm:ss.fffZ` where `fff` is the first three decimals of the fractional seconds (i.e., millisecond precision). **Durations** If a parameter represents a unit of time, then the unit name should be part of the field name so that the consumer knows what the value represents. For example, a retry timeout value would be named `retry_timeout_secs` or `retry_timeout_millis`. Valid field suffixes are: * millis * secs * hours * days * weeks * months * years **Time zones** Time zone field names are always spelled as `timezone` and the value is always [the Time Zone Database](https://www.iana.org/time-zones)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg) area name spelled out as `Europe/Berlin`, `America/Chicago` for example. **Date Literals** User-friendly date ranges use this naming convention. | DATE LITERAL | RANGE | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | yesterday | Starts 00:00:00 the day before and continues for 24 hours. | | today | Starts 00:00:00 of the current day and continues for 24 hours. | | tomorrow | Starts 00:00:00 after the current day and continues for 24 hours. | | last\_week | Starts 00:00:00 on the first day of the week before the most recent first day of the week and continues for seven full days. | | this\_week | Starts 00:00:00 on the most recent first day of the week before the current day and continues for seven full days. | | next\_week | Starts 00:00:00 on the most recent first day of the week after the current day and continues for seven full days. | | last\_month | Starts 00:00:00 on the first day of the month before the current day and continues for all the days of that month. | | this\_month | Starts 00:00:00 on the first day of the month that the current day is in and continues for all the days of that month. | | next\_month | Starts 00:00:00 on the first day of the month after the month that the current day is in and continues for all the days of that month. | | last\_N\_hours | For the number n provided, starts at 00 of the last hour and continues for the past n hours. | | next\_N\_hours | For the number n provided, starts at 00 of the next hour and continues for the next n hours. | | last\_N\_days | For the number n provided, starts 00:00:00 of the current day and continues for the past n days. | | next\_N\_days | For the number n provided, starts 00:00:00 of the current day and continues for the next n days. | | last\_N\_weeks | For the number n provided, starts 00:00:00 of the last day of the previous week and continues for the past n weeks. | | next\_N\_weeks | For the number n provided, starts 00:00:00 of the first day of the next week and continues for the next n weeks. | **Enums and String Literals** Enum and string literal parameters use snake case. If there is an acronym involved, there will not be an underscore between every letter. For example, `by_ani` instead of `ByANI`, `byAni`, or `by_a_n_i`. **Country Codes** The field name `country_code` is always used to represent a country. It will be in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg) format in capital letters to represent the country. For example `DE` for Germany. **Addresses** Addresses are represented like this: E.g. ``` { "street_address": "311 W Superior St", "extended_address": "Suite 504", "locality": "Chicago", "administrative_area", "IL" "country_code": "US", "postal_code": "60654" } ``` Copy Code![copy](https://developers.telnyx.com/assets/icon-copy.svg) **U.S. Addresses** US states are always represented in their two-digit form in capital letters. For example, `NY` for New York. **City Names** City names are always called `locality` and represented in title case. For example, `New York City` instead of `NEW YORK CITY`. **Phone Numbers** Phone numbers are always specified in [e164](https://en.wikipedia.org/wiki/E.164)![Telnyx Developers](https://developers.telnyx.com/assets/icon-external-link.svg) format. For example, `+18005550199`. If the country calling code needs to be represented in the API, the field name will always be `country_calling_code`. If representing the actual country via its alpha 2 representation, `country_code` will be used. Ex: `{"country_calling_code": "1", "country_code": "US"}` **PAGINATION** The parameter which contains pagination is `page`. This parameter is a map of pagination attributes. **Example** `GET /phone_numbers?page[number]=3&page[size]=1 HTTP/1.1` The default number of items per page is 20; however, sometimes, this may not be appropriate. Page numbering is 1-based and omitting the `page`, or the `page[number]` parameter will return the first page. Generally speaking, the maximum allowable results will not be more than 250, although there may be some exceptions to this rule. The total number of results is provided in the `total_pages` field so that clients will know how many page options to display. **SORTING** An endpoint may support requests to sort the primary data with a `sort` query parameter. **Example** ``` GET /connections?sort=name HTTP/1.1 ``` Copy Code![copy](https://developers.telnyx.com/assets/icon-copy.svg) Unless not appropriate, the default sort will be `created_at DESC` An endpoint may also support multiple sort fields using the array syntax. Sort fields will be applied in the order specified. **Example** ``` GET /connections?sort[]=name&sort[]=created_at HTTP/1.1 ``` Copy Code![copy](https://developers.telnyx.com/assets/icon-copy.svg) The sort order for each sort field will be ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it will be descending. ``` GET /connections?sort[]=-created_at&sort[]=name HTTP/1.1 ``` The above example should return the newest connections first. Any connections created on the same date will then be sorted by their name in ascending alphabetical order. **FILTERING** Filtering of a resource collection based upon associations do so by allowing query parameters that combine the filter with the association name. For example, the following is a request for all phone\_numbers associated with a particular tag: ``` GET /phone_numbers?filter[tag]=tag_one HTTP/1.1 ``` Filtering two values within an array can be achieved using query parameter array syntax: ``` GET /phone_numbers?filter[tag][]=tag_one&filter[tag][]=tag_two HTTP/1.1 ``` ``` GET /comments?filter[tag]=tag_one,tag_two HTTP/1.1 ``` Use the string `null` to filter on resources that don't have a particular value set: ``` GET /comments?filter[author]=null HTTP/1.1 ``` **FILTERING ON VALUES OF NESTED OR RELATED OBJECTS** In order to denote that a filter applies to an attribute of a nested object, use the dot notation. For example, the phone numbers endpoint returns data in this format: ``` { "id": "d460a653-8ee6-4061-ae9a-5b8a52539fb4", "phone_number": "18005550199", "record_type": "phone_number", ... "voice": { "e911_address_id" : "", "connection_name" : false, "inbound_call_recording_channels" : "single", ... } } ``` In order to filter by the connection name the path and request would look like: ``` GET /phone_numbers?filter[voice.connection_name]=conn_one HTTP/1.1 ``` Similarly by connection id: ``` GET /phone_numbers?filter[voice.connection_id]=d460a653-8pp6-4061-ae9a-5b8a57339fb4 HTTP/1.1 ``` However, if `name` was a top-level key as in the below example: ``` { "id": "d460a653-8pp6-4061-ae9a-5b8a57339fb4", "name": "conn_one", "record_type": "connection", ... }e ``` then the query would be: ``` GET /connections?filter[name]=conn_one HTTP/1.1 ``` **COMPLEX FILTERS** When filtering, you may need to specify more complex filters than `equal to`. Options are: * `eq` * `ne` * `gt` * `gte` * `lt` * `lte` * `starts_with` * `ends_with` * `contains` Return phone numbers purchased before 2018-02-21: ``` GET /phone_numbers?filter[purchased_at][lt]=2018-02-21 HTTP/1.1 ``` If using `eq` then: ``` GET /phone_numbers?filter[purchased_at][eq]=2018-02-21 HTTP/1.1 ``` Copy Code![copy](https://developers.telnyx.com/assets/icon-copy.svg) and: ``` GET /phone_numbers?filter[purchased_at]=2018-02-21 HTTP/1.1 ``` Copy Code![copy](https://developers.telnyx.com/assets/icon-copy.svg) are equivalent. To filter using string data use `starts_with`, `ends_with` or `contains`: ``` GET /phone_numbers?filter[voice.connection_name][contains]=conn HTTP/1.1 ``` ## Requests Requests to any API endpoint should be in the JSON format, with rare exceptions made for allowing other request types when needed (such as for file uploads). ## Responses All endpoints will respond with JSON unless another format is specifically requested and supported. ## Webhooks COMMENT: Are these being supported with our API? ## Errors We include known causes and possible solutions so that API users can write logic to handle errors intelligently and debug quickly. {% content-ref url="/pages/-MKZV7dzJimitC6niigs" %} [Messaging](/test/messaging.md) {% endcontent-ref %} {% content-ref url="/pages/-MKZVJ6hL7rY3zF38T3N" %} [Phone Numbers](/test/telephone-number.md) {% endcontent-ref %} {% content-ref url="/pages/-MKZVJfoBWspqnYQPY8R" %} [Call Control](/test/call-control.md) {% endcontent-ref %} {% content-ref url="/pages/-MKZVQQgB9Ku3ky358Ce" %} [Broken mention](broken://pages/-MKZVQQgB9Ku3ky358Ce) {% endcontent-ref %}