Verimor SMS API (v2)

Download OpenAPI specification:

Verimor SMS API, uygulamalarınız veya sunucu taraflı yazılımlarınız üzerinden SMS gönderimi ve yönetimi yapmanızı sağlayan bir HTTP arayüzüdür. API, farklı amaçlara yönelik (toplu gönderim, raporlama, bakiye sorgulama vb.) çeşitli endpoint'ler sunar.

Kimlik Doğrulama (Authentication)

API'ye yapılan istekler, Verimor kullanıcı adı ve API şifreniz ile doğrulanır. Kimlik doğrulama yöntemi, isteğin türüne göre değişir:

POST İstekleri (örn: /v2/send.json): username ve password bilgileri, isteğin gövdesinde (request body) JSON formatında gönderilir.
GET İstekleri (örn: /v2/report): username ve password bilgileri, isteğin URL'ine query string parametresi olarak eklenir.

API şifrenizi Verimor Online İşlem Merkezi (OİM) üzerinden oluşturabilirsiniz.

Temel Yetenekler

API, aşağıdaki temel işlevleri desteklemektedir:

Tekil veya toplu SMS gönderimi
İleri tarihli SMS gönderimlerini programlama
Gönderilen mesajların iletim durumlarını detaylı olarak sorgulama
Hesapta kalan SMS kredisini öğrenme
Zamanlanmış gönderimleri iptal etme
Onaylanmış gönderici başlıklarını (alfanümerik) listeleme

Teknik Formatlar

API, operasyona göre farklı veri formatları kullanır. Mesaj gönderme gibi POST işlemleri application/json formatında veri kabul eder ve yanıt döner. Raporlama gibi GET işlemleri ise parametreleri URL üzerinden alır ve yanıtı, isteğe bağlı olarak, varsayılan olarak boşluklarla ayrılmış düz metin (plain text) veya belirtilirse JSON formatında döndürebilir.

Webhooks

Gönderim Raporu Alımı (PUSH) Webhook

PUSH ile Gönderim Raporu Alımı

Push yönteminde mesajın durumu ile ilgili bilgi (teslim edildi, zaman aşımı, numara hatalı vb.) alınır alınmaz OİM üzerinden daha önce belirlediğiniz bir URL tetiklenir. Aşağıdaki gibi bir JSON POST edilir:

Content-Type: application/json

Accept: /

Not: API, sisteminize PUSH bildirimi yaptığında “HTTP/1.1 200 OK” cevabı bekler. Bu cevabı alamadığı zaman 5’er dakika bekleyerek 3 kere daha dener. Hala cevap alamazsa bu mesajı tekrar bildirmez.

Request Body schema: application/json

Sisteminize gönderilecek JSON örneği ve alan açıklamaları:

Array

type	string Mesajın yönüdür. Gönderilen sms olduğu için outbound.
campaign_id	integer Mesajın kampanya ID’si.
campaign_custom_id	string Mesajın kampanyasına sizin tarafınızdan verilmiş özel ID.
message_id	string Mesaja API tarafından verilmiş ID.
message_custom_id	string Mesaja sizin tarafınızdan verilmiş özel ID.
dest	string Mesajın gönderildiği telefon numarası. Yurt dışı numaralarının başına 00 eklenmelidir. Örnek: 0049xxxxxxxx.
size	integer Mesajın boyu.
international_multiplier	integer Mesajın kredi çarpanı (bir boyunun kaç krediye denk geldiği). Uluslararası mesajlarda 1’den büyük olur. Ulusal mesajlarda daima 1 olur.
credits	integer Bu mesaj için hesabınızdan kaç kredi düşüldüğü.
status	string Mesajın durumu (olabilecek durumlar ve anlamları için dokümanın sonundaki durum listesine bakınız).
gsm_error	string Mesaj iletilemediyse operatörden dönen hata kodu.
sent_at	string Mesajın iletildiği tarih (mesaj iletilemediyse null olur).
done_at	string Mesajın son durumuna ulaştığı tarih (mesaj iletilemediyse de dolu olur).

