Get a Call
const url = 'https://api.customer.onsim.uk/v1/calls/example';const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.customer.onsim.uk/v1/calls/example \ --header 'x-api-key: <x-api-key>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The ID of the Call, encoded for a path.
Responses
Section titled “Responses”OK
One conversation as the caller lives it, from the first ring to the last hang-up, with every Leg that it takes.
object
The ID of the Call. It can hold @ and :, so encode it in a path.
inbound: from outside to you. outbound: from you to outside. internal: between two of your extensions.
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.
Who makes the Call.
object
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.
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.
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.
The first person who speaks to the caller. Only an answered Call has it.
object
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.
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.
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.
When the Call starts.
When the Call ends.
What we charge for the Call. A Call has none when none of its Legs has a charge.
object
The sum of the charges of all Legs of the Call, with the duplicates and the artefacts.
The currency of amount, as an ISO 4217 code, such as GBP.
The Legs of the Call, as a tree. The first is the start of the Call.
One step of a Call that tries to reach one party. Legs nest: the Leg that causes another is its parent.
object
The ID of the Leg. It holds spaces, so encode it in a path.
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.
Who the Leg tries to reach.
object
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.
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.
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.
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.
When the Leg starts. For a ring that nobody answers, this is when the phone starts to ring.
When the Leg connects. A Leg that nobody answers has none.
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.
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.
True when the Leg has a Recording.
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.
object
The money that we charge. 0 when the tariff rates the use at no cost.
The currency of amount, as an ISO 4217 code, such as GBP.
The units that we bill, after the tariff rounds them. For data, the tariff rounds up to the next 20 KiB.
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.
The unit of quantity and used_quantity: seconds for a Leg, kib for a Data Session.
What the tariff rates the use as. A Leg to one of your extensions has none.
object
The entry that the tariff matches: a prefix of the dialled number, such as 447968, or a data zone, such as MXGDATAZ1GBR.
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.
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.
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.
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.
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.
Example
{ "direction": "inbound", "outcome": "answered", "legs": [ { "outcome": "answered", "charge": { "unit": "seconds" }, "unlinked": true } ]}The request is not valid
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}The API key is missing or not valid, or: This request is not permitted
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}No such resource
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}The request is too large
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}Too many requests, or: The daily quota is used up
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}The request failed
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}Your records are not available now
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}The request took too long
An error, as RFC 9457 Problem Details.
object
A URI that names the kind of error. It is also a page of the docs.
A short summary of the kind of error.
The HTTP status.
What went wrong in this request.
Each parameter that is not valid. Only an invalid-request error has it.
object
The parameter that is not valid.
Why it is not valid.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": [ { "field": "example", "detail": "example" } ]}