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

Pagination

Some endpoints can be paginated with timestamps or record IDs.

Request parameters
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.

Pricing

Retrieve Zevvle 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,
  "data_tiers": {
    "1": {
      "megabyte": 0.5,
      "gigabyte": 500
    },
    "2": {
      "megabyte": 0.2,
      "gigabyte": 200
    },
    "3": {
      "megabyte": 0.1,
      "gigabyte": 100
    }
  },
  "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.

Non-geographic pricing

curl "https://api.zevvle.com/non_geographic/118118"

Example response:

{
  "rate": {
    "fixed_fee": 243,
    "per_min_after_one": 243,
    "access_charge": 5
  },
  "format": "118 118",
  "code": "SC070"
}

Returns the pricing for non-geographic calls (some numbers starting 08, 09 and 118). They have an access charge set by us and 1 or 2 service charges set by the organisation you're calling.

We have a handy tool for this on our website.

Definition

GET https://api.zevvle.com/non_geographic/$phone_number

Response parameters
rate The rate for the phone number, including the possible keys access_charge, fixed_fee, per_min and/or per_min_after_one.
format The format of the phone number, e.g. 0845 112 or 118 118.
code The Service Charge code set by BT.

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).

Charges

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!

Retrieve a charge

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

Example response:

{
  "id": "ch_bkxIpsoBYmqtxAMFykZ5Xd3I",
  "amount": 3000,
  "paid_at": "2020-07-04T17:34:04.000Z",
  "error": null,
  "items": [
    {
      "item_id": "sim_8STKdUNSsONvYhZaKUqWnGqV",
      "description": "60_GB_data_only",
      "price": 3000,
      "quantity": 1
    }
  ]
}

Returns the details of a charge.

Definition

GET https://api.zevvle.com/charges/$charge_id

Response parameters
amount The total amount of the charge.
paid_at The time it was paid (null if there was an error).
error The error description, if any.
items An array of items for the charge.

List charges

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

Example response:

[
  {
    "id": "ch_vG0ZEqaaFyCFpSNGDJA4M2Fg",
    "amount": 2300,
    "paid_at": "2020-07-04T17:34:20.000Z",
    "error": null,
    "items": [
      {
        "item_id": "sim_8STKdUNSsONvYhZaKUqWnGqV",
        "description": "30_GB",
        "price": 2300,
        "quantity": 1
      }
    ]
  },
  {
    "id": "ch_bkxIpsoBYmqtxAMFykZ5Xd3I",
    "amount": 3000,
    "paid_at": "2020-07-04T17:34:04.000Z",
    "error": null,
    "items": [
      {
        "item_id": "sim_8STKdUNSsONvYhZaKUqWnGqV",
        "description": "60_GB_data_only",
        "price": 3000,
        "quantity": 1
      }
    ]
  }
]

Returns a list of charges for your account.

Definition

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

Request parameters
Pagination
Optional		 This endpoint can be paginated.

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,
      "row_sms": false,
      "row_outgoing_call": false,
      "row_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

SIM Card Settings

Each SIM card has the following settings:

Setting Description
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 is 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.
row_sms Incoming calls outside of Europe are enabled.
row_outgoing_call Outgoing SMS outside of Europe ('Rest of World') are enabled.
row_incoming_call Outgoing calls outside of Europe are enabled.

Call Records

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!

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

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.
expand[]
Optional		 Can be origin and/or destination for the name & flag of the country.
Pagination
Optional		 This endpoint can be paginated.

Number Types

We use the following number types:

Type Description
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

Webhooks

For every matching event, we'll make a POST request to the URL you provide with details of the event. If it fails, we'll retry up-to 5 times with exponential backoff.

Call Records

We receive call records in batches which normally arrive within 90 seconds of your usage, i.e. webhooks for those events are batched and not realtime. For data usage, we receive those records after one hour or 16 MB is used, whichever comes first.

For example, if you register a data.created webhook and use 80 MB within a minute, we'll notify the webhook with 5 data events as soon as we receive the records.

Charges

Charges are created for your monthly subscription (if any), top-ups or add-on purchases.

Create a webhook

curl -X POST "https://api.zevvle.com/webhooks" \
  -H "Authorization: Bearer $secret_token" \
  -d "url=https://example.com/z3vvl3" \
  -d "type=data.created"

Example response:

{
  "id": "wh_4kxxG730DZ03iQ2qEhkwd4Bt",
  "url": "https://example.com/z3vvl3",
  "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
  "type": "data.created",
  "sim_card_id": null
}

Definition

POST https://api.zevvle.com/webhooks

Request parameters
url
Required		 The URL we'll send notifications to. Must be HTTPS.
sim_card_id
Optional		 For call record events, the SIM card to receive notifications for. If it's empty, we'll send notifications for all your SIM cards.
type
Optional		 The matching event type (defaults to null, or everything). See below for available types.

List webhooks

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

Example response:

[
  {
    "id": "wh_4kxxG730DZ03iQ2qEhkwd4Bt",
    "url": "https://example.com/z3vvl3",
    "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
    "type": "data.created",
    "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw"
  },
  {
    "id": "wh_510U77gwGFjZ7ExjNETOzX8e",
    "url": "https://example.com/v0daf0ne",
    "user_id": "user_QhBebSdWZXIzHTvfeVAZc8Ko",
    "type": null,
    "sim_card_id": null
  }
]

Definition

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

Request parameters
sim_card_id
Optional		 The SIM card to retrieve the webhooks for. Defaults to all your webhooks.

Delete a webhook

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

Definition

DELETE https://api.zevvle.com/webhooks/$webhook_id

Webhook types

Data created event:

{
  "webhook_id": "wh_4kxxG730DZ03iQ2qEhkwd4Bt",
  "type": "data.created",
  "data": [
    {
      "id": "data_Ub8vXapFBs4uqxkjULj2DDYK",
      "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
      "setup_at": null,
      "started_at": "2020-06-25T13:37:00.000Z",
      "duration": 840346,
      "charge": "0.00",
      "imei": "531354301962910",
      "calling_number": "+447922306107",
      "dialled_number": "everywhere",
      "redirected_number": null,
      "number_type": null,
      "simple_type": "data",
      "zevvle_type": "bundle",
      "mcc": "234",
      "mnc": "30",
      "origin": "GBR",
      "destination": null
    }
    {
      "id": "data_7avjwG89WVFPgAAJ1vpPpzgI",
      "sim_card_id": "sim_sE0UiCwOYtcw4rx9rTQVH8Gw",
      "setup_at": null,
      "started_at": "2020-06-25T13:37:37.000Z",
      "duration": 3551663,
      "charge": "0.00",
      "imei": "531354301962910",
      "calling_number": "+447922306107",
      "dialled_number": "everywhere",
      "redirected_number": null,
      "number_type": null,
      "simple_type": "data",
      "zevvle_type": "bundle",
      "mcc": "234",
      "mnc": "30",
      "origin": "GBR",
      "destination": null
    }
  ]
}
Type Description
data.created Data records are created.
voice.created Voice records are created.
sms.created SMS records are created.
mms.created MMS records are created.
charge.created A charge was created.
null Matches any event.

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 request.
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.