{ "openapi": "3.0.3", "info": { "title": "CDR Telco API", "version": "1.36.0", "description": "Specifications for resource endpoints applicable to data holders in the Telco sector.", "license": { "name": "MIT License", "url": "https://opensource.org/licenses/MIT" }, "contact": { "name": "Data Standards Body", "email": "contact@dsb.gov.au", "url": "https://dsb.gov.au/" } }, "servers": [ { "description": "MTLS", "url": "https://mtls.dh.example.com/cds-au/v1" } ], "tags": [ { "name": "Telco Products", "x-shortName": "Products", "description": "Telco Product endpoints" }, { "name": "Telco Accounts", "x-shortName": "Accounts", "description": "Telco Account endpoints" }, { "name": "Telco Account Service Usage", "x-shortName": "Service Usage", "description": "Telco Account Service Usage endpoints" }, { "name": "Telco Account Balances", "x-shortName": "Account Balances", "description": "Telco Account Balance endpoints" }, { "name": "Telco Account Billing", "x-shortName": "Account Billing", "description": "Telco Account Billing endpoints" } ], "paths": { "/telco/products": { "get": { "servers": [ { "description": "TLS", "url": "https://tls.dh.example.com/cds-au/v1" } ], "description": "Obtain a list of telco products that are currently offered to the market.\n\nNote that the results returned by this endpoint are expected to be ordered in descending order according to _lastUpdated_.", "operationId": "listTelcoProducts", "parameters": [ { "name": "type", "description": "Used to filter results on the type field. Any one of the valid values for this field can be supplied. If absent, defaults to include `ALL` products. Valid values are [`MOBILE`](https://www.legislation.gov.au/Details/C2022C00170/Html/Volume_1#_Toc95898745) service, `BROADBAND` fixed internet service, or `ALL`.", "in": "query", "required": false, "schema": { "enum": [ "MOBILE", "BROADBAND", "ALL" ], "default": "ALL", "type": "string" } }, { "name": "billing-type", "description": "Used to filter results on the _billing-type_ field. Any one of the valid values for this field can be supplied. If absent, defaults to include all billing types. Valid values are `PRE_PAID`, `POST_PAID`, `UPFRONT_PAID`, `ALL`.", "in": "query", "required": false, "schema": { "enum": [ "PRE_PAID", "POST_PAID", "UPFRONT_PAID", "ALL" ], "type": "string" } }, { "name": "effective", "description": "Allows for the filtering of products based on whether the current time is within the period of time defined as effective by the _effectiveFrom_ and _effectiveTo_ fields. Valid values are `CURRENT`, `FUTURE` and `ALL`. If absent defaults to `CURRENT`.", "in": "query", "required": false, "schema": { "default": "CURRENT", "enum": [ "CURRENT", "FUTURE", "ALL" ], "type": "string" } }, { "name": "updated-since", "description": "Only include products that have been updated after the specified date and time. If absent defaults to include all plans.", "in": "query", "required": false, "schema": { "type": "string" }, "x-cds-type": "DateTimeString" }, { "name": "brand", "description": "Used to filter results on the brand field. If absent, defaults to include all products. For service providers that operate a number of mobile and internet brands.", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/QueryPage" }, { "$ref": "#/components/parameters/QueryPageSize" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" } ], "responses": { "200": { "$ref": "#/components/responses/ListTelcoProducts200" }, "400": { "$ref": "#/components/responses/ListTelcoProducts400" }, "406": { "$ref": "#/components/responses/ListTelcoProducts406" }, "422": { "$ref": "#/components/responses/ListTelcoProducts422" } }, "summary": "Get Telco Products", "tags": [ "Telco Products" ], "x-version": "1" } }, "/telco/products/{productId}": { "get": { "servers": [ { "description": "TLS", "url": "https://tls.dh.example.com/cds-au/v1" } ], "description": "Obtain detailed information on a single telco product offered openly to the market.", "operationId": "getTelcoProductDetail", "parameters": [ { "name": "productId", "description": "The _productId_ to obtain data for. _productId_ values are returned by product list endpoints.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TelcoProductId" }, "x-cds-type": "ASCIIString" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" } ], "responses": { "200": { "$ref": "#/components/responses/GetTelcoProductDetail200" }, "400": { "$ref": "#/components/responses/GetTelcoProductDetail400" }, "404": { "$ref": "#/components/responses/GetTelcoProductDetail404" }, "406": { "$ref": "#/components/responses/GetTelcoProductDetail406" } }, "summary": "Get Telco Product Detail", "tags": [ "Telco Products" ], "x-version": "1" } }, "/telco/accounts/{serviceId}/usage": { "get": { "description": "Obtain a usage data from a particular _serviceId_.", "operationId": "getTelcoServiceUsage", "parameters": [ { "$ref": "#/components/parameters/PathServiceId" }, { "$ref": "#/components/parameters/QueryOldestDate" }, { "$ref": "#/components/parameters/QueryNewestDate" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" }, { "$ref": "#/components/parameters/HeaderXFAPIInteractionId" }, { "$ref": "#/components/parameters/HeaderXFAPIAuthDate" }, { "$ref": "#/components/parameters/HeaderXFAPICustomerIPAddress" }, { "$ref": "#/components/parameters/HeaderXCDSClientHeaders" } ], "responses": { "200": { "$ref": "#/components/responses/GetTelcoServiceUsage200" }, "400": { "$ref": "#/components/responses/GetTelcoServiceUsage400" }, "404": { "$ref": "#/components/responses/GetTelcoServiceUsage404" }, "406": { "$ref": "#/components/responses/GetTelcoServiceUsage406" }, "422": { "$ref": "#/components/responses/GetTelcoServiceUsage422" } }, "summary": "Get Usage For Telco Service", "tags": [ "Telco Account Service Usage" ], "x-scopes": [ "telco:billing:read" ], "x-version": "1" } }, "/telco/accounts/usage": { "get": { "description": "Obtain usage data for all services associated with the customer.", "operationId": "listTelcoServiceUsage", "parameters": [ { "$ref": "#/components/parameters/QueryOldestDate" }, { "$ref": "#/components/parameters/QueryNewestDate" }, { "$ref": "#/components/parameters/QueryPage" }, { "$ref": "#/components/parameters/QueryPageSize" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" }, { "$ref": "#/components/parameters/HeaderXFAPIInteractionId" }, { "$ref": "#/components/parameters/HeaderXFAPIAuthDate" }, { "$ref": "#/components/parameters/HeaderXFAPICustomerIPAddress" }, { "$ref": "#/components/parameters/HeaderXCDSClientHeaders" } ], "responses": { "200": { "$ref": "#/components/responses/ListTelcoServiceUsage200" }, "400": { "$ref": "#/components/responses/ListTelcoServiceUsage400" }, "406": { "$ref": "#/components/responses/ListTelcoServiceUsage406" }, "422": { "$ref": "#/components/responses/ListTelcoServiceUsage422" } }, "summary": "Get Usage", "tags": [ "Telco Account Service Usage" ], "x-scopes": [ "telco:billing:read" ], "x-version": "1" }, "post": { "description": "Obtain usage data for a specific service.", "operationId": "listTelcoUsageForSpecificService", "parameters": [ { "$ref": "#/components/parameters/QueryPage" }, { "$ref": "#/components/parameters/QueryPageSize" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" }, { "$ref": "#/components/parameters/HeaderXFAPIInteractionId" }, { "$ref": "#/components/parameters/HeaderXFAPIAuthDate" }, { "$ref": "#/components/parameters/HeaderXFAPICustomerIPAddress" }, { "$ref": "#/components/parameters/HeaderXCDSClientHeaders" } ], "requestBody": { "$ref": "#/components/requestBodies/RequestServiceIds" }, "responses": { "200": { "$ref": "#/components/responses/ListTelcoUsageForSpecificService200" }, "400": { "$ref": "#/components/responses/ListTelcoUsageForSpecificService400" }, "406": { "$ref": "#/components/responses/ListTelcoUsageForSpecificService406" }, "422": { "$ref": "#/components/responses/ListTelcoUsageForSpecificService422" } }, "summary": "Get Usage For Specific Telco Service", "tags": [ "Telco Account Service Usage" ], "x-scopes": [ "telco:billing:read" ], "x-version": "1" } }, "/telco/accounts": { "get": { "description": "Obtain the list of telco accounts available under the authorised consent.", "operationId": "listTelcoAccounts", "parameters": [ { "$ref": "#/components/parameters/QueryTelcoAccountOpenStatus" }, { "name": "updated-since", "description": "Only include accounts that have been updated after the specified date and time. If absent defaults to include all plans.", "in": "query", "required": false, "schema": { "type": "string" }, "x-cds-type": "DateString" }, { "$ref": "#/components/parameters/QueryPage" }, { "$ref": "#/components/parameters/QueryPageSize" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" }, { "$ref": "#/components/parameters/HeaderXFAPIInteractionId" }, { "$ref": "#/components/parameters/HeaderXFAPIAuthDate" }, { "$ref": "#/components/parameters/HeaderXFAPICustomerIPAddress" }, { "$ref": "#/components/parameters/HeaderXCDSClientHeaders" } ], "responses": { "200": { "$ref": "#/components/responses/ListTelcoAccounts200" }, "400": { "$ref": "#/components/responses/ListTelcoAccounts400" }, "406": { "$ref": "#/components/responses/ListTelcoAccounts406" }, "422": { "$ref": "#/components/responses/ListTelcoAccounts422" } }, "summary": "Get Telco Accounts", "tags": [ "Telco Accounts" ], "x-scopes": [ "telco:accounts.basic:read" ], "x-version": "1" } }, "/telco/accounts/{accountId}": { "get": { "description": "Obtain detailed information for a specific telco account.", "operationId": "getTelcoAccountDetail", "parameters": [ { "$ref": "#/components/parameters/PathAccountId" }, { "$ref": "#/components/parameters/HeaderXV" }, { "$ref": "#/components/parameters/HeaderXMinV" }, { "$ref": "#/components/parameters/HeaderXFAPIInteractionId" }, { "$ref": "#/components/parameters/HeaderXFAPIAuthDate" }, { "$ref": "#/components/parameters/HeaderXFAPICustomerIPAddress" }, { "$ref": "#/components/parameters/HeaderXCDSClientHeaders" } ], "responses": { "200": { "$ref": "#/components/responses/GetTelcoAccountDetail200" }, "400": { "$ref": "#/components/responses/GetTelcoAccountDetail400" }, "404": { "$ref": "#/components/responses/GetTelcoAccountDetail404" }, "406": { "$ref": "#/components/responses/GetTelcoAccountDetail406" } }, "summary": "Get Telco Account Detail", "tags": [ "Telco Accounts" ], "x-scopes": [ "telco:accounts.detail:read" ], "x-version": "1" } }, "/telco/accounts/{accountId}/payment-schedule": { "get": { "description": "Obtain the agreed payment schedule and details, if any, for a specific telco account.\n\nSome general notes about this endpoint:\n\n