{ "openapi": "3.1.0", "info": { "title": "ONSIM Customer API", "version": "1.0.0", "description": "A read-only API for a Customer's own Users, Hunt Groups, IVRs, Numbers, Services, Calls with their Recordings, and Data Sessions.\n\nDownload this OpenAPI document: [openapi.json](/openapi.json)." }, "servers": [ { "url": "https://api.customer.onsim.uk" } ], "externalDocs": { "description": "The docs of the Customer API", "url": "https://docs.customer.onsim.uk" }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Users", "description": "A User is a person on your team. You see your Users in app.onsim under Team." }, { "name": "Hunt Groups", "description": "A Hunt Group is one destination that rings a set of Identities: Users, IVRs and other Hunt Groups." }, { "name": "IVRs", "description": "An IVR plays a menu and sends the caller on by the key they press. An IVR is not a User." }, { "name": "Numbers", "description": "A Number is a phone number that you own. An extension takes its calls, and Users can show it on the calls that they make." }, { "name": "Services", "description": "A Service is something that an Identity has: a plan, a data allowance, call recording. An Identity is a User, a Hunt Group or an IVR." }, { "name": "Calls", "description": "A Call is one conversation as the caller lives it, with every Leg that it takes. A Leg can have a Recording." }, { "name": "Data Sessions", "description": "A Data Session is the mobile data that one of your SIMs used in about one hour, as the mobile network reports it. It has one time, and no start or end." } ], "paths": { "/v1/users": { "get": { "operationId": "users-list", "summary": "List Users", "tags": [ "Users" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserSummary" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/users/{id}": { "get": { "operationId": "users-get", "summary": "Get a User", "tags": [ "Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the resource.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/hunt-groups": { "get": { "operationId": "hunt-groups-list", "summary": "List Hunt Groups", "tags": [ "Hunt Groups" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HuntGroupSummary" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/hunt-groups/{id}": { "get": { "operationId": "hunt-groups-get", "summary": "Get a Hunt Group", "tags": [ "Hunt Groups" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the resource.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuntGroup" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/ivrs": { "get": { "operationId": "ivrs-list", "summary": "List IVRs", "tags": [ "IVRs" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IvrSummary" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/ivrs/{id}": { "get": { "operationId": "ivrs-get", "summary": "Get an IVR", "tags": [ "IVRs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the resource.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ivr" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/numbers": { "get": { "operationId": "numbers-list", "summary": "List Numbers", "tags": [ "Numbers" ], "parameters": [ { "name": "state", "in": "query", "required": true, "description": "The state of the Numbers to list. One request gives the Numbers of one state.", "schema": { "type": "string", "enum": [ "regular", "legacy", "unassigned" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NumberSummary" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/numbers/{id}": { "get": { "operationId": "numbers-get", "summary": "Get a Number", "tags": [ "Numbers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The digits of the Number, with the country code and no plus.", "schema": { "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Number" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/services/{id}": { "get": { "operationId": "services-get", "summary": "Get the Services of an Identity", "tags": [ "Services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the Identity: of a User, a Hunt Group or an IVR.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calls": { "get": { "operationId": "calls-list", "summary": "List Calls", "tags": [ "Calls" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "The list has the Calls that start at this time or later.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "The list has the Calls that start before this time. It is 31 days after `from` at most.", "schema": { "type": "string", "format": "date-time" } }, { "name": "direction", "in": "query", "required": false, "description": "Only the Calls of this direction.", "schema": { "type": "string", "enum": [ "inbound", "outbound", "internal" ] } }, { "name": "outcome", "in": "query", "required": false, "description": "Only the Calls of this outcome. It is the outcome of the Call, not of one party.", "schema": { "type": "string", "enum": [ "answered", "missed", "abandoned", "unanswered" ] } }, { "name": "extension", "in": "query", "required": false, "description": "Only the Calls that involve this extension, as the caller or as the party of a Leg.", "schema": { "type": "string", "minLength": 1 } }, { "name": "number", "in": "query", "required": false, "description": "Only the Calls that involve this phone number, as the caller or as the party of a Leg. Give it in any usual form: `+442079460123`, `020 7946 0123` or `442079460123`. A number with no country code is a UK number. Encode a `+` as `%2B`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "Link": { "description": "Only when the window has more Calls than one answer holds. It gives the request for the next ones, as `; rel=\"next\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calls/{id}": { "get": { "operationId": "calls-get", "summary": "Get a Call", "tags": [ "Calls" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the Call, encoded for a path.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Call" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calls/{id}/recordings": { "get": { "operationId": "recordings-list", "summary": "List the recorded Legs of a Call", "tags": [ "Calls" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the Call, encoded for a path.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Recording" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calls/{id}/recordings/{leg_id}": { "get": { "operationId": "recordings-get", "summary": "Get a recorded Leg of a Call", "tags": [ "Calls" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the call of the Leg, encoded for a path: the `call_id` of the Leg when it has one, or else the `id` of its Call.", "schema": { "type": "string", "minLength": 1 } }, { "name": "leg_id", "in": "path", "required": true, "description": "The ID of the Leg, encoded for a path.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-sessions": { "get": { "operationId": "data-sessions-list", "summary": "List Data Sessions", "tags": [ "Data Sessions" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "The list has the Data Sessions at this time or later.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "The list has the Data Sessions before this time. It is 31 days after `from` at most.", "schema": { "type": "string", "format": "date-time" } }, { "name": "extension", "in": "query", "required": false, "description": "Only the Data Sessions of the SIM with this extension.", "schema": { "type": "string", "minLength": 1 } }, { "name": "account", "in": "query", "required": false, "description": "Only the Data Sessions of the SIM of this account, for a SIM with no extension.", "schema": { "type": "string", "minLength": 1 } }, { "name": "roaming", "in": "query", "required": false, "description": "`true`: only the Data Sessions abroad. `false`: only those at home. With no `roaming`, the list has both.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "headers": { "Link": { "description": "Only when the window has more Data Sessions than one answer holds. It gives the request for the next ones, as `; rel=\"next\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataSession" } } } } }, "400": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The API key is missing or not valid, or: This request is not permitted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The request is too large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests, or: The daily quota is used up", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "The request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Your records are not available now", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "504": { "description": "The request took too long", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "The Customer's API Key." } }, "schemas": { "Call": { "description": "One conversation as the caller lives it, from the first ring to the last hang-up, with every Leg that it takes.", "type": "object", "properties": { "id": { "description": "The ID of the Call. It can hold `@` and `:`, so encode it in a path.", "type": "string" }, "direction": { "description": "`inbound`: from outside to you. `outbound`: from you to outside. `internal`: between two of your extensions.", "type": "string", "enum": [ "inbound", "outbound", "internal" ] }, "outcome": { "description": "`answered`: a person speaks to the caller. `missed`: an inbound Call rings a User or a Hunt Group, and nobody answers. `abandoned`: the caller of an inbound Call hangs up in an IVR, before anything rings. `unanswered`: nobody answers an outbound or an internal Call.", "type": "string", "enum": [ "answered", "missed", "abandoned", "unanswered" ] }, "from": { "description": "Who makes the Call.", "$ref": "#/components/schemas/Party" }, "answered_by": { "description": "The first person who speaks to the caller. Only an answered Call has it.", "$ref": "#/components/schemas/Party" }, "started_at": { "description": "When the Call starts.", "type": "string", "format": "date-time" }, "ended_at": { "description": "When the Call ends.", "type": "string", "format": "date-time" }, "charge": { "description": "What we charge for the Call. A Call has none when none of its Legs has a charge.", "$ref": "#/components/schemas/CallCharge" }, "legs": { "description": "The Legs of the Call, as a tree. The first is the start of the Call.", "type": "array", "items": { "$ref": "#/components/schemas/Leg" } } }, "required": [ "id", "direction", "outcome", "from", "started_at", "ended_at", "legs" ] }, "CallCharge": { "description": "What we charge for a whole Call.", "type": "object", "properties": { "amount": { "description": "The sum of the charges of all Legs of the Call, with the duplicates and the artefacts.", "type": "number" }, "currency": { "description": "The currency of `amount`, as an ISO 4217 code, such as `GBP`.", "type": "string" } }, "required": [ "amount", "currency" ] }, "Charge": { "description": "What we charge for one Leg or one Data Session. A subscription fee, a credit or a payment is not a charge.", "type": "object", "properties": { "amount": { "description": "The money that we charge. `0` when the tariff rates the use at no cost.", "type": "number" }, "currency": { "description": "The currency of `amount`, as an ISO 4217 code, such as `GBP`.", "type": "string" }, "quantity": { "description": "The units that we bill, after the tariff rounds them. For data, the tariff rounds up to the next 20 KiB.", "type": "integer" }, "used_quantity": { "description": "The units that we measure, before the tariff rounds them. Only a Leg has it: a Data Session gives the same value as `bytes`. A Leg that passes the call on stays bridged to the end of the Call, and we measure that time too.", "type": "integer" }, "unit": { "description": "The unit of `quantity` and `used_quantity`: `seconds` for a Leg, `kib` for a Data Session.", "type": "string", "enum": [ "seconds", "kib" ] }, "destination": { "description": "What the tariff rates the use as. A Leg to one of your extensions has none.", "$ref": "#/components/schemas/Destination" } }, "required": [ "amount", "currency", "unit" ] }, "DataSession": { "description": "The mobile data that one of your SIMs used in about one hour. It is a reading, not a connection.", "type": "object", "properties": { "id": { "description": "The ID of the Data Session.", "type": "string" }, "sim": { "description": "The SIM that used the data: its `extension`, or its `account` when it has no extension.", "$ref": "#/components/schemas/Party" }, "at": { "description": "When the network read the use. A Data Session has one time, and no start or end.", "type": "string", "format": "date-time" }, "bytes": { "description": "The data that the SIM used, in bytes, in both directions.", "type": "integer" }, "country": { "description": "The country where the SIM used the data, as an ISO 3166-1 alpha-3 code, such as `GBR`.", "type": "string" }, "charge": { "description": "What we charge for the data. A Data Session has none when its record has no amount.", "$ref": "#/components/schemas/Charge" } }, "required": [ "id", "sim", "at", "bytes" ] }, "Destination": { "description": "What the tariff rates the use as.", "type": "object", "properties": { "prefix": { "description": "The entry that the tariff matches: a prefix of the dialled number, such as `447968`, or a data zone, such as `MXGDATAZ1GBR`.", "type": "string" }, "description": { "description": "The name of that entry in the tariff, such as `UK - Mobile - T-Mobile` or `Mobile Data (UK)`. It says why the price is what it is.", "type": "string" }, "country": { "description": "The country of that entry, as an ISO 3166-1 alpha-3 code, such as `GBR`. For a Leg, it is the country of the dialled number, not of the caller.", "type": "string" } }, "required": [ "prefix", "description" ] }, "HuntGroup": { "description": "One destination that rings a set of Identities.", "type": "object", "properties": { "id": { "description": "The ID of the Hunt Group. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" }, "ringing_strategy": { "description": "The order in which the Hunt Group rings its members.", "type": "string", "enum": [ "order", "random", "simultaneous", "least_used" ] }, "caller_id": { "description": "What a member sees when the Hunt Group rings them. `caller`: the number and the name of the caller. `caller_number`: the number of the caller and the name of the Hunt Group. `group`: the number and the name of the Hunt Group.", "type": "string", "enum": [ "caller", "caller_number", "group" ] }, "pickup_allowed": { "description": "True when another extension can pick up a call that rings a member.", "type": "boolean" }, "members": { "description": "The extensions that the Hunt Group rings.", "type": "array", "items": { "$ref": "#/components/schemas/HuntGroupMember" } } }, "required": [ "id", "extension", "label", "members" ] }, "HuntGroupMember": { "description": "An extension that a Hunt Group rings, and how the group rings it.", "type": "object", "properties": { "extension": { "description": "The extension that the Hunt Group rings: that of a User, of an IVR or of another Hunt Group.", "type": "string" }, "active": { "description": "False when the Hunt Group does not ring this member.", "type": "boolean" }, "position": { "description": "The place of the member in the order of ringing. Members can share a place.", "type": "integer" }, "ring_delay": { "description": "The seconds before the member starts to ring.", "type": "integer" }, "ring_time": { "description": "The seconds that the member rings.", "type": "integer" }, "forwarding": { "description": "True when the call forwarding of the member applies to a call from the Hunt Group.", "type": "boolean" } }, "required": [ "extension", "active", "forwarding" ] }, "HuntGroupSummary": { "description": "A Hunt Group, as a list gives it. Get the Hunt Group for its members and how it rings.", "type": "object", "properties": { "id": { "description": "The ID of the Hunt Group. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" } }, "required": [ "id", "extension", "label" ] }, "Ivr": { "description": "A menu that plays to the caller and sends them on by the key they press.", "type": "object", "properties": { "id": { "description": "The ID of the IVR. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" }, "menus": { "description": "The menus of the IVR. An IVR that plays no menu has none.", "type": "array", "items": { "$ref": "#/components/schemas/IvrMenu" } } }, "required": [ "id", "extension", "label" ] }, "IvrKey": { "description": "One step of a menu: what starts it, and what the menu then does.", "type": "object", "properties": { "key": { "description": "What starts the step: a key from `0` to `9`, `*` or `#`. Also `timeout` when the caller presses no key, `inactive` when the menu is not active, and `fax`.", "type": "string" }, "action": { "description": "What the menu does: `transfer`, `menu`, `queue`, `voicemail`, `directory`, `dial_extension`, `make_call`, `hang_up`, `none` or `other`. More values can come.", "type": "string" }, "extension": { "description": "For `transfer` to an extension: the extension that the menu dials.", "type": "string" }, "number": { "description": "For `transfer` to an outside number: the digits of that number.", "type": "string" }, "menu": { "description": "For `menu`: the name of the menu that comes next.", "type": "string" } }, "required": [ "key", "action" ] }, "IvrMenu": { "description": "A menu that an IVR plays.", "type": "object", "properties": { "name": { "description": "The name of the menu. Every IVR has a menu with the name `ROOT`, which a caller hears first. A step with the action `menu` goes to another.", "type": "string" }, "active": { "description": "When the menu is active, in words: `Always`, or a schedule.", "type": "string" }, "keys": { "description": "The steps of the menu.", "type": "array", "items": { "$ref": "#/components/schemas/IvrKey" } } }, "required": [ "name", "keys" ] }, "IvrSummary": { "description": "An IVR, as a list gives it. Get the IVR for its menus.", "type": "object", "properties": { "id": { "description": "The ID of the IVR. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" } }, "required": [ "id", "extension", "label" ] }, "Leg": { "description": "One step of a Call that tries to reach one party. Legs nest: the Leg that causes another is its parent.", "type": "object", "properties": { "id": { "description": "The ID of the Leg. It holds spaces, so encode it in a path.", "type": "string" }, "call_id": { "description": "The ID of the call that this Leg comes from, only when it is not the `id` of the Call. An attended transfer joins a second call into the Call. Use this ID to get the Recording of the Leg.", "type": "string" }, "party": { "description": "Who the Leg tries to reach.", "$ref": "#/components/schemas/Party" }, "outcome": { "description": "How the Leg ends. `answered` means that the Leg connects, also to an IVR or a mailbox. It does not mean that a person speaks: the `outcome` of the Call says that. `voicemail`: voicemail takes the Leg. `busy`: the phone is busy. `answered_elsewhere`: another phone of the same ring takes the call. `unreachable`: the phone is offline. `unanswered`: every other end.", "type": "string", "enum": [ "answered", "voicemail", "busy", "answered_elsewhere", "unreachable", "unanswered" ] }, "started_at": { "description": "When the Leg starts. For a ring that nobody answers, this is when the phone starts to ring.", "type": "string", "format": "date-time" }, "answered_at": { "description": "When the Leg connects. A Leg that nobody answers has none.", "type": "string", "format": "date-time" }, "passed_on_at": { "description": "When a Leg under this one takes the call over. The part of this Leg ends here. A Leg that keeps the call has none.", "type": "string", "format": "date-time" }, "ended_at": { "description": "When the Leg closes. A Leg that passes the call on stays open to the end of the Call, so do not use `ended_at` less `started_at` as its length. The part of the Leg is from `answered_at` to `passed_on_at`, or to `ended_at` when it has no `passed_on_at`.", "type": "string", "format": "date-time" }, "recorded": { "description": "True when the Leg has a Recording.", "type": "boolean" }, "charge": { "description": "What we charge for the Leg. A Leg has none when the call record has no amount. A duplicate and an artefact have their own `charge`. To get the charge of one step, add the charges of the duplicates and artefacts next to its Leg.", "$ref": "#/components/schemas/Charge" }, "unlinked": { "description": "Only on a Leg whose place in the Call is not known. It is next to the first Leg, not under the Leg that caused it.", "type": "boolean", "const": true }, "duplicate_of": { "description": "Only on a duplicate: the ID of the Leg that it duplicates. A call between two of your accounts has two legs. One is on the account that dials, and one is on the account that the call reaches. The Leg is the one that the call reaches. The duplicate is next to it, with no Legs under it. It has the `charge` of the account that dials. Its `outcome` is the outcome of the account that dials, so it can read `answered` in a missed Call. Leave out the duplicates to show each step one time. A duplicate can have a Recording of the same conversation.", "type": "string" }, "artefact_of": { "description": "Only on an artefact: the ID of the IVR Leg that it is next to. An IVR makes an extra leg on its own account, with a withheld caller. It shows no step of its own, but it can have a charge. The artefact is next to the IVR Leg, with no Legs under it. Leave out the artefacts to show each step one time.", "type": "string" }, "legs": { "description": "The Legs that this Leg causes, in the order that they start.", "type": "array", "items": { "$ref": "#/components/schemas/Leg" } } }, "required": [ "id", "party", "outcome", "started_at", "ended_at", "recorded", "legs" ] }, "Number": { "description": "A phone number that you own.", "type": "object", "properties": { "id": { "description": "The ID of the Number: its digits, with the country code and no plus.", "type": "string" }, "number": { "description": "The digits of the Number, with the country code and no plus.", "type": "string" }, "country": { "description": "The country of the Number, in English. A number of no one country has none.", "type": "string" }, "area": { "description": "The area of the Number.", "type": "string" }, "type": { "description": "`mobile` for a mobile number. `landline` for every other.", "type": "string", "enum": [ "mobile", "landline" ] }, "state": { "description": "`regular` when an extension takes the calls to the Number. `legacy` for a Number from before app.onsim, which cannot move to another holder. `unassigned` when nothing takes its calls.", "type": "string", "enum": [ "regular", "legacy", "unassigned" ] }, "inbound": { "description": "What takes the calls to the Number: a User, a Hunt Group or an IVR, by its extension. A line with no extension shows by its `account`. A Number that nothing takes the calls of has none.", "$ref": "#/components/schemas/Party" }, "outbound": { "description": "Each User that shows the Number on the calls that they make, by its extension.", "type": "array", "items": { "$ref": "#/components/schemas/Party" } } }, "required": [ "id", "number", "type", "state", "outbound" ] }, "NumberSummary": { "description": "A Number, as a list gives it. Get the Number for what takes its calls and who shows it.", "type": "object", "properties": { "id": { "description": "The ID of the Number: its digits, with the country code and no plus.", "type": "string" }, "number": { "description": "The digits of the Number, with the country code and no plus.", "type": "string" }, "country": { "description": "The country of the Number, in English. A number of no one country has none.", "type": "string" }, "area": { "description": "The area of the Number.", "type": "string" }, "type": { "description": "`mobile` for a mobile number. `landline` for every other.", "type": "string", "enum": [ "mobile", "landline" ] }, "state": { "description": "`regular` when an extension takes the calls to the Number. `legacy` for a Number from before app.onsim, which cannot move to another holder. `unassigned` when nothing takes its calls.", "type": "string", "enum": [ "regular", "legacy", "unassigned" ] } }, "required": [ "id", "number", "type", "state" ] }, "Party": { "description": "Who takes part in something: who makes a Call, who a Leg reaches, who takes the calls of a Number, which SIM uses data. One of your extensions has `extension`. An outside party has `number`. One of your lines with no extension has `account`. A User who hides their number has `extension` and `number`. A party that the record does not name has nothing.", "type": "object", "properties": { "extension": { "description": "The extension, for a party of your own: a User, a Hunt Group or an IVR. Look it up in their lists to learn which, and its name.", "type": "string" }, "number": { "description": "The digits of a phone number, for an outside party. `withheld` when the party hides it. A feature code such as `*40` is here too.", "type": "string" }, "account": { "description": "The name of one of your own lines that has no extension, such as a SIM in a router. app.onsim shows it in the Account column of its logs.", "type": "string" } } }, "Price": { "description": "What a Service costs for each billing period, with no tax. It is not a Charge, which is the money for usage.", "type": "object", "properties": { "amount": { "description": "The money for each period, with no tax. `0` for a Service that costs nothing.", "type": "number" }, "currency": { "description": "The currency of `amount`, as an ISO 4217 code, such as `GBP`.", "type": "string" }, "period": { "description": "The billing period of `amount`. More values can come.", "type": "string", "enum": [ "month" ] } }, "required": [ "amount", "currency", "period" ] }, "Problem": { "description": "An error, as RFC 9457 Problem Details.", "type": "object", "properties": { "type": { "description": "A URI that names the kind of error. It is also a page of the docs.", "type": "string" }, "title": { "description": "A short summary of the kind of error.", "type": "string" }, "status": { "description": "The HTTP status.", "type": "integer" }, "detail": { "description": "What went wrong in this request.", "type": "string" }, "errors": { "description": "Each parameter that is not valid. Only an invalid-request error has it.", "type": "array", "items": { "type": "object", "properties": { "field": { "description": "The parameter that is not valid.", "type": "string" }, "detail": { "description": "Why it is not valid.", "type": "string" } }, "required": [ "field", "detail" ] } } }, "required": [ "type", "title", "status" ] }, "Recording": { "description": "The audio of one Leg. A Call can have none, one or several.", "type": "object", "properties": { "leg_id": { "description": "The ID of the Leg of the Recording.", "type": "string" }, "expires_at": { "description": "When the links stop. Ask again for new links.", "type": "string", "format": "date-time" }, "files": { "description": "The parts of the Recording, in the order to play them. Most Recordings have one.", "type": "array", "items": { "$ref": "#/components/schemas/RecordingFile" } } }, "required": [ "leg_id", "expires_at", "files" ] }, "RecordingFile": { "description": "One part of a Recording.", "type": "object", "properties": { "url": { "description": "A link to the audio, as a WAV file. It works until `expires_at`.", "type": "string" } }, "required": [ "url" ] }, "Records": { "description": "What a recording Service records.", "type": "object", "properties": { "calls": { "description": "True when the calls of the Identity are recorded.", "type": "boolean" }, "messages": { "description": "True when the messages of the Identity are recorded. It is not there when we cannot read it at the time of the request.", "type": "boolean" } }, "required": [ "calls" ] }, "Service": { "description": "Something that an Identity has: a plan, a data allowance, call recording.", "type": "object", "properties": { "id": { "description": "The ID of the Service. It is the same for every Identity that has the Service.", "type": "integer" }, "type": { "description": "The section of the Services tab that holds it: `plan`, `data`, `recording`, `ai_insights` or `other`. More values can come.", "type": "string" }, "name": { "description": "The name, as app.onsim shows it.", "type": "string" }, "description": { "description": "What the Service gives, as app.onsim shows it.", "type": "string" }, "status": { "description": "`pending` when the Service has not started yet. A pending Service takes the place of an active one of the same type.", "type": "string", "enum": [ "active", "pending" ] }, "starts_at": { "description": "When the Service started, or will start. It is not there when the start is not known.", "type": "string", "format": "date-time" }, "ends_at": { "description": "When the Service stops. A Service with no end runs until someone changes it.", "type": "string", "format": "date-time" }, "records": { "description": "Only on a recording Service: what the Identity records.", "$ref": "#/components/schemas/Records" }, "price": { "description": "What the Service costs. It is not there when the Service has no fee, as for a Hunt Group.", "$ref": "#/components/schemas/Price" } }, "required": [ "id", "type", "name", "status" ] }, "User": { "description": "A person on your team. Each User has an extension that others dial.", "type": "object", "properties": { "id": { "description": "The ID of the User. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" }, "first_name": { "description": "The first name of the person who holds the User, as their account keeps it. It can differ from `label`.", "type": "string" }, "last_name": { "description": "The last name of the person who holds the User, as their account keeps it.", "type": "string" }, "email": { "description": "The email address of the person who holds the User, as their account keeps it.", "type": "string" } }, "required": [ "id", "extension", "label" ] }, "UserSummary": { "description": "A User, as a list gives it. Get the User for the details of the person.", "type": "object", "properties": { "id": { "description": "The ID of the User. It does not change when the extension does.", "type": "integer" }, "extension": { "description": "What others dial to reach it. It can change.", "type": "string" }, "label": { "description": "The label of the extension, as app.onsim and the call records show it. It is not the name of a person.", "type": "string" } }, "required": [ "id", "extension", "label" ] } } } }