NAV Navbar

Introduction

Welcome to the Zevvle API! It's the same one we use for our mobile apps, and you can use it to access your account, SIM cards and call records, as well as look up pricing for Zevvle, with more services en-route.

If you need help or want to show what you've built, the developers category on our forum is a good place to start.

Authentication

# To authorize, pass the correct header with each request:

curl "https://api.zevvle.com/$api_endpoint" \
  -H "Authorization: Bearer $secret_token"

We use bearer tokens for access to the Zevvle API. You can login and get yours at developers.zevvle.com.

Except for the pricing endpoint, you need to include the token in a header with every request like this:

Authorization: Bearer $secret_token

Log out

curl -X DELETE "https://api.zevvle.com/auth" \
  -H "Authorization: Bearer $secret_token"

To log out and destroy your token, use this endpoint.

Definition

DELETE https://api.zevvle.com/auth

Pricing

Retrieve pricing

curl "https://api.zevvle.com/pricing/FRA"

Example response:

{
  "voice": 3,
  "voicemail": 0,
  "incoming": 0,
  "sms": 3,
  "mms": 3,
  "megabyte": 0.1953125,
  "gigabyte": 200,
  "description": "Pricing within France."
}

Returns the pricing for any country, or between 2 countries.

Definition

GET https://api.zevvle.com/pricing/$origin_iso3/$destination_iso3

The destination_iso3 is optional and defaults to origin_iso3 which is also optional and defaults to GBR. ISO2 country codes work as well.

All prices are in GBP pence, and you can use this endpoint without authentication.

Accounts

Retrieve an account

curl "https://api.zevvle.com/accounts/$account_id" \
  -H "Authorization: Bearer $secret_token"

  # To expand the users and/or sim_cards: ?expand[]=users&expand[]=sim_cards

Example response:

{
  "id": "acc_4xEJ7pl6WNB8BjTxnmvUQ6Lr",
  "created_at": "2019-08-02T01:13:03.774Z",
  "balance": "1874.052415135502804626156",
  "billing_date": "2019-09-06T12:00:00.000Z",
  "users": [
    "user_QhBebSdWZXIzHTvfeVAZc8Ko"
  ],
  "sim_cards": [
    "sim_9hfPiB8wKpj2VTfpLbRYz2YO",
    "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
    "sim_sLpMrC4tFtptR1N28HteeMTE"
  ]
}

Returns the details for your account.

Definition

GET https://api.zevvle.com/accounts/$account_id

Request parameters

expand[]
Optional
Can be users and/or sim_cards.

Response parameters

balance The account balance in GBP pence (as a string).
billing_date The monthly billing date for the account (the year and month are irrelevant).
users A list of users for the account (expandable, see above).
sim_cards A list of sim_cards for the account (expandable, see above).

Users

Retrieve a user

curl "https://api.zevvle.com/users/$user_id" \
  -H "Authorization: Bearer $secret_token"

Example response:

{
  "id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
  "created_at": "2019-08-02T01:10:42.367Z",
  "account_id": "acc_4xEJ7pl6WNB8BjTxnmvUQ6Lr",
  "email": "nick@zevvle.com",
  "name": "Nick Goodall",
  "account_owner": true,
  "referral_id": "JN2PQF",
  "referrals": 1,
  "sim_cards": [
    "sim_9hfPiB8wKpj2VTfpLbRYz2YO",
    "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
    "sim_sLpMrC4tFtptR1N28HteeMTE"
  ]
}

Returns the details of a user.

Definition

GET https://api.zevvle.com/users/$user_id

Request parameters

expand[]
Optional
Can be sim_cards.

Response parameters

account_owner Whether or not the user is an account owner.
referral_id The code for referrals, used like this: https://zevvle.com?rid=$referral_id.
referrals
Current user only
How many people you've referred to Zevvle.
sim_cards A list of sim_cards for the user (expandable, see above).

SIM Cards

Retrieve a sim card

curl "https://api.zevvle.com/sim_cards/$sim_card_id" \
  -H "Authorization: Bearer $secret_token"

Example response:

