openapi: 3.2.0 info: title: Sonetel Usage API version: '2.0' contact: {} description: 'Operations tagged Usage across 2 of this provider''s published API definitions: 9_usagerecords.yaml, sonetel-usage-records-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://public-api.sonetel.com description: Production tags: - name: Usage paths: /usage/account/{accountid}/usagerecord: get: summary: Get usage records description: Use this endpoint to get your usage records as a JSON response. Use the query parameters to filter the data. operationId: get-usagerecord parameters: - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/charge_type' - $ref: '#/components/parameters/service' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/accountid' - $ref: '#/components/parameters/Authorization' responses: '200': $ref: '#/components/responses/usage-record-get' servers: - url: https://public-api.sonetel.com description: Production tags: - Usage servers: - url: https://public-api.sonetel.com description: Production /usage/account/{accountid}/usagerecord/download: get: summary: Download usage records description: 'Download the usage records in a CSV for offline analysis. > If `start_time` and `end_time` are not included in the request, only 15 records are downloaded by default.' operationId: get-usagerecord-download parameters: - $ref: '#/components/parameters/charge_type' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/service' - $ref: '#/components/parameters/accountid' - $ref: '#/components/parameters/Authorization' responses: '200': $ref: '#/components/responses/usage-record-download' '401': description: A 401 response is sent when the access token is either expired or malformed. servers: - url: https://public-api.sonetel.com description: Production tags: - Usage servers: - url: https://public-api.sonetel.com description: Production components: responses: usage-record-get: description: A success response returns the usage records along with pagination information. content: application/json: schema: type: object properties: resource: type: string description: Name of the resource being accessed readOnly: true status: type: string description: Status of the request readOnly: true endFlag: type: string enum: - 'true' - 'false' description: A boolean value that indicates whether or not data is available in the next page. readOnly: true startFlag: type: string enum: - 'true' - 'false' description: A boolean value that indicates whether or not data is available in the last page. readOnly: true pagination: type: object description: Information about pagination. properties: req_id: type: string description: A unique ID generated for each request. This is used in pagination. readOnly: true max_count: type: string description: The total number of results readOnly: true next: type: string description: URI for the next set of results readOnly: true previous: type: string description: URI for the previous set of results readOnly: true before: type: string description: Number of results in the previous page readOnly: true count: type: string description: Number of results in the current page readOnly: true refresh: type: string description: URI to refresh the current set of results readOnly: true after: type: string description: Number of results on the next page readOnly: true readOnly: true response: type: array description: Array carrying the usage records readOnly: true items: type: object description: The usage record object. properties: record_id: type: string description: The unique Id of the usage record. readOnly: true timestamp: type: string description: The date/time when the service was used. In case of calls and services that are used over a period of time, the detailed specifications are provided in other fields. readOnly: true service: type: string description: The service used readOnly: true account_id: type: string description: The Sonetel account ID. readOnly: true usage_details: type: object description: 'Details of the usage record. The details vary depending on the type of usage for which the record has been generated. Each usage record only contains one usage type i.e. `call`, `phnumsubscription` and so on.' properties: call: type: object description: Usage details for all types of phone calls. properties: start_time: type: string description: The usage start date & time. readOnly: true end_time: type: string description: The usage end date & time. readOnly: true call_length: type: string description: The length of the call in seconds readOnly: true from_type: type: string description: The type of source from where the call originated readOnly: true from: type: string description: The ID of the source from where the call originated readOnly: true caller_id: type: string description: The caller-ID sent to the called destination. readOnly: true to_type: type: string description: The type of destination where the call is sent. readOnly: true to: type: string description: The ID of the destination where the call is sent. For example, in case of outbound calls this will be the number called. readOnly: true to_orig: type: string description: 'The original value of the destination where the call is sent. The field `to` is usually a translated value. For example, a number may be dialed in a country’s local format. In which case, the value `to_orig` carries the local number(e.g. `076513234`), while the field `to` contains the translated E164 number(e.g. `4676513234`)' readOnly: true app_type: type: string description: 'A string field that indicates whether the call was connected to a voice app. It is empty if the call is not connected ' readOnly: true readOnly: true phnumsubscription: type: object description: Usage details related to phone number subscriptions properties: phnum: type: string description: The Sonetel phone to which this record applies. In case of a number series, the value in the field is the first phone number in the series. readOnly: true country: type: string description: The country of the phone number readOnly: true area_code: type: string description: The telephone area code of the phone number readOnly: true city: type: string description: Name of the city where the number is. The name is descriptive and does not follow any standard. readOnly: true type: type: string enum: - national - geographic - tollfree - mobile description: The type of number – this can be either “national”, “geographic”, “tollfree", "mobile" readOnly: true range: type: string description: Applicable if the phone number subscription is of a number that is a part of a phone number series. The value specifies the quantity of phone numbers in the number series of which this phone number is a part of. readOnly: true price_category: type: string enum: - '1' - '2' - '3' - '4' - '5' description: 'The price category of the number/series. The allowed values are 1- regular, 2- gold, 3 - gold+, 4 - gold++, 5 -gold+++. Does not apply to new phone numbers purchased.' readOnly: true readOnly: true inbound_sms: type: object description: Details of the usage related to incoming SMS. properties: from: type: string description: The sender's phone number. readOnly: true to: type: string description: The Sonetel number to which the SMS was sent. readOnly: true delivered_to: type: string description: The email address of the user to whom the SMS was delivered. format: email readOnly: true readOnly: true readOnly: true charges: type: object description: Details of the charges applied to the usage record properties: priceplan: type: string description: 'The price plan applicable for charges. Price plans define special discounts and prices for services. An account that subscribes to a price plan will have pricing applicable as per the price plan.' readOnly: true currency: type: string enum: - USD - SEK - EUR description: The currency in which the charges are applied. readOnly: true count: type: string description: The number of instances that are charged. For example, the number of users in case of monthly plan charges. readOnly: true usage_fixed: type: string description: Charges applied for fixed cost services such as incoming SMS, calls to a voice app and so on. readOnly: true usage_time: type: string description: The time based usage fee charged to this record. This normally applies to calls as they are charged per minute. readOnly: true subscription_setup: type: string description: The one time fee charged to this usage record. Usually applied to phone number subscriptions. readOnly: true subscription_recurring: type: string description: The recurring fee charged to this usage record. readOnly: true usage_vat: type: string description: 'The VAT value associated with this usage. VAT is only charged for accounts that have billing addresses within the European Union. VAT is waived off if you enter your VAT ID at app.sonetel.com.' readOnly: true renew_mode: type: string description: The renewal mode of the subscription. Not set for other types of usage records such as calls. readOnly: true example: 1m, 1y, 3y readOnly: true readOnly: true readOnly: true x-examples: example-1: resource: usagerecord status: success endFlag: 'true' pagination: req_id: 7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01 max_count: '241818' next: https://public-api.sonetel.com/usagerec/account/25001234/usagerecord?req_id=7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01&count=4&after=4 previous: '' before: '0' count: '4' refresh: https://public-api.sonetel.com/usagerec/account/25001234/usagerecord?req_id=7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01&reload=yes&count=4&before=0 after: '4' response: - record_id: '400774995' timestamp: 2022/08/01T08:51:12Z service: inbound_call account_id: '25001234' usage_details: call: start_time: 2022/08/01T08:51:12Z end_time: 2022/08/01T08:51:37Z call_length: '25' from_type: phonenumber from: '+6594660000' caller_id: '+6594660000' to_type: phonenumber to: '+6531589999' to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '' usage_time: '0.0' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none - record_id: '400774994' timestamp: 2022/08/01T08:51:12Z service: voiceapp_menu account_id: '25001234' usage_details: call: start_time: 2022/08/01T08:51:12Z end_time: 2022/08/01T08:51:37Z call_length: '25' from_type: phonenumber from: '+6594660000' caller_id: '+6594660000' to_type: sip to: vai6345m4oioic to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '0' usage_time: '' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none - record_id: '400772567' timestamp: 2022/08/01T07:37:54Z service: inbound_call account_id: '25001234' usage_details: call: start_time: 2022/08/01T07:37:54Z end_time: 2022/08/01T07:38:20Z call_length: '26' from_type: phonenumber from: '+14162000000' caller_id: '+14162000000' to_type: phonenumber to: '+18559999999' to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '' usage_time: '0.64' subscription_setup: '' subscription_recurring: '' usage_vat: '0.16' renew_mode: none - record_id: '400772566' timestamp: 2022/08/01T07:37:54Z service: voiceapp_menu account_id: '25001234' usage_details: call: start_time: 2022/08/01T07:37:54Z end_time: 2022/08/01T07:38:20Z call_length: '26' from_type: phonenumber from: '+14162000000' caller_id: '+14162000000' to_type: sip to: vai6345m4pgxic to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '0' usage_time: '' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none examples: Usage Record: value: resource: usagerecord status: success endFlag: 'true' pagination: req_id: 7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01 max_count: '241818' next: https://public-api.sonetel.com/usagerec/account/25001234/usagerecord?req_id=7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01&count=4&after=4 previous: '' before: '0' count: '4' refresh: https://public-api.sonetel.com/usagerec/account/25001234/usagerecord?req_id=7bf20e91-c568-4c18-84e7-e13014fcd4e0-2022:08:01&reload=yes&count=4&before=0 after: '4' response: - record_id: '400774995' timestamp: 2022/08/01T08:51:12Z service: inbound_call account_id: '25001234' usage_details: call: start_time: 2022/08/01T08:51:12Z end_time: 2022/08/01T08:51:37Z call_length: '25' from_type: phonenumber from: '+6594660000' caller_id: '+6594660000' to_type: phonenumber to: '+6531589999' to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '' usage_time: '0.0' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none - record_id: '400774994' timestamp: 2022/08/01T08:51:12Z service: voiceapp_menu account_id: '25001234' usage_details: call: start_time: 2022/08/01T08:51:12Z end_time: 2022/08/01T08:51:37Z call_length: '25' from_type: phonenumber from: '+6594660000' caller_id: '+6594660000' to_type: sip to: vai6345m4oioic to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '0' usage_time: '' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none - record_id: '400772567' timestamp: 2022/08/01T07:37:54Z service: inbound_call account_id: '25001234' usage_details: call: start_time: 2022/08/01T07:37:54Z end_time: 2022/08/01T07:38:20Z call_length: '26' from_type: phonenumber from: '+14162000000' caller_id: '+14162000000' to_type: phonenumber to: '+18559999999' to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '' usage_time: '0.64' subscription_setup: '' subscription_recurring: '' usage_vat: '0.16' renew_mode: none - record_id: '400772566' timestamp: 2022/08/01T07:37:54Z service: voiceapp_menu account_id: '25001234' usage_details: call: start_time: 2022/08/01T07:37:54Z end_time: 2022/08/01T07:38:20Z call_length: '26' from_type: phonenumber from: '+14162000000' caller_id: '+14162000000' to_type: sip to: vai6345m4pgxic to_orig: '' app_type: '' charges: priceplan: regular currency: SEK count: '' usage_fixed: '0' usage_time: '' subscription_setup: '' subscription_recurring: '' usage_vat: '0.0' renew_mode: none headers: Content-Type: schema: type: string description: application/json;charset=UTF-8 Connection: schema: type: string description: keep-alive usage-record-download: description: A success response will return the URL from where the usage records can be downloaded. content: application/json: schema: type: object properties: resource: type: string description: Name of the resource called status: type: string description: The status of the request response: type: string description: The URL from where to download the usage records. x-examples: example-1: resource: usagerecord status: success response: https://downloads-usage.sonetel.com/usage/usage_200000123_165554332456.csv examples: Download usage record: value: resource: usagerecord status: success response: https://downloads-usage.sonetel.com/usage/usage_2000000007_1659517051676.csv headers: Content-Type: schema: type: string description: application/json;charset=UTF-8 parameters: service: name: service in: query description: String identifier for the service used. schema: type: string enum: - outbound_call - inbound_call - phnum_subscription - on-net_call - fax_to_email - sms_to_email - priceplan_premium - voiceapp_menu - voiceapp_company-voicemail - voiceapp_prompt-recording - voiceapp_call-thru - overusage - voiceapp_user-voicemail - conference - priceplan_business Authorization: name: Authorization in: header description: The authorization header contains your access token and is used to authenticate requests. Generate an `access_token` using the `/oauth/token` endpoint. required: true schema: type: string example: Bearer accountid: name: accountid in: path description: Your Sonetel account ID. required: true schema: type: string count: name: count in: query description: Limits the number of results per page. Used in pagination. required: false schema: type: number charge_type: name: charge_type in: query description: The type of charge applied to the account. schema: type: string enum: - usage_fixed - usage_time - subscription_setup - subscription_recurring start_time: name: start_time in: query description: The starting date and time for which usage is included in the results. required: false schema: type: string example: 20220630T18:30:00Z end_time: name: end_time in: query description: The last date and time for which usage is included in the results. schema: type: string example: 20220731T18:29:59Z securitySchemes: production: type: oauth2 description: Get an access token from the `/oauth/token` and pass it as a Bearer token in the `Authorization` header. flows: password: refreshUrl: https://api.sonetel.com/SonetelAuth/beta/oauth/token tokenUrl: https://api.sonetel.com/SonetelAuth/beta/oauth/token scopes: {} x-refined-from: - 9_usagerecords.yaml - sonetel-usage-records-openapi.yml