Responses

Request samples

Payload

Content type

application/json

[[{"type": "outbound",
"campaign_id": 20121,
"campaign_custom_id": "123456789",
"message_id": "13582302",
"message_custom_id": "1234",
"dest": "905111111111",
"size": 1,
"international_multiplier": 1,
"credits": 1,
"status": "DELIVERED",
"gsm_error": "0",
"sent_at": "2015-02-20 16:06:00",
"done_at": "2015-02-20 16:06:00"
},
{"type": "outbound",
"campaign_id": 20121,
"campaign_custom_id": "123456789",
"message_id": "13582303",
"message_custom_id": "1235",
"dest": "905111111112",
"size": 1,
"international_multiplier": 1,
"credits": 1,
"status": "DELIVERED",
"gsm_error": "0",
"sent_at": "2015-02-20 16:06:00",
"done_at": "2015-02-20 16:06:00"
}
]
]

Gelen SMS Alımı (PUSH) Webhook

Push yönteminde hesabınıza bir mesaj gelir gelmez OİM üzerinden daha önce belirlediğiniz bir URL tetiklenir. Aşağıdaki gibi bir JSON POST edilir:

Content-Type: application/json

Accept: /

Not: API, sisteminize PUSH bildirimi yaptığında “HTTP/1.1 200 OK” cevabı bekler. Bu cevabı alamadığı zaman 5’er dakika bekleyerek 3 kere daha dener. Hala cevap alamazsa bu mesajı tekrar bildirmez.

Request Body schema: application/json

Sisteminize gönderilecek JSON örneği ve alan açıklamaları:

Array

message_id	integer Mesaja API tarafından verilmiş ID.
type	string Mesajın yönüdür. Gelen sms olduğu için inbound.
created_at	string Mesajın kayıt edildiği tarih saat. Tarih ve saat aralığına göre api isteklerinde filtre yapılacak alan.
network	string Mesajı gönderen operatör. TURKCELL, TTMOBIL, VODAFONE değerleri olabilir.
source_addr	string Mesajı gönderen numara.
destination_addr	string Mesajın gönderildiği numara (Verimor abone numarası veya 4 haneli Verimor ücretsiz kısa numarası).
keyword	string Ortak kullanımlı kısa numaralardaki ayırt edici anahtar kelime. Kısa numaraya değil doğrudan sizin numaranıza gelen sms'lerde boş olur.
content	string Gelen mesajın tam içeriği.
received_at	string Mesajın alındığı tarih saat.

Responses

Request samples

Payload

Content type

application/json

[[{"message_id": 1234,
"type": "inbound",
"created_at": "2017-01-01 09:00:00",
"network": "TURKCELL",
"source_addr": "905111111112",
"destination_addr": "908501234567",
"keyword": "",
"content": "verimor deneme",
"received_at": "2017-01-01 09:00:00"
}
]
]

İYS Günlük Vatandaş Raporu Alımı (PUSH) Webhook

Hergün gün sonunda vatandaşın İYS kanalları (E-Devlet, İYS Web/Mobil/Çağrı merkezi) üzerinden oluşturduğu hareketler için bir kampanya oluşturulur. Oluşturulan bu kampanya ile ilgili bilgiler, OİM üzerinden daha önce belirlediğiniz bir URL'ye (İYS Push URL) gönderilir.

Aşağıdaki örnekte olduğu gibi bir JSON string POST edilir.

Content-Type: application/json

Accept: /

Daha sonra istenirse, 'İYS İZİNLERİ RAPORU' başlığı altındaki dökümandan faydalanılarak, oluşturulan kampanya detayları alınabilir.

Request Body schema: application/json

Sisteminize gönderilecek JSON örneği ve alan açıklamaları:

iys_campaign_id	integer İYS kampanya ID'si.
report_date	string Rapor tarihi (YYYY-MM-DD formatında).
source_addr	string Kampanya başlığı veya kaynak adres.

