Calls

Call from your numbers (Marsial rings the person and connects them with your phone, a SIP address or an AI voice agent), read the call history with recordings and transcripts, and estimate what a call costs.

Call history of a number

GET/v1/phone-numbers/{id}/calls

Inbound and outbound, newest first.

Parameters

idstringrequired
cursorstring
directionstring
Values: inbound · outbound
limitinteger
max 100

Response 200

data

itemsobject[]required
items
- idstringrequired
  call_…
- numberIdstringrequired
- channelstringrequired
  pstn (phone).
- directionstringrequired
  Values: inbound · outbound
- fromstringrequired
- tostringrequired
- statusstringrequired
  dialing, ringing, answered, ended, failed, no_answer…
- endReasonstring
- durationSecondsnumber
- recordingbooleanrequired
- transcriptSnippetstring
- transcriptobject[]
  Only on GET /calls/{id}.
  transcript
  - textstringrequired
  - atstring
- costnumber
  Euros.
- startedAtstring
- endedAtstring
nextCursorstring | nullrequired
Send it as cursor for the next page; null on the last one.

curl "https://api.marsial.dev/v1/phone-numbers/num_…/calls" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/phone-numbers/num_…/calls', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/phone-numbers/num_…/calls",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Call someone

POST/v1/calls

Marsial rings to from your number and, when they answer, connects them with forwardTo (your phone, a SIP address or an AI voice agent) or the number's inbound destination.

Body

numberIdstringrequired
The number that calls (num_…).
tostringrequired
Who to call.
forwardTostring
Who to connect them with when they answer; the number's inbound destination otherwise.
max 500
greetingstring
Spoken to them when they answer, before connecting.
max 500
recordboolean
transcribeboolean
idempotencyKeystring
max 100

Response 201

data

idstringrequired
call_…
numberIdstringrequired
channelstringrequired
pstn (phone).
directionstringrequired
Values: inbound · outbound
fromstringrequired
tostringrequired
statusstringrequired
dialing, ringing, answered, ended, failed, no_answer…
endReasonstring
durationSecondsnumber
recordingbooleanrequired
transcriptSnippetstring
transcriptobject[]
Only on GET /calls/{id}.
transcript
- textstringrequired
- atstring
costnumber
Euros.
startedAtstring
endedAtstring

curl -X POST "https://api.marsial.dev/v1/calls" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numberId": "num_…",
    "to": "+447700900123",
    "forwardTo": "tel:+447700900456"
  }'

const res = await fetch('https://api.marsial.dev/v1/calls', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "numberId": "num_…",
    "to": "+447700900123",
    "forwardTo": "tel:+447700900456"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "numberId": "num_…",
        "to": "+447700900123",
        "forwardTo": "tel:+447700900456"
    },
)
data = res.json()["data"]

What a call would cost

GET/v1/calls/estimate

Parameters

tostringrequired
minutesinteger
Default: 5max 600
numberIdstring
The number that would call: the answer then says whether it can reach to.

Response 200

data

destinationCountrystring
minutesintegerrequired
max 9,007,199,254,740,991
perMinutenumberrequired
Euros per minute.
totalnumberrequired
Euros for the minutes asked.
reachableboolean
With numberId: false when that number only calls within its own country.
notestring

curl "https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/estimate?to=%2B447700900123&minutes=5",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Get a call

GET/v1/calls/{id}

With its transcript when transcription was on.

Parameters

idstringrequired

Response 200

data

idstringrequired
call_…
numberIdstringrequired
channelstringrequired
pstn (phone).
directionstringrequired
Values: inbound · outbound
fromstringrequired
tostringrequired
statusstringrequired
dialing, ringing, answered, ended, failed, no_answer…
endReasonstring
durationSecondsnumber
recordingbooleanrequired
transcriptSnippetstring
transcriptobject[]
Only on GET /calls/{id}.
transcript
- textstringrequired
- atstring
costnumber
Euros.
startedAtstring
endedAtstring

curl "https://api.marsial.dev/v1/calls/call_…" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/calls/call_…', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/call_…",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Recording of a call

GET/v1/calls/{id}/recording

A link to the MP3 that works for 15 minutes. Only calls recorded (setting or per call).

Parameters

idstringrequired

Response 200

data

urlstringrequired
Works for 15 minutes.

curl "https://api.marsial.dev/v1/calls/call_…/recording" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/recording', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/calls/call_…/recording",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Hang up

POST/v1/calls/{id}/end

Parameters

idstringrequired

Response 204

No content

curl -X POST "https://api.marsial.dev/v1/calls/call_…/end" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/end', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls/call_…/end",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Transfer a live call

POST/v1/calls/{id}/transfer

To another phone (+E164) or a SIP address; the call leaves your control.

Parameters

idstringrequired

Body

tostringrequired

Response 204

No content

curl -X POST "https://api.marsial.dev/v1/calls/call_…/transfer" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900789"
  }'

const res = await fetch('https://api.marsial.dev/v1/calls/call_…/transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+447700900789"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/calls/call_…/transfer",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "to": "+447700900789"
    },
)
data = res.json()["data"]