{
  "id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
  "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
  "msisdn": "+447922306107",
  "iccid": "8944122600601770672",
  "emoji": "🚀",
  "status": "active",
  "name": "🧀🍰",
  "activated_at": "2019-07-05T12:57:02.960Z",
  "settings": {
      "sms": true,
      "mms": true,
      "voice_geographic": true,
      "voice_mobile": true,
      "voicemail": false,
      "call_holding": true,
      "call_waiting": true,
      "calling_line_identity": true,
      "voice_sms_bundle": false,
      "international": "roaming",
      "eea_data": true,
      "eea_sms": false,
      "eea_outgoing_call": false,
      "eea_incoming_call": false,
      "data": "4G"
  },
  "modifying": false
}

Returns the details for a sim card.

Definition

GET https://api.zevvle.com/sim_cards/$sim_card_id

Response parameters

msisdn The international phone number of the SIM, or Mobile Station International Subscriber Directory Number.
iccid The serial number for the SIM, or Integrated Circuit Card Identifier.
emoji The emoji assigned to the SIM card batch.
status The status of the SIM; can be active, suspended or terminated.
name The name of the SIM (defaults to the msisdn in national format).
settings An object of the SIM's settings. See below for options.
modifying Whether or not the SIM card is currently being modified.

List sim cards

curl "https://api.zevvle.com/sim_cards" \
  -H "Authorization: Bearer $secret_token"

Example response:

[
  {
    "id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
    "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
    "msisdn": "+447922306107",
    "iccid": "8944122600601770672",
    "emoji": "🚀",
    "status": "active",
    "name": "🧀🍰",
    "activated_at": "2019-07-05T12:57:02.960Z",
    "settings": ...,
    "modifying": false
  },
  {
    "id": "sim_9hfPiB8wKpj2VTfpLbRYz2YO",
    "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
    "msisdn": "+447474747474",
    "iccid": "+8944004770932261152",
    "emoji": "🚀",
    "status": "active",
    "name": "The Second",
    "activated_at": "2019-08-02T11:42:19.872Z",
    "settings": ...,
    "modifying": true
  }
]

Returns an array of your SIM cards

Definition

GET https://api.zevvle.com/sim_cards

Call Records

Retrieve a call record

curl -G "https://api.zevvle.com/call_records/$call_record_id" \
  -H "Authorization: Bearer $secret_token" \
  -d "expand[]=destination"

  # The '-G' flag in cURL lets you add URL parameters with the -d/--data flag.

Example response:

{
  "id": "voice_ZQ4CVh9kw9fj3gLLadnuBinv",
  "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
  "setup_at": "2019-09-18T14:41:04.000Z",
  "started_at": "2019-09-18T14:41:31.000Z",
  "duration": 23,
  "charge": "5.75",
  "imei": null,
  "calling_number": "+447922306107",
  "dialled_number": "+33123456789",
  "redirected_number": null,
  "number_type": "FIX",
  "simple_type": "voice",
  "zevvle_type": null,
  "mcc": "234",
  "mnc": "30",
  "origin": "GBR",
  "destination": {
    "country": "France",
    "flag": "🇫🇷",
    "iso3": "FRA"
  }
}

Returns the details of a call record.

Definition

GET https://api.zevvle.com/call_records/$call_record_id

We use 'call' in the broadest sense, in line with the convention of calling them Call Detail Records, or CDRs, whether talking about data, voice, SMS or MMS.

We receive CDRs in batches which normally arrive within 90 seconds of your usage, so if they're not showing already, they're on their way!

Request parameters

expand[]
Optional
Can be origin and/or destination for the name & flag of the country.

Response parameters

setup_at
Voice only
The time the call was setup (i.e., started dialling).
started_at The time of the call/message/data session.
duration Seconds for voice, bytes for data or the number of distinct SMS/MMS.
charge The charge of the call, in GBP pence (a string).
imei If known, the IMEI of the device.
calling_number The phone number making the call.
dialled_number The receiving number of the call (or APN in the case of data records). The same as the SIM card phone number (MSISDN) for incoming calls.
redirected_number
Voice only
The number forwarded from (e.g. if the caller is redirected to voicemail).
number_type The type of number dialled. See below for possible options.
simple_type For convenience, the simple type of the record – either data, voice, sms or mms.
zevvle_type Can be either inter_account, bundle or null.
mcc The Mobile Country Code.
mnc The Mobile Network Code.
origin If known, the origin country code of the record, in ISO 3166-1 alpha-3 format (expandable, see above).
destination If known, the destination country code of the record. Returns null for data records (expandable, see above).