Responses

Request samples

Payload

Content type

application/json

{"iys_campaign_id": 1234,
"report_date": "2021-01-18",
"source_addr": "BASLIGIM"
}

SMS Kampanyası

Birden Çok Numara Bir Mesaj Gönderebilme

Smsapi gönderim için iki yöntemi destekler. Bunlar HTTP(S) GET (Plain de denir) ve HTTP(S) POST JSON’dır. İkisi de cevabını düz metin olarak döndürür.

query Parameters

username required	string API kullanıcı adı
password required	string API şifresi
dest required	string Mesajın gönderileceği telefon numaraları. Birden fazla numara varsa virgül ile ayrılmalıdır. Yurt dışı numaralarının başına 00 veya + eklenmelidir. Örnek: 0049xxxxxxxx veya +49xxxxxxxx (+ işareti URL'lerde boşluk olarak yorumlanacağı için %2B olarak encode etmelisiniz, örn: %2B49xxxxxxxx). (zorunlu)
msg required	string Gönderilecek mesaj. Türkçe harf içerebilir. Maksimum uzunluğu Türkçe harf içeriyorsa 1043, içermiyorsa 1071 karakter’dir. (zorunlu). Encoding her zaman UTF8 beklenir.
source_addr	string Gönderici kimliği (Başlık). Source_addr boş ise sistemde kayıtlı ilk başlığınız kullanılır.
valid_for	string Mesajın geçerlilik süresi. SS:DD (veya S:DD) formatında olmalı. (Varsayılan değer 24:00, Minumum değer 00:01, Maksimum değer 48:00)
datacoding	integer Mesaj metni için kullanılacak karakter kodlaması. 0, 1 ve 2 değerlerini alabilir. Mesajda kullanılabilecek harfleri ve mesajın boy limitlerini belirler. Boş ise mesaj metnine bakılır, türkçe harf varsa 1, yoksa 0 kaydedilir. Mesaj boyları tablosu için dokümanın sonuna bakınız. Yurt dışına sms gönderiminde değeri 1 olarak gönderilmemelidir.
is_commercial	bool Opsiyonel. true \| false değeri alır. Ticari gönderimlerde true olarak belirlemelisiniz.
iys_recipient_type	string BIREYSEL \| TACIR değeri alır. Ticari gönderimlerde mutlaka belirlemelisiniz.
send_at	string Mesajın gönderilmesini istediğiniz tarih saat. ‘2015-02-20 16:06:00’ şeklinde veya ISO 8601 standardındaki formatlar kabul edilir (http://en.wikipedia.org/wiki/ISO_8601). Boş ise mesaj hemen gönderilir.

Responses

Response samples

200
400
401
403

Content type

text/plain

Birden Çok Numara Farklı Mesajlar Gönderebilme

JSON formatında toplu SMS gönderimi için kullanılır. Birden fazla farklı mesajı farklı numaralara gönderebilirsiniz.

Request Body schema: application/json

username required	string API kullanıcı adı
password required	string API şifresi
source_addr	string Gönderici başlığı
valid_for	string Mesajın geçerlilik süresi (varsayılan: 24:00)
datacoding	integer Enum: 0 1 2 Veri kodlama (0: GSM Basic, 1: GSM Turkish, 2: UCS2)
is_commercial	boolean Ticari mesaj mı
iys_recipient_type	string İYS alıcı tipi (BIREYSEL/TACIR)
send_at	string Gönderim zamanı (ISO 8601 formatında)
custom_id	string Özel kampanya ID'si
required	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"username": "9085000000",
"password": "111111",
"source_addr": "VERIMOR",
"valid_for": "",
"datacoding": 0,
"is_commercial": true,
"iys_recipient_type": "BIREYSEL",
"send_at": "111111",
"custom_id": "123456",
"messages": [{"dest": "905111111111,905111111112",
"msg": "Deneme Mesaj",
"id": "1234567",
"iys_recipient_type": "BIREYSEL"
}
]
}

Response samples

200
400
401

Content type

text/plain

İleri Tarihli Mesaj Gönderimi İptali

İleri tarihli mesaj gönderimini iptal etmek için örnekte olduğu gibi bir JSON string POST edilir.

path Parameters

id

required

string

Kampanya ID'si

Request Body schema: application/json

username	string API kullanıcı adı
password	string API şifresi

Responses

Request samples

Payload

Content type

application/json

{"username": "9085000000",
"password": "111111"
}

Response samples

200
400

Content type

text/plain

Kampanya silindi: 123456

Bakiye Sorgulamaları

SMS Kalan Kredi Sorgulama

SMS kalan kredi sorgulama için bu servis kullanılır. İşlem için kullanıcı adı ve şifre gereklidir.

query Parameters

username required	string Kullanıcı Adı
password required	string Şifre

Responses

Response samples

200
401

Content type

text/plain

Karaliste

Karalistedeki Numaraların Alımı

Karaliste’deki numaraları listelemek için kullanılır.

Bu endpoint, kullanıcı adı ve şifre ile kimlik doğrulaması gerektirir.

Total değeri toplam kayıt sayısını verir, bir sorguda en fazla 100 adet kayıt dönülür. Devamını almak için offset değerini yükseltip tekrar sorgulamalısınız.

query Parameters

username required	string Kullanıcı adı
password required	string Şifre
offset	integer Sayfalama Taban Değeri
limit	integer Sayfa Kayıt Sayısı

Responses

Response samples

200
400
401

Content type

application/json

{"total": 2,
"records": [{"created_at": "2019-11-25T11:13:24.988+03:00",
"phone": "905111111111",
"source": "ret_web"
},
{"created_at": "2020-06-02T16:59:56.957+03:00",
"phone": "905111111112",
"source": "oim"
}
]
}

Karalisteye Numara Eklenmesi

Karalisteye numara eklemek için kullanılır.

Bu endpoint, kullanıcı adı ve şifre ile kimlik doğrulaması gerektirir.

query Parameters

username required	string Kullanıcı adı
password required	string Şifre
phones	string Karalisteye eklenmeleri istenen numaralar, virgülle ayrılmış liste olarak girilmelidir. Örnek: 905111111111,905111111112

Responses

Karalisteden Numaraların Silinmesi

Karalisteden numara(lar)ı silmek için kullanılır.

Bu endpoint, kullanıcı adı ve şifre ile kimlik doğrulaması gerektirir.

path Parameters

phones

required

string

Karalisteden silinmesi istenen numaralar, virgülle ayrılmış liste olarak girilmelidir. Örnek: 905111111111,905111111112

query Parameters

username required	string kullanıcı adı
password required	string Şifre

Responses

Raporlar

Gönderilen SMSlerden API’nin ürettiği ID ile sorma

Gönderim Raporu almak için kullanılır.

id: Kampanya’ya API tarafından verilen ID’dir. id veya custom_id zorunludur.
custom_id: Kampanya’ya sizin tarafınızdan verilen ID’dir. id veya custom_id zorunludur.
dest: Zorunlu değil. Kampanya’da belirli telefon numaralarına gönderilmiş mesajları sorgular.
greater_than: Verilen message_id’den büyük mesajları sorgular. Bu parametre, içinde çok mesaj olan kampanyaların sorgulanması için zorunludur. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

query Parameters

username required	string kullanıcı adı
password required	string Şifre
id required	integer Kampanya ID’si. Bu parametre zorunludur. Kampanya ID’si, API’nin gönderim sırasında ürettiği ID’dir. Bu ID ile sorgulama yapabilirsiniz.
dest	string Zorunlu değil. Kampanya’da belirli telefon numaralarına gönderilmiş mesajları sorgular
greater_than	integer Verilen message_id’den büyük mesajları sorgular. Bu parametre, içinde çok mesaj olan kampanyaların sorgulanması için zorunludur. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

Responses

Response samples

200
400
401
403
404

Content type

application/json

[{"campaign_id": 25388,
"campaign_custom_id": null,
"message_id": 23009861,
"message_custom_id": null,
"dest": "905111111111",
"size": 1,
"international_multiplier": 1,
"credits": 1,
"status": "EXPIRED",
"gsm_error": null,
"sent_at": null,
"done_at": "2025-03-19T15:27:37.348+03:00"
}
]

Gönderilen SMSlerden Custom ID ile sorma

Gönderim Raporu almak için kullanılır.

id: Kampanya’ya API tarafından verilen ID’dir. id veya custom_id zorunludur.
custom_id: Kampanya’ya sizin tarafınızdan verilen ID’dir. id veya custom_id zorunludur.
dest: Zorunlu değil. Kampanya’da belirli telefon numaralarına gönderilmiş mesajları sorgular.
greater_than: Verilen message_id’den büyük mesajları sorgular. Bu parametre, içinde çok mesaj olan kampanyaların sorgulanması için zorunludur. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

query Parameters

username required	string kullanıcı adı
password required	string Şifre
custom_id required	string Kampanya Custom ID’si. Bu parametre zorunludur. Kampanya Custom ID’si, API’nin gönderim sırasında ürettiği Custom ID’dir. Bu ID ile sorgulama yapabilirsiniz.
dest	string Zorunlu değil. Kampanya’da belirli telefon numaralarına gönderilmiş mesajları sorgular
greater_than	integer Verilen message_id’den büyük mesajları sorgular. Bu parametre, içinde çok mesaj olan kampanyaların sorgulanması için zorunludur. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

Responses

Response samples

200
400
401
403
404

Content type

application/json

[{"campaign_id": 25388,
"campaign_custom_id": null,
"message_id": 23009861,
"message_custom_id": null,
"dest": "905111111111",
"size": 1,
"international_multiplier": 1,
"credits": 1,
"status": "EXPIRED",
"gsm_error": null,
"sent_at": null,
"done_at": "2025-03-19T15:27:37.348+03:00"
}
]

Gelen SMS Raporu

Bu API, gelen SMS’lerinizi sorgulamak için kullanılır.

Smsapi hesabınıza gelen sms’leri iki farklı yöntemle teslim edebilir. Bunlar PUSH ve GET yöntemleridir.

Bu servis HTTP GET ile Gelen SMS Alımı hizmetini sağlar. PUSH ile Gelen SMS Alımı konusu için Webhooks Bölümü altındaki ilgili başlğıa bakabilirsiniz.

Sorgulama, belirli bir zaman aralığında veya belirli bir message_id’den büyük mesajları almak için yapılabilir.

query Parameters

username required	string Kullanıcı adı
password required	string Şifre
from_time	string Sorgulanacak zaman aralığının başlangıcı (YYYY-MM-DD HH:MM:SS)
to_time	string Sorgulanacak zaman aralığının bitişi (YYYY-MM-DD HH:MM:SS)
greater_than	integer Verilen message_id’den büyük mesajları sorgular. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

Responses

Response samples

200
400

Content type

application/json

[{"message_id": 12345,
"created_at": "2017-01-01T10:00:00+03:00",
"network": "TURKCELL",
"source_addr": "908500000000",
"destination_addr": "4609",
"keyword": "verimor",
"content": "verimor deneme",
"received_at": "2017-01-01T10:00:00+03:00"
}
]

Başlıklar

Liste

Tanımlı SMS Başlıklarını listeler.

query Parameters

username required	string Kullanıcı Adı
password required	string Şifre

Responses

Response samples

200
401

Content type

application/json

["verimor",
"bulutsantralim"
]

İYS Hizmetleri

İYS İzni Gönderimi

Ticari ileti göndermek için markalarınızı İYSye (İleti Yönetim Sistemi) kaydettirmiş olmalı ve OİM Başlık Yönetiminden ilgili başlığa İYS kodlarını girmiş olmanız gerekir. Bu işlemleri yaptıktan sonra müşterilerinizden aldığınız izinleri bu yöntemle İYSye bildirebilirsiniz.

Aşağıdaki örnekte olduğu gibi bir JSON string POST edilir.

Daha sonra istenirse, "İYS İZİNLERİ RAPORU" başlığı altındaki dökümandan faydalanılarak, gönderilen izinlerin durumları alınabilir.

Request Body schema: application/json

username required	string Kullanıcı Adı
password required	string Şifre
source_addr required	string Başlık
required	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"username": "908501234567",
"password": "xxxxxxx",
"source_addr": "BASLIGIM",
"consents": [{"type": "MESAJ",
"source": "HS_WEB",
"status": "ONAY",
"recipient_type": "BIREYSEL",
"consent_date": "2022-04-14 13:30:30",
"recipient": "905111111111"
},
{"type": "ARAMA",
"source": "HS_MESAJ",
"status": "RET",
"recipient_type": "BIREYSEL",
"consent_date": "2022-04-14 13:30:30",
"recipient": "905111111112"
},
{"type": "EPOSTA",
"source": "HS_MESAJ",
"status": "RET",
"recipient_type": "BIREYSEL",
"consent_date": "2022-04-14 13:30:30",
"recipient": "arge@verimor.com.tr"
}
]
}

İYS Kampanyalarını Listele

Gönderilen İYS izinleri ve İYS günlük vatandaş izin değişiklikleri için kampanyalar oluşturulur. Bu kampanyalar bu servisi kullanarak görülebilir.

Total değeri toplam kayıt sayısını verir, bir sorguda en fazla 100 adet kayıt dönülür. Devamını almak için offset değerini yükseltip tekrar sorgulamalısınız.

query Parameters

username required	string Kullanıcı adı
password required	string Şifre
offset	integer Sayfalama başlangıcı
limit	integer Sayfalama limiti
source	string Kaynak (e.g., list, csv, api, sms, web, iys)

Responses

Response samples

200
400

Content type

application/json

{"records": [{"id": 103,
"header_name": "VERIMOR",
"iys_code": 627033,
"iys_brand_code": 627033,
"source": "iys",
"created_at": "2021-02-10T11:58:57.508+03:00"
},
{"id": 104,
"header_name": "VERIMOR",
"iys_code": 627033,
"iys_brand_code": 627033,
"source": "iys",
"created_at": "2021-02-10T11:59:16.895+03:00"
}
],
"total": 2
}

İYS İzinleri Raporu

Gönderilen İYS izinleri ve İYS günlük vatandaş izin değişikliklerini kampanya idsi ile sorgulayabilirsiniz.

Total değeri toplam kayıt sayısını verir, bir sorguda en fazla 100 adet kayıt dönülür. Devamını almak için offset değerini yükseltip tekrar sorgulamalısınız.

path Parameters

id

required

integer

Kapmanya ID

query Parameters

username required	string Kullanıcı adı
password required	string şifre
offset	integer Sayfalama başlangıcı
limit	integer Sayfalama limiti

Responses

Response samples

200
400

Content type

application/json

{"total": 2,
"source_addr": "BASLIGIM",
"status": "Tamamlandı",
"records": [{"type": "MESAJ",
"source": "HS_WEB",
"recipient": "905111111114",
"status": "ONAY",
"consent_date": "2020-06-11T22:14:00.000+03:00",
"recipient_type": "BIREYSEL",
"request_status": "Başarılı"
},
{"type": "MESAJ",
"source": "HS_WEB",
"recipient": "905111111111",
"status": "RET",
"consent_date": "2020-06-11T22:14:00.000+03:00",
"recipient_type": "BIREYSEL",
"request_status": "Başarısız",
"request_error": "H175 İlk defa kaydedilen bir iznin durum (status) bilgisi RET olmamalıdır."
}
]
}