List call records

curl -G "https://api.zevvle.com/call_records" \
  -H "Authorization: Bearer $secret_token" \
  -d "sim_card_id=$sim_card_id"

Example response:

[
  {
    "id": "data_GmTSYCrVxfbzCTtxYf58rkew",
    "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
    "setup_at": null,
    "started_at": "2019-09-20T18:39:35.000Z",
    "duration": 290,
    "charge": "0.00005401670932769775390625",
    "imei": "531354301962910",
    "calling_number": "+447922306107",
    "dialled_number": "everywhere",
    "redirected_number": null,
    "number_type": null,
    "simple_type": "data",
    "zevvle_type": null,
    "mcc": "234",
    "mnc": "30",
    "origin": "GBR",
    "destination": null
  }
  {
    "id": "sms_2LbiZYft8N3vp3ppoJ4bdAOJ",
    "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
    "setup_at": null,
    "started_at": "2019-09-20T18:39:42.000Z",
    "duration": 1,
    "charge": "0.0",
    "imei": null,
    "calling_number": "+447922306107",
    "dialled_number": "+447898765432",
    "redirected_number": null,
    "number_type": "MOB",
    "simple_type": "sms",
    "zevvle_type": "inter_account",
    "mcc": "234",
    "mnc": "33",
    "origin": "GBR",
    "destination": "GBR"
  }
]

Returns a list of call records for a SIM card.

Definition

GET https://api.zevvle.com/call_records

Request parameters

sim_card_id
Required
The ID of the SIM to retrieve call records for.
type[]
Optional
The type of record to retrieve – can be data, voice, sms or mms. Repeatable.
limit
Optional
Limit the number of records; default 10, maximum 100.
before
Optional
Get records before an RFC 3339-encoded timestamp or record id.
after
Optional
Get records after an RFC 3339-encoded timestamp or record id.
expand[]
Optional
Can be origin and/or destination for the name & flag of the country.

Number Types

We use the following number types:

FIX Geographic
MOB Mobile
XPN Personal
XPR Premium rate
XSC Shared cost
XTF Toll-free
SAC Short or special code
VOI Voicemail
NFX National geographic
XLR Local rate
XNR National rate

SIM Card Settings

Each SIM card has the following settings:

sms SMS are enabled.
mms MMS are enabled.
data Data is enabled; either 4G or false.
voice_geographic Calls to UK landline numbers are enabled.
voice_mobile Calls to UK mobile numbers are enabled.
voicemail Your voicemail are enabled.
call_holding Call holding is enabled (pause your current call to make another call or answer an incoming one).
call_waiting Call waiting is enabled (get notified of incoming calls while you're on a call).
calling_line_identity Calling Line Identity is enabled (show the other person who's calling).
voice_sms_bundle Whether or not the SIM has an unlimited calling & messaging bundle.
international International & roaming setting; either roaming or false.
eea_data Data in Europe is enabled (the European Economic Area).
eea_sms Outgoing SMS in Europe are enabled.
eea_outgoing_call Outgoing calls in Europe are enabled.
eea_incoming_call Incoming calls in Europe are enabled.

Webhooks

Stand by, we're working on them! 🤓

Errors

We use standard HTTP response codes to indicate errors (and successes!), and include more details in each request.

Error Code Meaning
200
Great Success
Magnificent.
400
Bad Request
Your request is invalid.
401
Unauthorized
Your authorization token is incorrect.
403
Forbidden
You're not allowed there.
404
Not Found
We couldn't find the requested resource.
418
I'm a teapot
Yes.
429
Too Many Requests
Slow down!
500
Internal Server Error
We screwed up.
503
Service Unavailable
We're temporarily offline; try again later.