API Reference

Apifon's REST API is split into the following resources:

Bounce List Resource: Provides endpoints to access and modify the bounce subscribers.
List Resource: Provides endpoints to access and modify the lists.
Subscriber Resource: Provides endpoints to access the list subscribers.
SMS Gateway Resource: Provides endpoints related to SMS messaging.
IM Gateway Resource: Provides endpoints related to IM messaging.
OTP Gateway Resource: Provides endpoints related to OTP (One Time Password) messaging.
Balance Resource: Provides endpoints related to account balance.

The API reference also includes resources related to:

Callback Responses: Callback related information and structure.
Response Status Codes: Information about status codes and responses returned by the API.

Bounce List REST API

The Bounce REST API provides an interface for manipulating your bounced contacts.

Bounced contacts is a feature that safeguards you against dispatching messages to contacts that have chosen to opt out of your content or are otherwise deemed invalid.

To get started, you need to sign up and login to our platform, where you can create an API key, and use that key within the HTTP headers for every request.

Add

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/bounce/subscriber/block

Request body

{
    "destination": "306999999999",
    "description": "Blocked from API",
    "reason": "sub_requested"
}

Add a subscriber as blocked.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/bounce/subscriber

HTTP Path: /block

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes required: writeSubscriber

Request Body: Outer Level

Key	Type	Description
destination	String	The blocked subscriber's destination (Mobile/Email).
reason	Enum	Available Options: BLOCK_REASONS The reason describing why this subscriber was blocked.
description (*optional)	String	A short custom description.

JSON Response

We have an empty Response Body. If you add successfully a blocked subscriber , you will get a success code as response. You can see possible response statuses below.

Get Block Subscribers

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/bounce/subscriber?type=MOBILE&size=50

Request body

No request body is supplied for the balance service.

Using this endpoint, you can get a list of the blocked subscribers for your account. This endpoint enforces pagination on the results returned.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/bounce/subscriber

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes required: readSubscriber

Query Parameters

Key	Type	Description
type (*optional)	Enum	Available Options: MOBILE/EMAIL.
reason (*optional)	Enum	Available Options: BLOCK_REASONS The reason describing why this subscriber was blocked.
fields (*optional)	String	The fields you want to include in the response as comma-seperated input. Used for Partial Responses.
page (*optional)	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size (*optional)	Integer	The number of subscribers displayed on one page. Used for pagination. Max value for size is 200. If ommited, defaults to the max value.
sort (*optional)	String	Sort block subscribers based on a field value. Used for sorting. If ommited, the API will sort based on the date_created field.
sort_dir (*optional)	Enum	Sorting Method. Available Options:DESC/ASC. Default: ASC. DESC: sort values in which the sorting starts from the highest value and proceeds to the lowest value. ASC: sort values in which the sorting starts from the lowest value and proceeds to the highest value. Used for sorting.

JSON Response

Response body

{
    "meta": {
       "page": 1,
       "size": 50,
       "total": 160
    },
    "links": {
       "prev": "",
       "next": "https://ars.apifon.com/services/api/v1/bounce/subscriber?type=MOBILE&size=50&page=2",
       "first": "https://ars.apifon.com/services/api/v1/bounce/subscriber?type=MOBILE&size=50&page=1",
       "last": "https://ars.apifon.com/services/api/v1/bounce/subscriber?type=MOBILE&size=50&page=4"
    },
    "results": [
      {
          "meta": {
              "Etag": "e7c7c847a2c5f0e6502bd9191f54586b"
          },
          "destination": "306999999999",
          "type": "MOBILE",
          "reason": "other",
          "user": "API",
          "description": "Blocked from API",
          "date_created": 1558612507988
          },
          // Results ommited
       ]
}

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
links	LINKS_DETAILS	Links used for pagination.
results	List of BLOCK_SUBSCRIBERS	A List with blocked subscribers.

JSON Response:META_DETAILS

Key	Type	Description
page	Integer	Current page of results. Used for pagination.
size	Integer	The number of subscribers displayed on one page. Used for pagination.
total	Integer	Total number of pages. Used for pagination.

JSON Response:LINKS_DETAILS

Key	Type	Description
prev	String	The previous page of results. May be empty. Used for pagination.
next	String	The next page of results. May be empty. Used for pagination.
first	String	The first page of results. Used for pagination.
last	String	The last page of results. Used forpagination.

JSON Response:BLOCK_SUBSCRIBERS

Key	Type	Description
meta	BLOCK_SUBSCRIBERS_META	Data information for the entity.
destination	String	The blocked subscriber's destination (Mobile/Email).
type	Enum	Available Options: MOBILE/EMAIL. Defines the type of the blocked subscriber. MOBILE: Subscriber is blocked by his mobile destination. EMAIL: Subscriber is blocked by his email destination.
reason	Enum	Available Options: BLOCK_REASONS. The reason describing why this subscriber was blocked.
user	String	The user that blocked this particular subscriber.
description	String	A short custom description.
date_created	Epoch Timestamp	The date that the subscriber was blocked.

JSON Response:BLOCK_SUBSCRIBERS_META

Key	Type	Description
Etag	String	Entitytag

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

Get Block Subscriber by destination

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/bounce/subscriber/306999999999

Request body

No request body is supplied for the balance service.

With this endpoint, you can get a blocked user by his destination.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/bounce/subscriber

HTTP Path: /{destination}

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes required: readSubscriber

Query Parameters

Key	Type	Description
fields (*optional)	String	The fields you want to include in the response as comma seperated input. Used for Partial Responses.

Path Parameters

Key	Type	Description
destination	String	The blocked subscriber's destination (Mobile/Email).

JSON Response

Response body

{
 "meta": {
   "Etag": "e7c7c847a2c5f0e6502bd9191f54586b"
 },
 "destination": "306999999999",
 "type": "MOBILE",
 "reason": "other",
 "user": "API",
 "description": "Blocked from API",
 "date_created": 1558612507988
 }

Key	Type	Description
meta	BLOCK_SUBSCRIBERS_META	Data information for the entity.
destination	String	The blocked subscriber's destination (Mobile/Email).
type	Enum	Available Options: MOBILE/EMAIL. Defines the type of the blocked subscriber. MOBILE: Subscriber is blocked by his mobile destination. EMAIL: Subscriber is blocked by his email destination.
reason	Enum	Available Options: BLOCK_REASONS. The reason describing why this subscriber was blocked.
user	String	The user that blocked this particular subscriber.
description	String	A short custom description.
date_created	Epoch Timestamp	The date that the subscriber was blocked.

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

Query Block Subscribers

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/bounce/subscriber/query

With this endpoint you can make conditions and query blocked subscribers with these conditions.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/bounce/subscriber/query

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readSubscriber

Request Body

Request Body

{
    "conditions": [
        {
            "name": "date_created",
            "op": "gte",
            "vl": "1716991961177"
        },
        {
            "name": "destination",
            "op": "beginsWith",
            "vl": "30699"
        }
    ],
    "fields": ["destination" , "reason", "user", "description","date_created"],
    "sort": {
        "sort_dir": "DESC",
        "sort_field": "destination"
    },
    "page": "1",
    "size": 200
}

Response Body

{
    "meta": {
        "page": 1,
        "size": 200,
        "total": 1
    },
    "results": [
        {
            "reason": "other",
            "date_created": 1716991961178,
            "destination": "306999999999",
            "description": "Blocked from API",
            "user": "API"
        }
    ]
}

Key	Type	Description
conditions (*optional)	List of CONDITIONS	A list of conditions that the blocked subscribers must fullfil. Note: If multiple conditions are specified then only subscribers matching ALL of the conditions are returned.
sort (*optional)	Sort	sorting properties.
fields (*optional)	String	The fields you want to include in the response as comma-seperated input. Used for Partial Responses.
page	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size	Integer	Number of subscribers displayed in one page. Used for pagination. Max value for size is 200. If ommited, defaults to the max value.

CONDITIONS

Key	Type	Description
name	String	The field on which to apply the condition.
op	Enum	The operator to apply. Available operators.
vl	Object	The value that the condition must match.

CONDITION_OPERATORS

Option	Description
eq (*)	Value must match exactly the given vl.
beginsWith	Value must begin with the given vl.
gte (*)	Value must be greater or equal than the given vl.
gt	Value must be greater than the given vl.
lte (*)	Value must be lower or equal than the given vl.
lt	Value must be lower than the given vl.
exists	Value must exist (Not null).
nexists	Value must not exist (null).

(*) This operator cannot be applied in date fields.

Sort

Key	Type	Description
sort_dir	Enum	Sorting Method. Available Options:DESC/ASC. Default: ASC. DESC: sort values in which the sorting starts from the highest value and proceeds to the lowest value. ASC: sort values in which the sorting starts from the lowest value and proceeds to the highest value. Used for sorting.
sort_field	String	Sorting is based at this field. If ommited, it defaults to "id" field.

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
results	List of SUBSCRIBERS_DETAILS	A List with all selected subscribers.

Json Response: META_DETAILS

Key	Type	Description
page	Integer	Current page of results. Used for pagination.
size	Integer	The number of subscribers displayed on one page. Used for pagination.
total	Integer	Total number of blocked subscribers. Used for pagination.

SUBSCRIBERS_DETAILS

Key	Type	Description
destination	String	The blocked subscriber's destination (Mobile/Email).
type	Enum	Available Options: MOBILE/EMAIL. Defines the type of the blocked subscriber. MOBILE: Subscriber is blocked by his mobile destination. EMAIL: Subscriber is blocked by his email destination.
reason	Enum	Available Options: BLOCK_REASONS. The reason describing why this subscriber was blocked.
user	String	The user that blocked this particular subscriber.
description	String	A short custom description.
date_created	Epoch Timestamp	The date that the subscriber was blocked.

Possible Response statuses

A status code for the given request that follows the http standards.

Remove Blocked Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/bounce/subscriber/unblock/306999999999

Request body

No request body is supplied for the balance service.

With this Endpoint, you can delete a Subscriber from the block list.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/bounce/subscriber

HTTP Path: /unblock/{destination}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes required: writeSubscriber

Path Parameters

Key	Type	Description
destination	String	The blocked subscriber's destination (Mobile/Email).

JSON Response

We have an empty Response Body. If you remove successfully a subscriber , you will get a success code as response. You can see possible response statuses below.

BLOCK_REASONS

Key	Description
other	Other reason not described below.
not_delivering	Subscriber is blocked due to messages not delivering.
sub_deleted	Subscriber is blocked because he was removed.
sub_requested	Subscriber is blocked because he requested it.
sub_invalid	Subscriber is blocked because he is invalid.

List REST API

The List REST API provides an interface for manipulating your lists.

Lists is a collection of contacts in Mookee and provide tools for campaign automation, message content personalization, segmentation and GDPR preferences.

To get started, you need to sign up and login to our platform, where you can create an API key, and use that key within the HTTP headers for every request.

Double OPT-in

Double OPT-in is an extra level of security that helps you reduce the chance of spam addresses in your lists. When registering a subscriber in your list, there is the option of using the Double Opt-In mechanism, in which the subscriber receives an SMS and/or Email to confirm that he wants to subscribe to your list. For more information, click here

Add List

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list

Request body

{
    "title": "Sample list from API ",
    "type": "ADVANCED",
    "description": "This is a list created from API",
    "prefix": "+30",
    "campaign_defaults": {
        "sender_id": "Apifon",
        "sender_name": "Apifon",
        "viber_sender_id": "Apifon",
        "from": "apifon@apifon.com",
        "reply_to": "apifon@apifon.com"
    },
    "gdpr_properties": {
        "gdpr_compliant": true,
        "legal_text": "My legal Text",
        "title": "Communication Purposes",
        "description": "We will communicate with you."
    },
    "double_optin":{
        "mobile": false,
        "email": false,
        "review_mobile_details":false
    }
}

Add a new list. You can create a new list and then fill it with subscribers.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Request Body

Key	Type	Description
type	Enum	Available Options : ADVANCED The type of list you want to create. ADVANCED: A list that offers mobile and email destination storing, GDPR compliance features, landing pages & forms etc.
title	String	The title of your list.
description (*optional)	String	A description of your list.
prefix	String	The default prefix (Country Code) for subscribers of that list. If no country code is provided for a mobile destination then the default one will be used.
campaign_defaults(*optional)	CAMPAIGN_DEFAULTS*	Default values for campaign creation in Mookee.
gdpr_properties (*optional)	GDPR_PROPERTIES**	GDPR Legal Properties.
double_optin (*optional)	DOUBLE_OPTIN***	It allows for sending confirmation messages to the subscribers once they enter the list.

CAMPAIGN_DEFAULTS*

Key	Type	Description
sender_id (*optional)	String	The sender ID that will be used as default when one is not defined in SMS campaigns. The maximum is 11 for alphanumeric and 16 for numeric characters.
viber_sender_id (*optional)	String	The viber sender ID that will be used as default when one is not defined in Viber campaigns. ✔ To get a viber sender ID please contact support@apifon.com.
sender_name (*optional)	String	The sender name diplayed on emails send.
from (*optional)	String	The FROM address used in emails.
reply_to(*optional)	String	The REPLY TO address used in emails.

GDPR_PROPERTIES**

Key	Type	Description
gdpr_compliant (*optional)	Boolean	True to indicate that the list is gdpr compliant, false otherwise. Defaults to false if omitted.
legal_text	String	The legal text displayed as a footer on your forms.
title	String	The title of your GDPR section.
description	String	The description of your GDPR section.

DOUBLE_OPTIN***

Key	Type	Description
mobile (*optional)	boolean	Enable to send a confirmation sms every time a new subscriber with a mobile joins the list. Defaults to false if ommited.
email (*optional)	boolean	Enable to send a confirmation email every time a new subscriber with an email joins the list. Defaults to false if ommited.
review_mobile_details (*optional)	boolean	Enable to send a review page back to the subscriber during signup so that he can go over and reexamine his details. Can only be true if mobile is true.

JSON Response

If your request to add a new list is successful you will get a 201 - Created success code as response.
A success response will include a Location HTTP header with the URI of the resource created.
You can see possible response statuses below for other cases.

Get Lists

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list?type=ADVANCED&size=10&page=1

Response body

{
     "meta": {
        "page": 1,
        "size": 10,
        "total": 15
   },
   "links": {
        "prev": "",
        "next": "https://ars.apifon.com/services/api/v1/list?type=ADVANCED&page=2&size=10",
        "first": "https://ars.apifon.com/services/api/v1/list?type=ADVANCED&page=1&size=10",
        "last": "https://ars.apifon.com/services/api/v1/list?type=ADVANCED&page=2&size=10"
   },
   "results": [
     {
      "meta": {
          "ETag": "0c06d1eb393d353aed62d94c7157bd38",
      },
      "id": "5ce4fcef7ed5cc3898208e67",
      "type": "ADVANCED",
      "title": "Apifon List API",
      "status": "IDLE",
      "description": "This is a list created from API",
      "prefix": "+30",
      "account_id": 1,
      "date_created": 1560522076000,
      "date_updated": 1560522076000,
      "campaign_defaults": {
         "from": "apifon@apifon.com",
         "sender_id": "Apifon",
         "sender_name": "Apifon",
         "reply_to": "apifon@apifon.com"
       },
       "total_subscribers": 200,
       "active_subscribers": 195,
       "active_email_subscribers": 112,
       "form_id": "c95d238a-3bd0-45a5-a37c-e001baa2ccda",
        "groups": [
        {
        "name": "API_GROUP",
        "field": "API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2",
        "type": "GROUP",
        "internal": false,
        "selectionType": "MULTIPLE",
        "options": [
            {
                "name": "API_GROUP_OPTION_1",
                "field": "API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902"
            },
            {
                "name": "API_GROUP_OPTION_3",
                "field": "API_GROUP_OPTION_3_f9d9e293-b69e-4baf-a89a-7d97d9a86f48"
            }
        ],
        "formHidden": false,
        "groupOptionsOrientation": "HORIZONTAL"
        }
      ],
       "subscriber_fields": [
        {
          "field": "date_BIRTHDAY",
          "length": 20,
          "name": "Birthday",
          "type": "DATE",
          "internal": false,
          "date_format": "dd/MM/yy"
        },
        {
          "field": "NAME",
          "length": 25,
          "name": "Name",
          "type": "Text",
          "internal": false,
        }
    ],
       "gdpr_fields": [
        {
          "name": "Promotion",
          "description": "I do accept to receive promotional notifications",
          "field": "PROMOTION",
          "mobile": true
          "email": true
        },
        {
          "name": "Offers",
          "description": "Offers",
          "field": "OFFERS",
          "mobile": true
          "email": true
         }
     ],
     "brand_name": "Apifon",
     "company_name": "Apifon",
     "gdpr_properties": {
        "title": "Communication Purposes",
        "description": "We will communicate with you.",
        "gdpr_compliant": true,
        "legal_text": "My legal Text",
      },
     "double_optin":{
        "mobile": false,
        "email": false,
        "review_mobile_details":false
    },
      "form_urls": {
        "SUBSCRIBE_MOBILE": "https://list-manage.apifon.com/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5-a37ce001baa2ccda&c=d9e3110063ba107ab79340dceebc2d7b",
        "UNSUBSCRIBE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5a37c-e001baa2ccda&c=d9e3110063ba107ab79340dceebc2d7b",
        "SUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5a37c-e001baa2ccda&c=61a649a33f2869e5e35fbb7aff3a80d9",
        "UNSUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5-a37ce001baa2ccda&c=61a649a33f2869e5e35fbb7aff3a80d9",
        "SUBSCRIBE": "https://list-manage.apifon.com/listmanager/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=3251245f-5048-4c0c-90a9-58ef80737155"
       }
      },
      //Results ommited
     ]
    }

Used to retrieve lists of your account. This endpoint enforces pagination on the results returned.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readList

Query Parameters:

Key	Type	Description
fields (*optional)	String	The fields you want to include in the response as comma-seperated input. Used for Partial Responses.
type (*optional)	Enum	Available Options: ADVANCED The type of the list.
page (*optional)	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size (*optional)	Integer	Number of lists displayed in one page. Used for pagination. If ommited, defaults to 20.
sort (*optional)	String	Sort lists based on a field value. Used for sorting. If ommited, the API will sort based on the id field.
sort_dir (*optional)	Enum	Sorting Method. Available Options:DESC/ASC. Default: ASC. DESC: sort values in which the sorting starts from the highest value and proceeds to the lowest value. ASC: sort values in which the sorting starts from the lowest value and proceeds to the highest value. Used for sorting.

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
links	LINKS_DETAILS	Links used for pagination.
results	List of LIST_DETAILS	All lists matching the query.

JSON Response:META_DETAILS

Key	Type	Description
page	Integer	Current page of results. Used for pagination.
size	Integer	The number of subscribers displayed on one page. Used for pagination.
total	Integer	Total number of pages. Used for pagination.

JSON Response:LINKS_DETAILS

Key	Type	Description
prev	String	The previous page of results. May be empty. Used for pagination.
next	String	The next page of results. May be empty. Used for pagination.
first	String	The first page of results. Used for pagination.
last	String	The last page of results. Used for pagination.

JSON Response:LIST_DETAILS

Key	Type	Description
meta	META_DETAILS	Data information for the entity
id	String	The ID of the list.
type	Enum	Available Options : ADVANCED The type of the list. ADVANCED: A list that offers mobile and email destination storing, GDPR compliance features, landing pages & forms etc.
title	String	The title of your list.
status	Enum	Available Options: IDLE / UPDATING / CORRUPTED. The current status of the list. UPDATING: Indicates that an import is currently in progress CORRUPTED: Indicates that the last import action on the list failed. IDLE: The List is idle.
description	String	A description of your list.
prefix	String	The default prefix (Country Code) for subscribers of that list. If no country code is provided for a mobile destination then the default one will be used.
account_id	Integer	The account ID of the list.
date_created	Epoch Timestamp	a Timestamp indicating the Date the list was created.
date_updated	Epoch Timestamp	a Timestamp indicating the Date the list was last updated.
campaign_defaults	CAMPAIGN_DEFAULTS	Default values for campaign creation in Mookee.
total_subscribers	Integer	A number of the total subscribers of the list (including UNSUBSCRIBED).
active_subscribers	Integer	A number of the total SUBSCRIBED subscribers that have a mobile destination.
active_email_subscribers	Integer	A number of the total SUBSCIRBED subscribers that have an email destination.
form_id	String	A unique identifier for the forms of the list.
groups	List GROUPS	A list containing all of the groups of the list.
subscriber_fields	List SUBSCRIBER_FIELDS	A list containing all of the subscriber fields of the list.
gdpr_fields	List GDPR_FIELDS	A list containing all of the GDPR field options of the list.
brand_name	String	Your brand name.
company_name	String	Your company name.
gdpr_properties	GDPR_PROPERTIES	GDPR Legal Properties.
form_urls	FORM_URLS	Contains URLs to the list forms.
double_optin	DOUBLE_OPTIN	It allows for sending confirmation messages to the subscribers once they enter the list.

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

Get List

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67

Response body

{
    "meta": {
        "ETag": "0c06d1eb393d353aed62d94c7157bd38",
    },
    "id": "5ce4fcef7ed5cc3898208e67",
    "type": "ADVANCED",
    "title": "Apifon List API",
    "status": "IDLE",
    "description": "This is a list created from API",
    "prefix": "+30",
    "account_id": 1234,
    "date_created": 1560522076000,
    "date_updated": 1560522076000,
    "campaign_defaults": {
        "from": "apifon@apifon.com",
        "sender_id": "Apifon",
        "sender_name": "Apifon",
        "reply_to": "apifon@apifon.com"
    },
    "total_subscribers": 200,
    "active_subscribers": 195,
    "active_email_subscribers": 112,
    "form_id": "c95d238a-3bd0-45a5-a37c-e001baa2ccda",
    "groups": [
    {
    "name": "API_GROUP",
    "field": "API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2",
    "type": "GROUP",
    "internal": false,
    "selectionType": "MULTIPLE",
    "options": [
        {
            "name": "API_GROUP_OPTION_1",
            "field": "API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902"
        },
        {
            "name": "API_GROUP_OPTION_3",
            "field": "API_GROUP_OPTION_3_f9d9e293-b69e-4baf-a89a-7d97d9a86f48"
        }
    ],
    "formHidden": false,
    "groupOptionsOrientation": "HORIZONTAL"
    }
      ],
    "subscriber_fields": [
      {
          "field": "date_BIRTHDAY",
          "length": 20,
          "name": "Birthday",
          "type": "DATE",
          "internal": false,
          "date_format": "dd/MM/yy"
      },
      {
          "field": "NAME",
          "length": 25,
          "name": "Name",
          "type": "Text",
          "internal": false,
      }
    ],
     "gdpr_fields": [
      {
          "name": "Promotion",
          "description": "I do accept to receive promotional notifications",
          "field": "PROMOTION",
          "mobile": true
          "email": true
      }
    ],
    "brand_name": "Apifon",
    "company_name": "Apifon",
    "gdpr_properties": {
        "title": "Communication Purposes",
        "description": "We will communicate with you.",
        "gdpr_compliant": true,
        "legal_text": "My legal Text",
    },
    "double_optin":{
        "mobile": false,
        "email": false,
        "review_mobile_details":false
    },
    "form_urls": {
        "SUBSCRIBE_MOBILE": "https://list-manage.apifon.com/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5-a37ce001baa2ccda&c=d9e3110063ba107ab79340dceebc2d7b",
        "UNSUBSCRIBE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5a37c-e001baa2ccda&c=d9e3110063ba107ab79340dceebc2d7b",
        "SUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5a37c-e001baa2ccda&c=61a649a33f2869e5e35fbb7aff3a80d9",
        "UNSUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=c95d238a-3bd0-45a5-a37ce001baa2ccda&c=61a649a33f2869e5e35fbb7aff3a80d9",
        "SUBSCRIBE": "https://list-manage.apifon.com/listmanager/Apifon/subscribe?l=5ce4fcef7ed5cc3898208e67&f=3251245f-5048-4c0c-90a9-58ef80737155"
    }
}

Retrieve a specific list by it's ID.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readList

Query Parameters

Key	Type	Description
fields (*optional)	String	The fields you want to include in the response as comma seperated input. Used for Partial Responses.

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity
id	String	The ID of the list.
type	Enum	Available Options : ADVANCED The type of the list. ADVANCED: A list that offers mobile and email destination storing, GDPR compliance features, landing pages & forms etc.
title	String	The title of your list.
status	Enum	Available Options: IDLE / UPDATING / CORRUPTED. The current status of the list. UPDATING: Indicates that an import is currently in progress CORRUPTED: Indicates that the last import action on the list failed. IDLE: The List is idle.
description	String	A description of the list.
prefix	String	The default prefix (Country Code) for subscribers of that list. If no country code is provided for a mobile destination then the default one will be used.
account_id	Integer	The account ID of the list.
date_created	Epoch Timestamp	a Timestamp indicating the Date the list was created.
date_updated	Epoch Timestamp	a Timestamp indicating the Date the list was last updated.
campaign_defaults	CAMPAIGN_DEFAULTS	Default values for campaign creation in Mookee.
total_subscribers	Integer	A number of the total subscribers of the list (including UNSUBSCRIBED).
active_subscribers	Integer	A number of the total SUBSCRIBED subscribers that have a mobile destination.
active_email_subscribers	Integer	A number of the total SUBSCIRBED subscribers that have an email destination.
form_id	String	A unique identifier for the forms of the list.
groups	List GROUPS	A list containing all of the groups of the list.
subscriber_fields	List SUBSCRIBER_FIELDS	A list containing all of the subscriber fields of the list.
gdpr_fields	List GDPR_FIELDS	A list containing all of the GDPR field options of the list.
brand_name	String	String containing your brand name.
company_name	String	String containing your company name.
gdpr_properties	GDPR_PROPERTIES	GDPR Legal Properties.
form_urls	FORM_URLS	Contains URLs to the list forms.
double_optin	DOUBLE_OPTIN	It allows for sending confirmation messages to the subscribers once they enter the list.

Json Response: META_DETAILS

Key	Type	Description
Etag	String	Entitytag

Json Response: CAMPAIGN_DEFAULTS

Key	Type	Description
sender_id	String	The sender ID that will be used as default when one is not defined in SMS campaigns.
viber_sender_id	String	The viber sender ID that will be used as default when one is not defined in Viber campaigns. ✔ To get a viber sender ID please contact support@apifon.com.
sender_name	String	The sender name diplayed on emails send.
from	String	The FROM address used in emails.
reply_to	String	The REPLY TO address used in emails.

Json Response: DOUBLE_OPTIN

Key	Type	Description
mobile (*optional)	boolean	If true, sends a confirmation sms every time a new subscriber with a mobile joins the list.
email (*optional)	boolean	If true, sends a confirmation email every time a new subscriber with an email joins the list.
review_mobile_details (*optional)	boolean	If true sends a review page back to the subscriber during signup so that he can go over and reexamine his details. Can only be true if mobile is true.

Json Response: GROUPS

Key	Type	Description
name	String	String containing your group’s name.
field	String	The ID of the group
type	Enum	Available Options : GROUP,CHIPS Type of Group.
internal	Boolean	A boolean indicates if this group is for internal use. An internal group will not show up on any forms. Defaults to false.
selectionType	Enum	Available Options : SINGLE,MULTIPLE Selection Type of Group. Defaults to SINGLE
options	List SUBGROUP	A list containing all of subgroups of the group.
groupOptionsOrientation	Enum	Available Options : VERTICAL, HORIZONTAL, DROPDOWN_LIST Indicates the orientation of subgroups. Defaults to VERTICAL
formHidden	Boolean	A Boolean to make this group visible/invisible in your sign up forms and landing pages. Defaults to false

JSON Response: SUBGROUP

Key	Type	Description
name	String	String containing subgroup’s name.
field	String	The ID of the subgroup

Json Response: SUBSCRIBER_FIELDS

Key	Type	Description
field	String	The identifier of the subscriber field.
length	Integer	A number indicating the max length a personalization field can have when sending a campaign.
name	String	A name for the Subscriber field.
type	Enum	Type of the field. Available options: DATE A date field. Note: Dates are assumed to be in GMT+0 (UTC) timezone. Accepting Epoch timestamps OR a String formatted using date formatter TEXT A simple text field with no specific format NUMBER A numeric field URL A field containing URLs. Accepts valid URLs. EMAIL A field containing Email addresses. Accepts valid Email addresses.
internal	Boolean	This indicates if this field is for internal usage only. An internal field will not show up on any forms. If ommited, defaults to false.
date_format	Enum	A date formatter, only applicable on subscriber fields with type DATE.

Json Response: GDPR_FIELDS

Key	Type	Description
field	String	The identifier of the GDPR field.
name	String	A name for the GDPR field.
description	String	Short description about this GDPR purpose.
mobile	Boolean	A boolean indicating if the GDPR field applies on mobile destinations. If ommited, defaults to true.
email	Boolean	A boolean indicating if the GDPR field applies on email destinations. If ommited, defaults to true.

Json Response: GDPR_PROPERTIES

Key	Type	Description
gdpr_compliant	Boolean	True to indicate that the list is gdpr compliant, false otherwise. Defaults to false if omitted.
legal_text	String	The legal text displayed as a footer on your forms.
title	String	The title of your GDPR section.
description	String	The description of your GDPR section.

Json Response: FORM_URLS

Lists are now unified and combine the operations of mobile and email into a single form. The old/deprecated form urls are still operational for old lists supporting backwards compatibility. The unsubscribe forms are now replaced with the new unified UNSUBSCRIBE form which is unique per subscriber and thus it has been removed from the list's forms.

Key	Type	Description
SUBSCRIBE_MOBILE	URL	Mobile Subscribe form DEPRECATED. Use SUBSCRIBE form instead.
UNSUBSCRIBE_MOBILE	URL	Mobile Unsubscribe form DEPRECATED
SUBSCRIBE_EMAIL	URL	Email Subscribe form DEPRECATED. Use SUBSCRIBE form instead.
UNSUBSCRIBE_EMAIL	URL	Email Unsubscribe form DEPRECATED
SUBSCRIBE	URL	Unified Subscribe form

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

Update List

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67

Request body

{
    "title": "Apifon list API ",
    "description": "This is a list created from API",
    "prefix": "+30",
    "campaign_defaults": {
        "from": "apifon@apifon.com",
        "sender_id": "Apifon",
        "sender_name": "Apifon",
        "reply_to": "apifon@apifon.com"
    },
    "gdpr_properties": {
        "title": "Communication Purposes",
        "description": "We will communicate with you.",
        "gdpr_compliant": true,
        "legal_text": "My legal Text",
    },
    "double_optin":{
        "mobile": false,
        "email": false,
        "review_mobile_details":false
    }

}

Update the properties of an existing list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request Body

Key	Type	Description
title	String	The title of your list.
description (*optional)	String	A description of your list.
prefix	String	The default prefix (Country Code) for subscribers of that list. If no country code is provided for a mobile destination then the default one will be used.
campaign_defaults(*optional)	CAMPAIGN_DEFAULTS*	Default values for campaign creation in Mookee.
gdpr_properties (*optional)	GDPR_PROPERTIES**	GDPR Legal Properties.
double_optin (*optional)	DOUBLE_OPTIN***	It allows for sending confirmation messages to the subscribers once they enter the list.

JSON Response

If your request to update a list is successful you will receive a 204 - No Content status code response.
The successful response will include a Location HTTP header with the URI of the resource updated.
You can see possible response statuses below for other cases.

Remove List

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67

Use this endpoint to remove a list and all associated subscribers, forms and landing pages.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list.

JSON Response

If your request to remove a list is successful you will receive a 204 - No Content status code response
You can see possible response statuses below for other cases.

Add Subscriber field

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/field

Request body

{
    "name": "Birthday",
    "type": "DATE",
    "length": 20,
    "date_format": "dd/MM/yy",
    "internal": false
    }

Using this endpoint, you can add a Subscriber field into a list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/field

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request body

Key	Type	Description
length	Integer	Size of field. The minimum is 1 and the maximum is 256.
name	String	String containing your field's name.
type	Enum	Type of the field. Available options: DATE A date field. Note: Dates are assumed to be in GMT+0 (UTC) timezone. Accepting Epoch timestamps OR a String formatted using date formatter TEXT A simple text field with no specific format NUMBER A numeric field URL A field containing URLs. Accepts valid URLs. EMAIL A field containing Email addresses. Accepts valid Email addresses.
date_format (*optional)	Enum	A date formatter, only applicable on subscriber fields with type DATE.
internal (*optional)	Boolean	A boolean indicates if this field is for internal use. An internal field will not show up on any forms. Defaults to false.

JSON Response

If your request to add a subscriber field to a list is successful a 201 - Created status code response will be signaled back.
The successful response will include a Location header with the URI of the resource updated.
You can see possible response statuses below for other cases.

Update Subscriber field

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/field/NAME

Request body

{
    "length": 50,
    "name": "My First Name",
    "internal": "true"
}

Use this endpoint to update a subscriber field of a list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/field/{field}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
field	String	The identifier of the subscriber field.

Request body

Key	Type	Description
length	Integer	Size of field.
name	String	String containing your field's name.
date_format (*optional)	Enum	A date formatter, only applicable on subscriber fields with type DATE.
internal(*optional)	Boolean	A boolean indicates if this field is for internal use. An internal field will not show up on any forms. Defaults to false.

JSON Response

If your request to update a subscriber field of a list is successful a 200 - OK response status code will be signaled back.
The successful response will include a Location HTTP header with the URI of the resource updated.
You can see possible response statuses below for other cases.

Remove Subscriber field

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/field/NAME

Using this endpoint, you can remove a Subscriber field.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/field/{field}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
field	String	The identifier of the subscriber field.

JSON Response

We have an empty Response Body. If you update successfully a list , you will get a success code as response. You can see possible response statuses below.

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ccc2a4f7ed5cc19d4ce21f2/gdpr

Request body

{
    "name": "Promotion",
    "description": "We are contacting you for promotional reasons"
}

Add a GDPR field to a list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/gdpr

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request body

Key	Type	Description
name	String	The field name.
description (*optional)	String	Short description about this GDPR field.

JSON Response

If your request to add a GDPR field to a list is successful a 201 - Created HTTP response will be signaled back.
The successful response will include a Location HTTP header with the URI of the resource created. You can see possible response statuses below for other cases.

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/gdpr/PROMOTION

Request body

{
    "name": "Product Promotion",
    "description": "We are contacting you about a certain product promotion"
}

Update a GDPR field of a list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/gdpr/{field}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
field	String	The identifier of the subscriber field.

Request body

Key	Type	Description
name	String	String containing your field's name.
description (*optional)	String	Short description about this GDPR field.

JSON Response

If your request to update a GDPR field on your list is successful a 200 - OK response code will be signaled back.
A successful response will include a Location HTTP header with the URI of the resource updated.
You can see possible response statuses below for other cases.

DATE_FORMATTER

Available Options	Example
dd-MM-yy	16-01-2019, 22-6-91
yy-MM-dd	2019-01-16, 91-6-22
MM-dd-yy	01-16-2019, 6-22-91
dd/MM/yy	16/01/2019, 22/6/91
yy/MM/dd	2019/01/16, 91/6/22
MM/dd/yy	01/16/2019, 6/22/91

Add Group

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/group

Request body

{
    "name": "Food",
    "type": "GROUP",
    "selectionType": "MULTIPLE",
    "groupOptionsOrientation": "DROPDOWN_LIST",
    "internal": false
}

Using this endpoint, you can add a Group to a list.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/group

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request body

Key	Type	Description
name	String	String containing your group’s name.
type	Enum	Available Options : GROUP Type of Group.
internal (*optional)	Boolean	A boolean indicates if this group is for internal use. An internal group will not show up on any forms. Defaults to false.
selectionType (*optional)	Enum	Available Options : SINGLE,MULTIPLE Selection Type of Group. Defaults to SINGLE
groupOptionsOrientation (*optional)	Enum	Available Options : VERTICAL, HORIZONTAL, DROPDOWN_LIST Indicates the orientation of subgroups. Defaults to VERTICAL

JSON Response

If your request to add a group to a list is successful a 201 - Created status code response will be signaled back. The successful response will include a Location header with the URI of the resource created.

Get Group

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/group/API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2

Response body

{
    "name": "API_GROUP",
    "field": "API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2",
    "type": "GROUP",
    "internal": false,
    "selectionType": "MULTIPLE",
    "options": [
        {
            "name": "API_GROUP_OPTION_1",
            "field": "API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902"
        },
        {
            "name": "API_GROUP_OPTION_3",
            "field": "API_GROUP_OPTION_3_f9d9e293-b69e-4baf-a89a-7d97d9a86f48"
        }
    ],
    "formHidden": false,
    "groupOptionsOrientation": "HORIZONTAL"
}

Use this endpoint to retrieve a specific Group by it's field.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/group/{group_field}

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of the group

JSON Response

Key	Type	Description
name	String	String containing your group’s name.
field	String	The ID of the group
type	Enum	Available Options : GROUP Type of Group.
internal	Boolean	A boolean indicates if this group is for internal use. An internal group will not show up on any forms. Defaults to false.
selectionType	Enum	Available Options : SINGLE,MULTIPLE Selection Type of Group. Defaults to SINGLE
options	List SUBGROUP	A list containing all of subgroups of the group.
groupOptionsOrientation	Enum	Available Options : VERTICAL, HORIZONTAL, DROPDOWN_LIST Indicates the orientation of subgroups. Defaults to VERTICAL
formHidden	Boolean	A Boolean to make this group visible/invisible in your sign up forms and landing pages. Defaults to false

JSON Response: SUBGROUP

Key	Type	Description
name	String	String containing subgroup’s name.
field	String	The ID of the subgroup

Update Group

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/group/API_GROUP_af44e02e-25ad-41d9-8bc2-906e91e3c23f

Request body

{
    "name": "Food",
    "type": "GROUP",
    "selectionType": "MULTIPLE",
    "groupOptionsOrientation": "DROPDOWN_LIST",
    "internal": false
}

Use this endpoint to update the properties of an existing group.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/group/{group_field}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of the group

Request body

Key	Type	Description
name	String	String containing your group’s name.
type	Enum	Available Options : GROUP Type of Group.
internal (*optional)	Boolean	A boolean indicates if this group is for internal use. An internal group will not show up on any forms. Defaults to false.
selectionType (*optional)	Enum	Available Options : SINGLE,MULTIPLE Selection Type of Group. Defaults to SINGLE
groupOptionsOrientation (*optional)	Enum	Available Options : VERTICAL, HORIZONTAL, DROPDOWN_LIST Indicates the orientation of subgroups. Defaults to VERTICAL

JSON Response

If your request to add a group to a list is successful a 200 - OK response status code response will be signaled back. The successful response will include a Location HTTP header with the URI of the resource updated.

Remove Group

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/group/API_GROUP_af44e02e-25ad-41d9-8bc2-906e91e3c23f

Using this endpoint, you can remove a group.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/group/{group_field}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of the group

JSON Response

If your request to remove a group is successful you will receive a 204 - No Content status code response

Add Subgroup

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2/option

Request body

{
    "name": "subgroup1"
}

Using this endpoint, you can add a subgroup to a specific group.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/{group_field}/option

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of group

Request body

Key	Type	Description
name	String	String containing your subgroup's name.

JSON Response

If your request to add subgroups to a group is successful a 201 - Created status code response will be signaled back. The successful response will include a Location header with the URI of the resource updated.

Add Subgroups

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2/options

Request body

{
    "name": ["subgroup1","subgroup2"]
}

Using this endpoint, you can add many subgroups to a specific group.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/{group_field}/options

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of group

Request body

Key	Type	Description
name	List	List of Strings containing your subgroups names.

JSON Response

Get Subgroup

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5e8c26c09997c6f7f17051cf/API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2/option/API_GROUP_OPTION_3_f9d9e293-b69e-4baf-a89a-7d97d9a86f48

Response body

{
    "name": "API_GROUP_OPTION_3",
    "field": "API_GROUP_OPTION_3_f9d9e293-b69e-4baf-a89a-7d97d9a86f48"
}

Use this endpoint to retrieve a specific Group's Subgroup by it's field.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/{group_field}/option/{option_field}

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of the group
option_field	String	The identifier of the subgroup

JSON Response

Key	Type	Description
name	String	String containing subgroup’s name.
field	String	The ID of the subgroup

Update Subgroup

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5e8c26c09997c6f7f17051cf/API_GROUP_58f14815-277d-428a-8a50-eb1070033ac2/SUBGROUP_4eded086-5e51-40c1-9c81-dbe9b53c230f

Request body

{
    "name": "updated_subgroup"
}

Using this endpoint, you can update a subgroup of a group.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/{group_field}/{option_field}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of group
option_field	String	The identifier of subgroup that will be updated

Request body

Key	Type	Description
name	String	String containing your groups name.

JSON Response

If your request to update a group option is successful a 200 - OK response status code will be signaled back. The successful response will include a Location HTTP header with the URI of the resource updated.

Remove Subgroup

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5e8c26c09997c6f7f17051cf/GROUP_b78f31c4-6235-4325-b89d-71bf7b1c613a/SUBGROUP_4eded086-5e51-40c1-9c81-dbe9b53c230f

Remove a Subgroup.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/list

HTTP Path: /{list_id}/{group_field}/{option_field}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeList writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
group_field	String	The identifier of group
option_field	String	The identifier of subgroup that will be deleted

JSON Response

If your request to remove a subgroup is successful you will receive a 204 - No Content status code response

Subscriber REST API

The Subscriber REST API provides an interface for manipulating your list subscribers.

A subscriber represents a customer or a business unit and can store personalization information that can be used to personalize your message content and apply a segmentation.

To get started, you need to sign up and login to our platform, where you can create an API key, and use that key within the HTTP headers for every request.

Add Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber

Request body

{
    "destination": "+306999999999",
    "status": "UNSUBSCRIBED",
    "email": "apifon@apifon.com",
    "email_status": "SUBSCRIBED",
    "subscriber_fields": {
         "EMPLOYEE_ID": 1,
         "FIRST_NAME": "John",
         "WORK_EMAIL": "john@apifon.com",
         "DEPARTMENT": "IT",
         "date_JOINED": 1560902400000
    },
    "gdpr_fields": {
          "PROMOTION": {
              "mobile": true,
              "email": false
          }
    },
    "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
}

Using this endpoint you can add a Subscriber into a list.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request body

Key	Type	Description
destination	String	The subscriber's destination (Mobile).
email	String	The subscriber's email . Only applicable on lists with type ADVANCED
status	Enum	The current mobile status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list . You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list . You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED mobile status automatically sends a sms message to the subscriber for him/her to confirm his/hers status.
email_status	Enum	The current email status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED email status automatically sends an email message to the subscriber for him/her to confirm his/hers status.
subscriber_fields (*optional)	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.
gdpr_fields (*optional)	Key-Value(GDPR_FIELDS*)	A list containing all of the GDPR field options of the Subscriber. Only applicable on lists with type ADVANCED.
groupOptions (*optional)	List	A list containing all of the subgroups we want to add for a subscriber

GDPR_FIELDS*

Key	Type	Description
mobile	Boolean	Indicates if a subscriber has given consent or not to receive message content based on a GDPR field.
email	Boolean	Indicates if a subscriber has given consent or not to receive email content based on a GDPR field.

JSON Response

We have an empty Response Body. If you update successfully a list , you will get a success code as response. You can see possible response statuses below.

Add Subscribers

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/bulk

Request body

{
  "update_on_duplicate": true,
  "subscribers": [
    {
      "destination": "+306911111111",
      "status": "UNSUBSCRIBED",
      "email": "apifon1@apifon.com",
      "email_status": "SUBSCRIBED",
      "subscriber_fields": {
        "EMPLOYEE_ID": 1,
        "FIRST_NAME": "John",
        "WORK_EMAIL": "john@apifon.com",
        "DEPARTMENT": "IT",
        "date_JOINED": 1560902400000
    },
    "gdpr_fields": {
      "PROMOTION": {
        "mobile": true,
        "email": false
      }
    },
    "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
    },
    {
      "destination": "+306922222222",
      "status": "SUBSCRIBED",
      "email": "apifon2@apifon.com",
      "email_status": "UNSUBSCRIBED",
      "subscriber_fields": {
        "EMPLOYEE_ID": 2,
        "FIRST_NAME": "Maria",
        "WORK_EMAIL": "maria@apifon.com",
        "DEPARTMENT": "IT",
        "date_JOINED": 1560902400000
    },
    "gdpr_fields": {
      "PROMOTION": {
        "mobile": true,
        "email": false
      }
    },
    "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
    }

  ]
}

Using this/hers endpoint you can add and/or update multiple Subscribers into a list.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber/bulk

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Request Body: Outer Level

Key	Type	Description
update_on_duplicate	boolean	A flag determining if the subscribers with a destination that already exists on a list will be updated or skipped. By default is set to false.
subscribers	SUBSCRIBERS*	An array of subscriber objects (more info below). [SUBSCRIBER_1, SUBSCRIBER_2, …]

Request Body: SUBSCRIBERS*

Key	Type	Description
destination	String	The subscriber's destination (Mobile).
email	String	The subscriber's email . Only applicable on lists with type ADVANCED
status	Enum	The current mobile status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list . You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list . You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED mobile status automatically sends a sms message to the subscriber for him/her to confirm his/hers status.
email_status	Enum	The current email status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED email status automatically sends an email message to the subscriber for him/her to confirm his/hers status.
subscriber_fields (*optional)	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.
gdpr_fields (*optional)	Key-Value(GDPR_FIELDS*)	A list containing all of the GDPR field options of the Subscriber. Only applicable on lists with type ADVANCED.
groupOptions (*optional)	List	A list containing all of the subgroups we want to add for a subscriber

GDPR_FIELDS*

Key	Type	Description
mobile	Boolean	Indicates if a subscriber has given consent or not to receive message content based on a GDPR field.
email	Boolean	Indicates if a subscriber has given consent or not to receive email content based on a GDPR field.

JSON Response

We have an empty Response Body. You can see possible response statuses below.
A success response, indicates that Apifon acknowledged your request and proceeds with processing the subscribers included in the request body.
You may receive a success response but if for example all subscribers are in the Bounce list, none of them will be added.

Update Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/7c845e6ece4f466f62f01767d0fd9cc4

Request body

{
    "destination": "+306999999999",
    "status": "UNSUBSCRIBED",
    "email": "apifon@apifon.com",
    "email_status": "SUBSCRIBED",
    "subscriber_fields": {
          "EMPLOYEE_ID": 5,
          "FIRST_NAME": "Jane",
          "WORK_EMAIL": "jane@apifon.com",
          "date_JOINED": 1560902400000
    },
    "gdpr_fields": {
          "PROMOTION": {
              "mobile": false,
              "email": false
          }
    },
    "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
}

Using this endpoint you can update an existing Subscriber. Updating a subscriber will also unarchive him/her if he was previously archived.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Path: /{lookup_md5}

HTTP Method: PUT

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
ist_id	String	The ID of the list
lookup_md5	String	A unique Identifier for the subscriber, you can use either destination_id or email_id.

Request body

Key	Type	Description
destination	String	The subscriber's destination (Mobile).
email	String	The subscriber's email . Only applicable on lists with type ADVANCED
status	Enum	The current mobile status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED mobile status automatically sends a sms message to the subscriber for him/her to confirm his/hers status.
email_status	Enum	The current email status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Inserting a subscriber with UNCONFIRMED email status automatically sends an email message to the subscriber for him/her to confirm his/hers status.
subscriber_fields (*optional)	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.
gdpr_fields (*optional)	Key-Value(GDPR_FIELDS*)	A list containing all of the GDPR field options of the Subscriber. Only applicable on lists with type ADVANCED.
groupOptions (*optional)	List	A list containing all of the subgroups we want to add for a subscriber

GDPR_FIELDS*

Key	Type	Description
mobile	Boolean	Indicates if a subscriber has given consent or not to receive message content based on a GDPR field.
email	Boolean	Indicates if a subscriber has given consent or not to receive email content based on a GDPR field.

JSON Response

We have an empty Response Body. If you update successfully a list , you will get a success code as response. You can see possible response statuses below.

Get Subscribers

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/subscriber/

Response body

{
          "meta": {
            "page": 1,
            "size": 200,
            "total": 1002
           },
           "links": {
            "prev": "",
            "next": "https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/subscriber?page=2&size=200",
            "first": "https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/subscriber?page=1&size=200",
            "last": "https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/subscriber?page=6&size=200"
           },
        "results": [
         {
          "meta": {
              "Etag": "9b914344475f6b31beec7a4decb5d93d"
          },
          "id": "5ce553637ed5cc369889bca6",
          "destination": "306999999999",
          "status": "SUBSCRIBED",
          "account_id": 1,
          "destination_id": "7c845e6ece4f466f62f01767d0fd9cc4",
          "date_created": 1558532963526,
          "date_updated": 1558534259428,
          "list_id": "5ce4fcef7ed5cc3898208e67",
          "gdpr_fields": {
           "PROMOTION": {
              "mobile": false
           }
          },
          "subscribers_fields": {
              "date_BIRTHDAY": 1558533285000
           }
         },
            "meta": {
              "Etag": "1a22b53bf247ef11772f994b4cd29ccb"
          },
          "id": "5ce682557ed5cc3698844a1a",
          "destination": "306999999998",
          "status": "SUBSCRIBED",
          "account_id": 1,
          "destination_id": "7b12a9860b3be7e786beba2351826616",
          "archived": false,
          "date_created": 1558610517617,
          "date_updated": 1558612770197,
          "list_id": "5ce4fcef7ed5cc3898208e67",
          "gdpr_fields": {
           "PROMOTION": {
              "mobile": true
           }
          },
          "form_urls": {
            "UNSUBSCRIBE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=607fe04e9997c6c209c02aab&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "PROFILE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "UNSUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=61a649a33f2869e5e35fbb7aff3a80d9&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "PROFILE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=61a649a33f2869e5e35fbb7aff3a80d9&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui"
            "UNSUBSCRIBE":"https://list-manage.apifon.com/listmanager/Apifon/profile/unsubscribe?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&u=YPimigcuBpatdpBMLcd4IhihMp6WNM9sHk2nFpvXUKq_kkwHZm1lbNck-ceIhtnJ",
            "PROFILE": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui"
            },
          "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
         },
        //Ommited...
       ]
}

Using this endpoint you can get all Subscribers of a list.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list

Query Parameters

Key	Type	Description
fields (*optional)	String	The fields you want to include in the response as comma-seperated input. Used for Partial Responses.
status (*optional)	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
email (*optional)	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
page (*optional)	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size (*optional)	Integer	The number of subscribers displayed on one page. Used for pagination. Max value for size is 200. If ommited, defaults to the max value.
sort (*optional)	String	Sort lists based on a field value. Used for sorting.
sort_dir (*optional)	Enum	Sorting Method. Available Options:DESC/ASC. Default: ASC. DESC: sort values in which the sorting starts from the highest value and proceeds to the lowest value. ASC: sort values in which the sorting starts from the lowest value and proceeds to the highest value. Used for sorting.

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
links	LINKS_DETAILS	Links used for pagination.
results	List of SUBSCRIBERS_DETAILS	A List with all selected lists.

JSON Response:META_DETAILS

Key	Type	Description
page	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size	Integer	The number of subscribers displayed on one page. Used for pagination. Max value for size is 200. If ommited, defaults to the max value.
total	Integer	Total number of pages. Used for pagination.

JSON Response:LINKS_DETAILS

Key	Type	Description
prev	String	The previous page of results. May be empty. Used for pagination.
next	String	The next page of results. May be empty. Used for pagination.
first	String	The first page of results. Used for pagination.
last	String	The last page of results. Used for pagination.

JSON Response:SUBSCRIBERS_DETAILS

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
id	String	The ID of the subscriber.
destination	String	The subscriber's destination.
email	String	The subscriber's email.
status	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
email_status	Enum	The current email status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
account_id	Integer	The account ID of the subscriber.
destination_id	String	Destination identifier of the subscriber. Can be used as lookup_MD5 parameter in endpoints. This is the MD5 hash of the subscribers destination.
archived	boolean	Signifies whether or not the subscriber is archived.
date_created	Epoch Timestamp	a Timestamp indicating the Date the subscriber was created.
date_updated	Epoch Timestamp	a Timestamp indicating the Date the subscriber was last updated.
list_id	String	The ID of the list.
gdpr_fields	Key-Value(GDPR_FIELDS)	A list containing all of the GDPR field options of the list. Only applicable on lists with type ADVANCED.
subscriber_fields (*optional)	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.
form_urls	FORM_URLS	Contains URLs to the list forms.
groupOptions (*optional)	List	A list containing all of the subgroups we want to add for a subscriber

Get Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/7c845e6ece4f466f62f01767d0fd9cc4

Response Body

{
          "meta": {
              "Etag": "9b914344475f6b31beec7a4decb5d93d"
          },
          "id": "5ce553637ed5cc369889bca6",
          "destination": "306999999999",
          "status": "SUBSCRIBED",
          "account_id": 1,
          "destination_id": "7c845e6ece4f466f62f01767d0fd9cc4",
          "archived": false,
          "date_created": 1558532963526,
          "date_updated": 1558534259428,
          "list_id": 5ce4fcef7ed5cc3898208e67,
          "gdpr_fields": {
           "PROMOTION": {
              "mobile": false
           }
          },
          "subscriber_fields": {
           "date_BIRTHDAY": 1558533285000
          },
          "form_urls": {
            "UNSUBSCRIBE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=607fe04e9997c6c209c02aab&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "PROFILE_MOBILE": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "UNSUBSCRIBE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/unsubscribe?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=61a649a33f2869e5e35fbb7aff3a80d9&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui",
            "PROFILE_EMAIL": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=61a649a33f2869e5e35fbb7aff3a80d9&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui"
            "UNSUBSCRIBE":"https://list-manage.apifon.com/listmanager/Apifon/profile/unsubscribe?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&u=YPimigcuBpatdpBMLcd4IhihMp6WNM9sHk2nFpvXUKq_kkwHZm1lbNck-ceIhtnJ",
            "PROFILE": "https://list-manage.apifon.com/listmanager/Apifon/profile?l=607fe04e9997c6c209c02aeb&f=e5335cbb-9480-471a-aee8-d87dd32e251f&c=d9e3110063ba107ab79340dceebc2d7b&u=IsVjj4P8RWhgDUWBUMQQUa0pQHauQ2bMNQ0i6F0SEfopJTcQFY5PTOac4OX-57ui"
            },
          "groupOptions":["SUBGROUP_0_cf54b8eb-5a01-42d7-b556-b42b1a2a0875","API_GROUP_OPTION_1_fa633bdd-12dc-4e78-a415-dc73212cc902","SUBGROUP2_3af4459c-4033-4ba0-9122-4db11767dbdf"]
}

Using this endpoint you can get all Subscribers of a list .

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Method: GET

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readSubscriber

Query Parameters

Key	Type	Description
fields (*optional)	String	The fields you want to include in the response as comma seperated input. Used for Partial Responses.

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
lookup_md5	String	A unique Identifier for the subscriber, you can use either destination_id or email_id.

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
id	String	The ID of the subscriber.
destination	String	The subscriber's destination.
email	String	The subscriber's email.
email_id	String	Email identifier of the subscriber. Can be used as lookup_MD5 parameter in endpoints. This is the MD5 hash of the subscribers email.
email_status	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
status	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
account_id	Integer	The account ID of the subscriber.
destination_id	String	Destination identifier of the subscriber. Can be used as lookup_MD5 parameter in endpoints. This is the MD5 hash of the subscribers destination.
date_created	Epoch Timestamp	a Timestamp indicating the Date the subscriber was created.
archived	boolean	Signifies whether or not the subscriber is archived.
date_updated	Epoch Timestamp	a Timestamp indicating the Date the subscriber was last updated.
list_id	String	The ID of the list.
gdpr_fields	Key-Value(GDPR_FIELDS)	A list containing all of the GDPR field options of the list. Only applicable on lists with type ADVANCED.
subscriber_fields	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.
form_urls	FORM_URLS	Contains URLs to the list forms.
groupOptions (*optional)	List	A list containing all of the subgroups we want to add for a subscriber

Json Response: META_DETAILS

Key	Type	Description
Etag	String	Entitytag

JSON Response: GDPR_FIELDS

Key	Type	Description
mobile	Boolean	Indicates if a subscriber has given consent or not to receive message content based on a GDPR field.
email	Boolean	Indicates if a subscriber has given consent or not to receive email content based on a GDPR field.

Json Response: FORM_URLS

Lists are now unified and combine the operations of mobile and email into a single form. The old/deprecated form urls are still operational for old lists supporting backwards compatibility.

Key	Type	Description
PROFILE_MOBILE	URL	Mobile Update form. DEPRECATED: Use unified PROFILE url instead.
UNSUBSCRIBE_MOBILE	URL	Mobile Unsubscribe form. DEPRECATED: Use unified UNSUBSCRIBE url instead.
PROFILE_EMAIL	URL	Email Update form. DEPRECATED: Use unified PROFILE url instead.
UNSUBSCRIBE_EMAIL	URL	Email Unsubscribe form. DEPRECATED: Use unified UNSUBSCRIBE url instead.
UNSUBSCRIBE	URL	Unifiled mobile/email Unsubscribe form.
PROFILE	URL	Unifiled mobile/email Profile form.

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

Query Subscribers

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/query

With this endpoint you can make conditions and query subscribers with these conditions.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Path: /query

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: readSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list.

Request Body

Request Body

{
          "conditions": [
              {
                    "name": "destination",
                    "op": "beginsWith",
                    "vl": "30699"
              }
          ],
          "fields": ["destination" , "status"],
          "sort": {
              "sort_dir": "DESC",
              "sort_field": "destination",
          },
          "page": "1",
          "size": 200,
}

Response Body

{
    "meta": {
       "page": 1,
       "size": 200,
       "total": 1002
    },
    "results": [
      {
          "destination": "306999999999",
          "status": "SUBSCRIBED",
      },
      {
          "destination": "30696999999998",
          "status": "SUBSCRIBED",
      },
      {
          "destination": "306999999997",
          "status": "SUBSCRIBED",
      },
      {
          "destination": "306999999996",
          "status": "SUBSCRIBED",
      },
       //Omitted...
      ]
}

Key	Type	Description
conditions (*optional)	List of CONDITIONS	A list of conditions that the subscribers must fullfil. Note: If multiple conditions are specified then only subscribers matching ALL of the conditions are returned.
sort (*optional)	Sort	sorting properties.
fields (*optional)	String	The fields you want to include in the response as comma-seperated input. Used for Partial Responses.
page	Integer	Current page of results. Used for pagination. If ommited, defaults to 1.
size	Integer	Number of subscribers displayed in one page. Used for pagination. Max value for size is 200. If ommited, defaults to the max value.

CONDITIONS

Key	Type	Description
name	String	The field on which to apply the condition. Inner fields can be accesed using dot notation, eg "subscriber_fields.FIRST_NAME".
op	Enum	The operator to apply. Available operators.
vl	Object	The value that the condition must match.

CONDITION_OPERATORS

Option	Description
eq (*)	Value must match exactly the given vl.
beginsWith	Value must begin with the given vl.
gte (*)	Value must be greater or equal than the given vl.
gt	Value must be greater than the given vl.
lte (*)	Value must be lower or equal than the given vl.
lt	Value must be lower than the given vl.
exists	Value must exist (Not null).
nexists	Value must not exist (null).

(*) This operator cannot be applied in date fields.

Sort

Key	Type	Description
sort_dir	Enum	Sorting Method. Available Options:DESC/ASC. Default: ASC. DESC: sort values in which the sorting starts from the highest value and proceeds to the lowest value. ASC: sort values in which the sorting starts from the lowest value and proceeds to the highest value. Used for sorting.
sort_field	String	Sorting is based at this field. If ommited, it defaults to "id" field.

JSON Response

Key	Type	Description
meta	META_DETAILS	Data information for the entity.
results	List of SUBSCRIBERS_DETAILS	A List with all selected lists.

Json Response: META_DETAILS

Key	Type	Description
page	Integer	Current page of results. Used for pagination.
size	Integer	The number of subscribers displayed on one page. Used for pagination.
total	Integer	Total number of subscribers. Used for pagination.

JSON Response: SUBSCRIBERS_DETAILS

Key	Type	Description
meta	RESULTS_META_DETAILS	Data information for the entity.
id	String	The ID of the subscriber.
destination	String	The subscriber's destination.
email	String	The subscriber's email .
email_id	String	Email identifier of the subscriber. Can be used as lookup_MD5 parameter in endpoints. This is the MD5 hash of the subscribers email.
email_status	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her emails. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her emails. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
status	Enum	The current status of the Subscriber. Available options: SUBSCRIBED : Subsciber subscribed to list. You can send him/her messages. UNSUBSCRIBED : Subsciber unsubscribed from the list. You can't send him/her messages. UNCONFIRMED: Only available in double OptIn lists. Subscriber status is pending.
account_id	Integer	The account ID of the subscriber.
destination_id	String	Destination identifier of the subscriber. Can be used as lookup_MD5 parameter in endpoints. This is the MD5 hash of the subscribers destination.
archived	boolean	Signifies whether or not the subscriber is archived.
date_created	Epoch Timestamp	A Timestamp indicating the Date the subscriber was created.
date_updated	Epoch Timestamp	A Timestamp indicating the Date the subscriber was last updated.
list_id	String	The ID of the list.
gdpr_fields	Key-Value(GDPR_FIELDS)	A list containing all of the GDPR field options of the list. Only applicable on lists with type ADVANCED.
subscriber_fields (*optional)	Key-Value	A list containing all of the subscriber fields of the list for a Subscriber.

Json Response: RESULTS_META_DETAILS

Key	Type	Description
Etag	String	Entitytag

JSON Response: GDPR_FIELDS

Key	Type	Description
mobile	Boolean	Indicates if a subscriber has given consent or not to receive message content based on a GDPR field.
email	Boolean	Indicates if a subscriber has given consent or not to receive email content based on a GDPR field.

Possible Response statuses

A status code for the given request that follows the http standards. (more info below)

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/709dcd7a6c63bde6685e78e17de83df7/subscribe

With this endpoint you can subscribe a subscriber in a list. Subscribing a subscriber will also unarchive him/her if he was previously archived.

Trying to subscribe a subscriber that is on blocked list will return an error response.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Path: /{lookup_md5}/subscribe

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
lookup_md5	String	A unique Identifier for the subscriber, you can use either destination_id or email_id.

JSON Response

We have an empty Response Body.

If you subscribe successfully a subscriber , you will get a success code as response.

You can see possible response statuses below.

Unsubscribe Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/709dcd7a6c63bde6685e78e17de83df7/unsubscribe

With this endpoint you can unsubscribe a subscriber in a list. Unsubscribing a subscriber will also unarchive him/her if he was previously archived.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Path: /{lookup_md5}/unsubscribe

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
lookup_md5	String	A unique Identifier for the subscriber, you can use either destination_id or email_id.

JSON Response

We have an empty Response Body.

If you unsubscribe successfully a subscriber , you will get a success code as response.

You can see possible response statuses below.

Remove Subscriber

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/list/5cc0794e7ed5cc5edc8f40a0/subscriber/a0162976c05ffe437a311a80cbd90267

With this endpoint you can archive or permanently delete a subscriber from a list. Archived subscribers will not be removed from the list but will not count towards your billing activities. Updating, subscribing or unsubscribing archived subscribers via the corresponding endpoints will unarchive them.

Host URL: https://ars.apifon.com

Service Endpoint: services/api/v1/list/{list_id}/subscriber

HTTP Path: /{lookup_md5}

HTTP Method: DELETE

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: writeSubscriber

Path Parameters

Key	Type	Description
list_id	String	The ID of the list
lookup_md5	String	A unique Identifier for the subscriber, you can use either destination_id or email_id.

Query Parameters

Key	Type	Description
permanent (*optional)	boolean	True to permanently delete the subscriber from the list. False to archive the subscriber. If ommited, defaults to false.

JSON Response

We have an empty Response Body.

If you archive or permanently remove a subscriber , you will get a success code as response.

You can see possible response statuses below.

SMS Gateway REST API

The SMS REST API provides an interface for sending SMS messages around the world.

To get started, you need to sign up and login to our platform, where you can create an SMS API key, and use that key within the HTTP headers for every request.

The SMS REST web service expects a JSON request that defines the message you wish to send. The service replies with a JSON response that acknowledges your request including an identifier for your reference. A callback service is also available that informs you of the delivery status of a message once it has been processed.

SMS Request

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/sms/send

Complete SMS Request body

{
    "subscribers": [{
            "number": "306999999999",
            "custom_id": "222",
            "params": {
                "apifon_lp": {
                    "url": "https://mookee.apifon.com/user/login/",
                    "data": {
                        "name": "Mr. John"
                    },
                    "redirect": true
                },
                "name": "John"
            }
        }
    ],
    "reference_id": "Campaign #215",
    "message": {
        "text": "Hello {name}! {apifon_lp}",
        "dc": 0,
        "sender_id": "Apifon"
    },
    "callback_url": "",
    "tte": "86400",
    "date": "2018-02-06T12:43:23"
}

Simple SMS Request Body

{
    "message": {
        "text": "Hello There!",
        "sender_id": "Apifon"
    },
    "subscribers": [{
            "number": "306999999999"
        }
    ]
}

Code Example

"String body" = "{\n" +
            "   \"subscribers\": [{\n" +
            "           \"number\": \"306999999999\",\n" +
            "           \"custom_id\": \"222\",\n" +
            "           \"params\": {\n" +
            "               \"apifon_lp\": {\n" +
            "                   \"url\": \"https://mookee.apifon.com/user/login/\",\n" +
            "                   \"data\": {\n" +
            "                       \"name\": \"Mr. John\"\n" +
            "                   },\n" +
            "                   \"redirect\": true\n" +
            "               },\n" +
            "               \"name\": \"John\"\n" +
            "           }\n" +
            "       }\n" +
            "   ],\n" +
            "   \"reference_id\": \"Campaign #215\",\n" +
            "   \"message\": {\n" +
            "       \"text\": \"Hello {name}! {apifon_lp}\",\n" +
            "       \"dc\": 0,\n" +
            "       \"sender_id\": \"Apifon\"\n" +
            "   },\n" +
            "   \"callback_url\": \"\",\n" +
            "   \"tte\": \"86400\",\n" +
            "   \"date\": \"2018-02-06T12:43:23\"\n" +
            "}";

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/sms

HTTP Path: /send

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: smsGateway

The request is encoded in JSON, and is split in several levels. Each table below will represent a level, starting with the outermost one.

Request Body: Outer Level

Key	Type	Description
subscribers	SUBSCRIBERS*	An array of subscriber objects (more info below). [SUBSCRIBER_1, SUBSCRIBER_2, …]
reference_id (*optional)	String	Include any reference string for your reference. Useful for your internal reports (255 characters max).
message	MESSAGE**	Defines the content of your message (more info below).
callback_url (*optional)	String	If set, the callback (delivery / status report) will be delivered to this URL, otherwise no callback will take place. Must be a valid URL starting with https://. For example https://yourserver/callback. A valid signed certificate must be used.
tte (*optional)	String	If the value inside the string is an integer, then tte is the Validity Period in seconds. Otherwise, the value inside the string must be a date with the format “yyyy-MM-dd’T’HH:mm:ss”. This sets the length of time, in seconds, for which Apifon will attempt to send the message. Note that this does not guarantee a message will be delivered within the specified time, as not all network operators will honor this value. Minimum value is 60 seconds, and maximum is 48 hours. If any of these limits are exceeded then the closest limit gets applied. Default (when not supplied, or when set to 0): 8 hours.
date (*optional)	String	The date that the message will be sent on UTC/GMT timezone – if omitted it will be sent immediately. Format: "yyyy-MM-dd'T'HH:mm:ss".

Request Body: SUBSCRIBERS*

Key	Type	Description
number	String	Mobile number (MSISDN) to deliver the message to. Number is in international format and is only digits between 7-15 digits long. First digit cannot be a 0.
custom_id (*optional)	String	ID for the specific subscriber.
params (*optional)	Key-Value	If your message content contains placeholders for personalized messages per destination, this field is required to populate the value for each recipient. For further details, see the MESSAGE** table in the next page. This field can also contain one or more landing pages for the specific subscriber using a LANDING object as a value. Please note that every non-LANDING parameter value should be a String for proper replacement on SMS text content.

Request Body: MESSAGE**

Key	Type	Description
text	String	Contains the body of the SMS message to be delivered to the destination device. One can optionally specify keys within the message body that will be replaced later with values given by the params field in the SUBSCRIBERS* object. See 'params' in the SUBSCRIBERS* section for more information on supplying the value for these keys. Each placeholder must be specified as {KEY}, where KEY is a key name in the params list. For this feature to be used, GSM7 or UCS2 encoding must be used. In the event your text is longer than 160 characters in 7bit, 140 in 8bit or 70 in 16bit, Apifon will split the message into parts. In that case, the response will tell you how many parts the message has been sent in. If one or more LANDING pages are defined, {apifon_lp*} parameters will be replaced with the shortened url parameter of the landing object.
dc (*optional)	Data coding	Contains the information on how the text is encoded. Defaults to ‘0’. It can only be a number in the rand [0-2].The maximum number of characters you can fit into a single message depends on the encoding you are using: [0]: GSM7 bit Default Alphabet (160). Basic Latin subset of ASCII, as well as some characters of the ISO Latin 1 – 160 [1]: GSM 8-bit data encoding (140). 8-bit data encoding mode treats the information as raw data. According to the standard, the alphabet for this encoding is user-specific. [2]: UCS-2 (UTF-16 [16 bit]) Encoding (70). This encoding allows use of a greater range of characters and languages. UCS-2 can represent the most commonly used Latin and eastern characters at the cost of a greater space expense.
sender_id	String	The sender ID (a.k.a. from) for the SMS delivery. The sender ID can contain numbers or/and Latin characters. If numeric, minimum length is 1, maximum length is 16 digits. If alphanumeric, minimum length is 1, maximum length is 11 characters.

Request Body: LANDING PAGE***

Example Request - Multiple landing pages

{
    "message": {
        "text": "Hello There! Click the link {apifon_lp_company} to visit our site and place your order. You can view our privacy policy at {apifon_lp_privacy} for your convenience.",
        "sender_id": "Apifon"
    },
    "subscribers": [{
            "number": "306999999999",
            "params" : {
                "apifon_lp_company" : {
                    "url" : "https://www.apifon.com",
                    "method" : "GET"
                },
                "apifon_lp_privacy" : {
                    "url" : "https://www.apifon.com/privacy",
                    "method" : "GET"
                }
            }
        }
    ]
}

You may include one or more parameters in the "param" field of the request if you wish to include hyperlinks in your message that will be shortened and tracked on click. Each landing parameter should be prefixed with "apifon_lp_" and a keyword of your preference. The content of the message should include the key that will be replaced with your shortened URL on the SMS message. Please note that any landing parameters NOT referenced in the content of your message will not be shortened.

Key	Type	Description
url	String	The url or the template ID of the given landing page.
data (*optional)	Key-Value	If the landing page content contains placeholders for personalized pages per destination, this field is required to populate the value for each recipient.
redirect (*optional)	Boolean	A flag determining if the shortened url will redirect to the landing page url. By default redirect is set to true.
method (*optional)	Enum	The http method that shortened url will use to direct to the landing page url. Set value only if redirect is set to false. If ommited, defaults to "GET". ["GET"]: The short url will direct to the landing page url using a GET request. ["POST"]: The short url will direct to the landing page url using a POST request.
prevent_sys_params (*optional)	Boolean	A flag determining if the System Parameters will be forwarded to URL as Query Parameters. By default prevent_sys_params is set to false.
landing_domain (*optional)	String	If set, your domain will be used instead of Apifon's landing domain http://apfn.eu. Must be a valid URL, starting with http:// or https://. If you wish to purchase your own custom domain for shortening please contact us.
enable_tracking (*optional)	Boolean	Determines if you wish to enable tracking on your link. If disabled your link will be shortened but clicks will not be tracked. By default is set to true if ommited.

SMS Response

Response body

{
  "request_id": "eff655d8-0cb6-47b3-8828-96e1b80b55af",
  "reference": "Campaign #215",
  "results": {
    "306999999999": [{
        "message_id": "e2d4424d-7d6a-49c2-b564-99b2b68c74cb",
        "custom_id": "222",
        "length": 11,

        "short_code": "123456",
        "short_url": "https://apfn.eu/123456",
        "landing_pages" : {
            "apifon_lp" : {
                "short_code" : "123456",
                "short_url" : "https://apfn.eu/123456"
            }
        }
            }
        }
      }
    ]
  },
  "result_info": {
    "status_code": 200,
    "description": "OK"
  }
}

After submitting a request using Apifon API, you will receive an HTTP response and a delivery receipt to your submitted Callback URL (if you have indicated one on your request). The HTTP response will contain a JSON object. The actual delivery status of the message is only confirmed by the delivery receipt.

JSON Response

Key	Type	Description
request_id	String	A generated id for the given request.
reference	String	Whatever the user passed into reference_id.
results	Map < String, RESULT_DETAILS >	A Map with the results for every subscriber. The map key is the subscriber number and the value for any entry is an array of detail objects.
result_info	RESULT_INFO	A summary of the status of the request.

JSON Response: RESULT_DETAILS

Key	Type	Description
message_id	String	A generated id for the new message.
custom_id	String	The custom id that the user gave.
length	Int	The message size in bytes.
short_url	String	Now deprecated, use landing_pages instead. Contains the shortened version of the url, if the request contained a landing page. If multiple LANDING parameters are included in your request the first parameter encountered will be placed here.
short_code	String	Now deprecated, use landing_pages instead. Contains the generated shortened code used by the short_url if the request contained a landing page. If multiple LANDING parameters are included in your request the first parameter encountered will be placed here.
landing_pages	Map < String, LANDING_PAGES >	A map of all detected shortening request parameters and their respective shortened URLs & short codes.

JSON Response: LANDING_PAGES

Key	Type	Description
short_url	String	The shortened version of the URL
short_code	String	The generated short code used by the short_url

JSON Response: RESULT_INFO

Key	Type	Description
status_code	String	A status code for the given request that follows the http standards ( 200 if OK, 403 if parameters are wrong, 401 if authentication error).
description	String	A human friendly message that describes the status code.

SMS Reply Callback

Reply Callback

{
    "message_id": "d5a53b51-dc57-4c2c-b880-36f788c4d4d4",
    "from": "306999999999",
    "to": "306988888888",
    "text": "This is my reply.",
    "timestamp": 1481126247,
    "type": "SMS"
}

HTTP Method: POST

Content-Type: application/json; charset=utf-8

When a subscriber responds on a 2-way message, a callback is generated and signaled back to the client using an HTTP callback. The request generated to this URL is described here. The endpoint on the client side must fully support this kind of request and respond accordingly. In case of delivery failure, the callback will be resent three more time with a two minute gap.

Key	Type	Description
message_id	String	A generated id for the new message.
from	String	The number of the subscriber.
to	String	The sender id of the original message request.
text	String	Contains the body of the subscriber's response.
timestamp	int	The timestamp the message arrived.
type	String	The type of the channel the subscriber used to create the reply.

Delete Scheduled SMS

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/sms/remove

Request body

{
 "id": "adbfbe48-82e7-49d5-af1a-e5b284cf5bf3",
 "field": "REQUEST_ID"
}

Response body

Code Example

"String body" = "{\n" +
            " \"id\": \"adbfbe48-82e7-49d5-af1a-e5b284cf5bf3\",\n" +
            " \"field\": \"REQUEST_ID\"\n" +
            "}";

The deletion service can be used to remove scheduled SMSs.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/sms

HTTP Path: /remove

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: smsGateway

Request

The request object consists of two keys, the field and the id, as explained in the following table.

Key	Type	Description
field	String	We can delete messages based on their request id and their reference id. So if you want to delete using the request id then the field must be equal to “REQUEST_ID”, otherwise the field must be equal to “REFERENCE_ID”.
id	String	The value of the field.

Response

The response is an integer that shows the number of the deleted messages.

IM Gateway REST API

The IM REST API provides an interface for sending IM and SMS messages around the world.

To get started, you need to have an Account on our platform, an API Token with Viber scope enabled, and use that Token within the HTTP headers for every request. Each Token includes a routing preference (lowest cost or feature-first). New Tokens default to lowest cost. You can request a change to the routing preference from your Account Manager.

The IM REST web service expects a JSON request that defines the action you wish to perform. The service replies with a JSON response that acknowledges your request including an identifier for your reference. A callback service is also available that informs you of the delivery status of a message once it has been processed.

Functionality offered by the platform includes the ability to send text, images, videos, files, action buttons via IM, receive replies from recipients via 2-way messaging, and SMS Failover (automatically send SMS if IM delivery is not possible).

IM Failover to SMS

To enable SMS Failover, include message in your IM request. SMS Failover is triggered instantly once the IM message receives one of the following Statuses:

unknown_user
no_active_subscription
expired ()

The following diagram demonstrates the flow:

IM Request

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/im/send

Complete IM Request body

{
  "subscribers": [{
      "number": "306999999999",
      "custom_id": "222",
      "params": {
        "apifon_lp": {
          "url": "https://mookee.apifon.com/user/login/",
          "data": {
            "name": "John"
          },
          "redirect": true,
          "method": "GET"
        },
        "name": "John"
      }
    }
  ],
  "reference_id": "Campaign #216",
  "message": {
    "text": "Hello {name}! {apifon_lp}",
    "dc": 0,
    "sender_id": "Apifon"
  },
  "callback_url": "",
  "reply_url": "",
  "im_channels": [{
      "id": "channelID",
      "sender_id": "Mookee",
      "text": "{name}! 50% discount on our membership fee if you renew your subscription today!",
      "images": ["http://assets.apifon.com/images/boy_girl.jpg"],
      "actions": [{
          "title": "Renew now!",
          "target_url": "https://www.apifon.com"
        }
      ],
      "ttl": 86400,
      "expiry_text": "Message Expired!!"
    }
  ],
  "date": "2018-02-06T13:18:25"
}

Simple IM Request Body

{
    "message": {},
    "callback_url": "",
    "im_channels": [{
            "sender_id": "Mookee",
            "text": "50% discount on our membership fee if you renew your subscription today!"
        }
    ],
    "subscribers": [{
            "number": "306999999999"
        }
    ]
}

Code Example

"String body" = "{\n" +
            "  \"subscribers\": [{\n" +
            "      \"number\": \"306999999999\",\n" +
            "      \"custom_id\": \"222\",\n" +
            "      \"params\": {\n" +
            "        \"apifon_lp\": {\n" +
            "          \"url\": \"https://mookee.apifon.com/user/login/\",\n" +
            "          \"data\": {\n" +
            "            \"name\": \"John\"\n" +
            "          },\n" +
            "          \"redirect\": true,\n" +
            "          \"method\": \"GET\"\n" +
            "        },\n" +
            "        \"name\": \"John\"\n" +
            "      }\n" +
            "    }\n" +
            "  ],\n" +
            "  \"reference_id\": \"Campaign #216\",\n" +
            "  \"message\": {\n" +
            "    \"text\": \"Hello {name}! {apifon_lp}\",\n" +
            "    \"dc\": 0,\n" +
            "    \"sender_id\": \"Apifon\"\n" +
            "  },\n" +
            "  \"callback_url\": \"\",\n" +
            "  \"reply_url\": \"\",\n" +
            "  \"im_channels\": [{\n" +
            "      \"id\": \"channelID\",\n" +
            "      \"sender_id\": \"Mookee\",\n" +
            "      \"text\": \"{name}! 50% discount on our membership fee if you renew your subscription today!\",\n" +
            "      \"images\": [\"http://assets.apifon.com/images/boy_girl.jpg\"],\n" +
            "      \"actions\": [{\n" +
            "          \"title\": \"Renew now!\",\n" +
            "          \"target_url\": \"https://www.apifon.com\"\n" +
            "        }\n" +
            "      ],\n" +
            "      \"ttl\": 86400,\n" +
            "      \"expiry_text\": \"Message Expired!!\"\n" +
            "    }\n" +
            "  ],\n" +
            "  \"date\": \"2018-02-06T13:18:25\"\n" +
            "}";

The request is encoded in JSON, and is split in several levels. Each table below will represent a level, starting with the outermost one.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/im

HTTP Path: /send

Content-Type: application/json; charset=utf-8

HTTP Method: POST

OAuth2 Scopes Required: imGateway

OUTER LEVEL

Key	Type	Description
subscribers	SUBSCRIBERS	An array of subscriber objects (more info below). [SUBSCRIBER_1, SUBSCRIBER_2, …]
reference_id (*optional)	String	Include any reference string for your reference. Useful for your internal reports (255 characters max).
message (*optional)	MESSAGE	If Viber delivery fails, this message will be sent as SMS instead.
callback_url (*optional)	String	If set, the callback (delivery / status report) will be delivered to this URL, otherwise no callback will take place. Must be a valid URL starting with https://. For example https://yourserver/callback. A valid signed certificate must be used.
reply_url (*optional)	String	If set, any replies sent by the recipient of this message will generate a message-reply callback that will be delivered to the URL given by this field. In order to use this feature, 2-way messaging must be enabled on the Sender ID specified in this message. To enable 2-way messaging on a sender ID, please login to the control panel on our platform, or ask for assistance. Must be a valid URL starting with https://, meaning that a valid signed certificate must be used. You can view the callbacks in this section.
im_channels	Array [IMChannel]	Array of various IM channels that will be used to send the message. [IMChannel_1, IMChannel_2, …]
date (*optional)	String	The date that the message will be sent on UTC/GMT TIMEZONE – if omitted it will be sent immediately. Format: "yyyy-MM-dd'T'HH:mm:ss".

SUBSCRIBERS

Key	Type	Description
number	String	Mobile number (MSISDN) to deliver the message to. Number is in international format and is only digits between 7-15 digits long. First digit cannot be a 0.
custom_id (*optional)	String	ID for the specific subscriber
params (*optional)	Key-Value	If your message content contains placeholders for personalized messages per destination, this field is required to populate the value for each recipient. For further details, see the MESSAGE table in the next page. This field can also contain one or more landing pages for the specific subscriber using a LANDING object as a value. Please note that every non-LANDING parameter value should be a String for proper replacement on IM and possible failover SMS content.

MESSAGE

Key	Type	Description
text	String	Contains the body of the SMS message to be delivered to the destination device. One can optionally specify keys within the message body that will be replaced later with values given by the params field in the Subscribers object. See ‘params’ in the SUBSCRIBERS section for more information on supplying the value for these keys. Each placeholder must be specified as {KEY}, where KEY is a key name in the params list. For this feature to be used, GSM7 or UCS2 encoding must be used. In the event your text is longer than 160 characters in 7bit, 140 in 8bit or 70 in 16bit, Apifon will split the message into parts. In that case, the response will tell you how many parts the message has been sent in. If one or more LANDING pages are defined, {apifon_lp*} parameters will be replaced with the shortened url parameter of the landing object.
dc (*optional)	Data coding	Contains the information on how the text is encoded. Defaults to ‘0’. It can only be a number in the rand [0-2]. The maximum number of characters you can fit into a single message depends on the encoding you are using: [0]: GSM7 bit Default Alphabet (160). Basic Latin subset of ASCII, as well as some characters of the ISO Latin 1 – 160. [1]: GSM 8-bit data encoding (140). 8-bit data encoding mode treats the information as raw data. According to the standard, the alphabet for this encoding is user-specific. [2]: UCS-2 (UTF-16 [16 bit]) Encoding (70). This encoding allows use of a greater range of characters and languages. UCS-2 can represent the most commonly used Latin and eastern characters at the cost of a greater space expense.
sender_id	String	The sender ID (a.k.a. from) for the SMS delivery. The sender ID can contain numbers or/and Latin characters. If numeric, minimum length is 1, maximum length is 16 digits. If alphanumeric, minimum length is 1, maximum length is 11 characters.

Request Body: LANDING PAGE

Example Request - Multiple landing pages

{
    "message": {
        "text" : "Hello, here is your failover SMS with a link to our site {apifon_lp_company}",
        "dc" : 0,
        "sender_id" : "Apifon"
    },
    "im_channels": [{
            "sender_id": "Mookee",
            "text": "Hello There! Click the link {apifon_lp_company} to visit our site and place your order. You can view our privacy policy at {apifon_lp_privacy} for your convenience."
        }
    ],
    "subscribers": [{
            "number": "306999999999",
            "params" : {
                "apifon_lp_company" : {
                    "url" : "https://www.apifon.com",
                    "method" : "GET"
                },
                "apifon_lp_privacy" : {
                    "url" : "https://www.apifon.com/privacy",
                    "method" : "GET"
                }
            }
        }
    ]
}

You may include one or more parameters in the "param" field of the request if you wish to include hyperlinks in your message that will be shortened and tracked on click. Each landing parameter should be prefixed with "apifon_lp_" and a keyword of your preference. The content of the message should include the key that will be replaced with your shortened URL on the IM message and a possible SMS failover.
Any landing parameters NOT referenced in the content of your message will not be shortened.

Key	Type	Description
url	String	The url or the template ID of the given landing page.
data (*optional)	Key-Value	If the landing page content contains placeholders for personalized pages per destination, this field is required to populate the value for each recipient.
redirect (*optional)	Boolean	A flag determining if the shortened url will redirect to the landing page url. By default redirect is set to true.
method (*optional)	Enum	The http method that shortened url will use to direct to the landing page url. Set value only if redirect is set to false. By default if ommited is set to "GET". ["GET"]: The short url will direct to the landing page url using a GET request. ["POST"]: The short url will direct to the landing page url using a POST request.
prevent_sys_params (*optional)	Boolean	A flag determining if the System Parameters will be forwarded to URL as Query Parameters. If ommited, prevent_sys_params defaults to false.
landing_domain (*optional)	String	If set, your domain will be used instead of Apifon's landing domain http://apfn.eu. Must be a valid URL, starting with http:// or https://. If you wish to purchase your own custom domain for shortening please contact us.
enable_tracking (*optional)	Boolean	Determines if you wish to enable tracking on your link. If disabled your link will be shortened but clicks will not be tracked. If ommited, defaults to true .

IMChannel

Key	Type	Description
id (*optional)	String	The channel id. If id is not set, the channel ID defined in the token provided is used.
sender_id (*optional)	String	The sender id. If sender_id is not set, the sender_id defined in the token provided is used.
text (*conditional)	String	The message content. It can be formatted by adding specific markdown characters to any text string. The maximum limit is 1000 characters. If a LANDING page is defined, {apifon_lp*} parameters will be replaced with the shortened url of the landing object. Viber deep links are also permittable.
images (*conditional)	Array	Array of objects containing the images of the IM message to send, if message includes images. For Viber, the maximum size of the array is 1, as only one image is supported per message. Recommended image size: 800x800px. Recommended formats: PNG, JPEG, JPG.
actions (*conditional)	Array [IM-ACTION]	Array of objects describing the action buttons of the IM message to send. For Viber, the maximum size of the array is 1, as only one button is supported per message.
videos (*conditional)	Array [IM-VIDEO]	Array of objects describing the videos of the IM message to send. For Viber, the maximum size of the array is 1, as only one video is supported per message.
ttl (*optional)	IntVal	Each Viber message can be sent with a predefined Time to Live (TTL) value. TTL will determine the time period of delivery attempts before the message expires. The minimum value is 30 (seconds), while the maximum value is 86400 (24 hours). If omitted, defaults to maximum.
expiry_text (*optional)	String	If the message gets delivered after ttl has passed, then this text will appear instead.
device_target (*optional)	Enum	This field can be used in order to target a specific device when sending a Viber Message in case a user has multiple devices. Available Options: SMARTPHONE_ONLY/SMARTPHONE_AND_OTHER_DEVICES. Default: "SMARTPHONE_AND_OTHER_DEVICES".

IM-ACTION

Key	Type	Description
title	String	The caption text to display on the button. It cannot exceed 30 characters.
target_url	String	The HTTP URL that will be called on the click event for this action. You can also lead your subscribers to online hosted files by specifying the URL as the file's public link. The URL must be url-encoded. Viber deep links are also permittable.

IM-VIDEO

Example Request - Viber Video

{
    "subscribers": [
        {
            "number": "306999999999",
            "params": {
                "name": "John"
            }
        }
    ],
    "im_channels": [
        {
            "sender_id": "Mookee",
            "text": "{name}! 50% discount on our membership fee if you renew your subscription today!",
            "videos": [
                {
                    "video_content_length": 912534,
                    "video_url": "https://assets.apifon.com/videos/apifon_video_example.mp4",
                    "video_duration": 15,
                    "thumbnail_image_url": "https://assets.apifon.com/images/apifon-thumbnail.png",
                    "video_content_type": "mp4",
                    "video_caption": "Hello there!"
                }
            ]
        }
    ]
}

Key	Type	Description
video_url	String	The HTTP URL of the video, the server hosting the video should allow HEAD methods and include the file 'Content-Length' in server reply.
video_content_length	int	The size of the video file in bytes. The maximum value is 200MB.
video_duration	int	The duration of the video in seconds. The maximum value is 600 seconds.
thumbnail_image_url	String	The url of a static image that acts as the preview image for the video. The maxium length of the URL is 1000 characters.
video_content_type	String	The type of the video file. Allowed video formats are 3gp, m4v, mov & mp4. For device parsability, mp4 is highly recommended.
video_caption (*optional)	String	The caption text to display on the button. It cannot exceed 30 characters. The URL that will be called on the click event of this button is the video url. If no caption is added then the message will not have a button.

Viber Text Formatting

Viber messages can be formatted by adding specific markdown characters to any text string using the following markdown guidelines:

Format	Markdown	Message string	Appearance on message
Bold	One asterisk (*) surrounding the text	Bold text	Bold text
Italics	One underscore (_) surrounding the text	_italicized tex_	italicized tex
Monospace	Three brackets (```) surrounding the text	```monospaced text```	`monospaced text`
Strikethrough	One tilden(~) surrounding the text	~text with strikethrough~	~~text with strikethrough~~

Markdown symbols need to be adjacent to the first and last characters of the formatted text. If they are attached to both sides, or aren't atatched at all then no formatting will take place.

*Viber* message will be Viber message.
*Viber*message will be *Viber*message.
*Viber * message will be *Viber * message.

Formatted messages sent back from users will display the markdown symbols on the reply callback. For example:

User sent: Hello
Reply callback text: *Hello*

Deep Links

Deep links allow you to create a shortcut to a specific action within an app. Deep links are permittable for use either on the text itself or as the redirect link of the action button. It is highly recommended to shorten deep links with an http(s):// prefix.
You can find the available Viber Deep Links in our Knowledge base.

Conditional Note

The IMChannel content must follow one of the following patterns:

Content	Type	Description
Text	Transactional	An IM message is send containing only a text message.
Image	Promotional	An IM message is send containing only an image.
Text & Action	Promotional	An IM message is send containing a text message and an Action content.
Text & Image & Action	Promotional	An IM message is send containing a text message, and image and an Action content.
Video	Promotional	An IM message is send containing only a video.
Text & Video	Promotional	An IM message is send containing a text message, and a video.
Text & Video & Button	Promotional	An IM message is send containing a text message, a video and a button.

IM File Request

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/im/file

Complete IM File Request body

{
  "subscribers": [{
      "number": "306999999999",
      "custom_id": "222"
    }
  ],
  "reference_id": "Campaign #216",
  "callback_url": "",
  "reply_url": "",
  "im_channels": [{
      "id": "channelID",
      "sender_id": "Mookee",
      "file_name": "myFile.pdf",
      "file_type": "pdf",
      "file_url": "http://asdfghjk/sample.pdf"
      "ttl": 86400
    }
  ],
  "date": "2018-02-06T13:18:25"
}

Simple IM File Request Body

{
    "im_channels": [{
        "sender_id": "Mookee",
        "file_name": "myFile.pdf",
        "file_type": "pdf",
        "file_url": "http://asdfghjk/sample.pdf"
        }
    ],
    "subscribers": [{
            "number": "306999999999"
        }
    ]
}

Code Example

 String s = "{\n"
            + "  \"subscribers\": [{\n"
            + "      \"number\": \"306999999999\",\n"
            + "      \"custom_id\": \"222\"\n"
            + "    }\n"
            + "  ],\n"
            + "  \"reference_id\": \"Campaign #216\",\n"
            + "  \"callback_url\": \"\",\n"
            + "  \"reply_url\": \"\",\n"
            + "  \"im_channels\": [{\n"
            + "      \"id\": \"channelID\",\n"
            + "      \"sender_id\": \"Mookee\",\n"
            + "   \"file_name\": \"myFile.pdf\",\n"
            + "   \"file_type\": \"pdf\",\n"
            + "   \"file_url\": \"http://asdfghjk/sample.pdf\"\n"
            + "      \"ttl\": 86400\n"
            + "    }\n"
            + "  ],\n"
            + "  \"date\": \"2018-02-06T13:18:25\"\n"
            + "}";

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/im

HTTP Path: /file

Content-Type: application/json; charset=utf-8

HTTP Method: POST

OAuth2 Scopes Required: imGateway

Use this endpoint to send file type IM messages. The request is encoded in JSON, and is split in several levels. Each table below will represent a level, starting with the outermost one.

OUTER LEVEL

Key	Type	Description
subscribers	SUBSCRIBERS*	An array of subscriber objects (more info below). [SUBSCRIBER_1, SUBSCRIBER_2, …]
reference_id (*optional)	String	Include any reference string for your reference. Useful for your internal reports (255 characters max).
callback_url (*optional)	String	If set, the callback (delivery / status report) will be delivered to this URL, otherwise no callback will take place. Must be a valid URL starting with https://. For example https://yourserver/callback. A valid signed certificate must be used.
reply_url (*optional)	String	If set, any replies sent by the recipient of this message will generate a message-reply callback that will be delivered to the URL given by this field. In order to use this feature, 2-way messaging must be enabled on the Sender ID specified in this message. To enable 2-way messaging on a sender ID, please login to the control panel on our platform, or ask for assistance. Must be a valid URL starting with https://, meaning that a valid signed certificate must be used. You can view the callbacks in this section.
im_channels	Array [IMChannel]	Array of IM channels that will be used to send the file message. [IMChannel_1, IMChannel_2, …]
date (*optional)	String	The date that the message will be sent on UTC/GMT TIMEZONE – if omitted it will be sent immediately. Format: "yyyy-MM-dd'T'HH:mm:ss".

SUBSCRIBERS*

Key	Type	Description
number	String	Mobile number (MSISDN) to deliver the message to. Number is in international format and is only digits between 7-15 digits long. First digit cannot be a 0.
custom_id (*optional)	String	ID for the specific subscriber

IMChannel

Key	Type	Description
id (*optional)	String	The channel id. If id is not set, the channel ID defined in the token provided is used.
sender_id (*optional)	String	The sender id. If sender_id is not set, the sender_id defined in the token provided is used.
file_name	String	The name for the file displayed on the message. Maximum of 25 characters.
file_type	String	The type format of the file. Refer to the table [File Types] below for allowed formats.
file_url	String	The url hosting the file. Must be a valid URL.
ttl (*optional)	IntVal	Each Viber message can be sent with a predefined Time to Live (TTL) value. TTL will determine the time period of delivery attempts before the message expires. The minimum value is 30 (seconds), while the maximum value is 86400 (24 hours). If omitted, defaults to maximum.

File Types

The file formats allowed for IM file type messages:

File Type	File Formats
Documents	.doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info
PDF	.pdf, .xps, .pdax, .eps
Spreadsheet	.xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

IM Response

Response body

{
  "request_id": "ccb9111f-9ea0-4e01-882f-f72ee502e779",
  "reference": "Campaign #216",
  "results": {
    "306999999999": [{
        "message_id": "6f3f5441-391f-473d-b822-cfb129f21238",
        "custom_id": "222",
        "length": 80,
        "short_code": "123456",
        "short_url": "https://apfn.eu/123456",
        "landing_pages" : {
            "apifon_lp" : {
                "short_code" : "123456",
                "short_url" : "https://apfn.eu/123456"
            }
        }
            }
        }
      }
    ]
  },
  "result_info": {
    "status_code": 200,
    "description": "OK"
  }
}

When responding, the REST API will make use of the appropriate and relevant HTTP status code to describe the nature of the result. For non-200 response codes, not all of the fields described in Outer Response, RESULT Item, and RESULT_DETAIL Item might be present.

View the response codes here.

After submitting a request using Apifon API, you will receive an HTTP response and a delivery receipt to your submitted Callback URL (if you have indicated one on your request). The HTTP response will contain a JSON object. The actual delivery status of the message is only confirmed by the delivery receipt.

JSON response

Key	Type	Description
request_id	String	A generated id for the given request.
reference	String	Whatever the user passed into reference_id
results	Hashmap < String, RESULT_DETAILS >	A hashmap with the results for every subscriber. The map key is the subscriber number and the value for any entry is an array of detail objects.
result_info	RESULT_INFO	A summary of the status of the request.

RESULT_DETAILS

Key	Type	Description
message_id	String	A generated id for the new message.
custom_id	String	The custom id that the user gave.
length	Int	The number of characters that the message contains.
short_url	String	Now deprecated, use landing_pages instead. Contains the shortened version of the url, if the request contained a landing page. If multiple LANDING parameters are included in your request the first parameter encountered will be placed here.
short_code	String	Now deprecated, use landing_pages instead. Contains the generated shortened code used by the short_url if the request contained a landing page. If multiple LANDING parameters are included in your request the first parameter encountered will be placed here.
landing_pages	Map < String, LANDING_PAGES >	A map of all detected shortening request parameters and their respective shortened URLs. Please note that for IM with failover SMS, landing parameters referenced only in the SMS content will NOT be included in the response.

JSON Response: LANDING_PAGES

Key	Type	Description
short_url	String	The shortened version of the URL
short_code	String	The generated short code used by the short_url

RESULT_INFO

Key	Type	Description
status_code	String	A status code for the given request that follows the http standards ( 200 if OK, 403 if parameters are wrong, 401 if authentication error).
description	String	A human friendly message that describes the status code.

IM Reply Callback

Reply Callback

{
    "channel": "VIBER",
    "reply": {
        "reply_message_id": "d5a53b51-dc57-4c2c-b880-36f788c4d4d4",
        "from": "306999999999",
        "to": "306988888888",
        "timestamp": 1481126247,
        "price": 0.05,
        "message": {
            "text": "This is my reply.",
            "mediaUrl": "https:\/\/dl-media.viber.com\/5\/media\/2\/short\/any\/def\/file\/0x0\/80ca\/54e9d89d8650631b425aa062db8055baa78d54aca4b0a0e0e4eb7c1ab5f380ca?Expires=1627579550\u0026Signature=lVIGJr8tqR~CXM7gKQhAmb0yssk0~WM~bz44oWZKUlhOzWB9JF42kIgsHwSAUit4Wrq7Mot5uqWBkvImw~ySZEteeufXtUlL1Umh28oAzl-bsXF4t1ZvcpjSH0eLL3vhIDW5cblqxQDs4v5IDuULABGKkyjtCYDJsDNn0vKx6zYGeIfhWV~uvGHbR2cfN9HyOPv3C~hbnJ5SLfovL0KBL3mdA2nVHD0i7uEy95JL7UV0Jt1tbKDEJiTQMf6KRELBP5ysGG5KvtodUwOvtRcPugwubBZacKG6-EamuZ6IQGTXGwIADifui2GxvIvJs3vxCbu4KXSgRpxBNzb20v5whw__\u0026Key-Pair-Id=APKAJ62UNSBCMEIPV4HA",
            "mediaFileName": "dummy.pdf"
        }
    },
    "original_im": {
        "message_id": "6f3f5441-391f-473d-b822-cfb129f21238",
        "request_id": "ccb9111f-9ea0-4e01-882f-f72ee502e779",
        "reference_id": "My Reference",
        "custom_id": "312312412"
    }
}

HTTP Method: POST

Content-Type: application/json; charset=utf-8

When a subscriber responds on a 2-way message, a callback is generated and signaled back to the client using an HTTP callback. The URL invoked is obtained from the “reply_url” field in the original message request. The request generated to this URL is described here. The endpoint on the client side must fully support this kind of request and respond accordingly. In case of delivery failure, the callback will be resent three more times with a two minute gap.

Notes:

The media included can be files (document, pdf or spreadsheet), images or videos. The list of supported image and video formats can be found bellow.
Replies from users cannot include both text and media. Separate messages are required for each type.

Key	Type	Description
channel	String	The channel the subscriber used to create the reply.
reply	Reply	A summary of the reply message.
original_im	Original IM	A summary of the original message.

Reply

Key	Type	Description
reply_message_id	String	A generated id for the new reply message.
from	String	Subscriber's mobile number.
to	String	The sender id of the original message request.
timestamp	int	The timestamp the reply message arrived.
price	double	The cost of the reply message.
message	Message	A summary of the message content.

Message

Key	Type	Description
text	String	Contains the body of the subscriber's response. will be null if response is a media message.
media_url	String	The URL for any file, image or video the subscriber might have included in his response. Each file sent from the user to you will be stored on Viber’s server for up to 7 days, after which it will no longer be available to download. If not file is included it will be null. Will be null if response is a text message.
media_filename	String	The name of the file accessed by the above URL. If not file is included it will be null. Will be null if response is a text message.

Original IM

Key	Type	Description
message_id	String	The generated id for the given request.
request_id	String	The generated id for the given message.
reference_id	String	The reference id for the given request.
custom_id	String	The custom id for the given subscriber.

Reply Media Filetypes

The media file formats allowed attached to replies by the user:

Media Type	Media Formats
Photos	.jpg, .jpeg, .png, .bmp, .gif, .svg, .webp
Videos	.avi, .wmv, .mov, .mp4, .m4v, .3gpp, .3gpp2, .asf, .mkv, .mp2ts, .webm

Delete Scheduled IM

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/im/remove

Request body

{
 "id": "adbfbe48-82e7-49d5-af1a-e5b284cf5bf3",
 "field": "REQUEST_ID"
}

Response body

Code Example

"String body" = "{\n" +
            " \"id\": \"adbfbe48-82e7-49d5-af1a-e5b284cf5bf3\",\n" +
            " \"field\": \"REQUEST_ID\"\n" +
            "}";

The deletion service can be used to remove scheduled IMs.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/im

HTTP Path: /remove

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: imGateway

Request

The request object consists of two keys, the field and the id, as explained in the following table.

Key	Type	Description
field	String	We can delete messages based on their request id and their reference id. So if you want to delete using the request id then the field must be equal to “REQUEST_ID”, otherwise the field must be equal to “REFERENCE_ID”.
id	String	The value of the field.

Response

The response is an integer that shows the number of the deleted messages.

OTP Gateway REST API

The OTP REST API provides an interface for sending OTP messages around the world. The service supports IM, SMS or a combination of those methods.

To get started, you need to login to our members section to create an authentication OTP token API key, and use that token key within the HTTP headers for every request.

The OTP REST web service expects a JSON request that defines the message you wish to send. The service replies with a JSON response that acknowledges your request including an identifier for your reference. A callback service is also available that informs you of the delivery status of a message once it has been processed.

OTP Request

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Complete Request body

{
    "reference_id": "OTP-944706",
    "subscriber": "306999999999",
    "code_length": 6,
    "code_type": "numeric",
    "callback_url": "",
    "expire": 300,
    "message": {
        "text": "Hello There! Here is your OTP: {apifon_otp}",
        "dc": 0,
        "sender_id": "Apifon"
    },
    "im_channels" : [{
        "sender_id" : "Apifon",
        "text" : "Hello There! Here is your OTP: {apifon_otp}",
        "ttl" : 150
    }]
}

Simple Request body (SMS)

{
    "reference_id": "OTP-337",
    "subscriber": "306999999999"
}

Simple Request body (IM)

{
    "reference_id": "OTP-337",
    "subscriber": "306999999999",
    "im_channels" : [{
        "sender_id" : "Apifon",
        "text" : "Hello There! Here is your OTP: {apifon_otp}"
    }]
}

Simple Request body (IM with failover SMS on expiration/delivery failure)

{
    "reference_id": "OTP-337",
    "subscriber": "306999999999",
    "message": {
        "text": "Hello There! Here is your OTP: {apifon_otp}",
        "dc": 0,
        "sender_id": "Apifon"
    },
    "im_channels" : [{
        "sender_id" : "Apifon",
        "text" : "Hello There! Here is your OTP: {apifon_otp}"
    }]
}

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/otp

HTTP Path: /create

Content-Type: application/json; charset=utf-8

HTTP Method: POST

OAuth2 Scopes Required: otpGateway

Sending an OTP Request will generate an one time password for the specific subscriber. This one time password will be sent to the subscriber via the requested channel. In case of failover the same OTP code will be dispatched for the SMS. The API distinguishes what channel to use when dispatching the OTP to the subscriber according to the following table.

Request	Description
message is missing im_channels is missing	The OTP will be dispatched using SMS channel
message is missing im_channels is present	The OTP will be dispatched using IM channel
message is present im_channels is missing	The OTP will be dispatched using SMS channel
message is present im_channels is present	The OTP will be dispatched using IM channel. Potential failover to SMS may occur in case of delivery failure.

The reference_id that you are including to the request is interconnected with the generated OTP.

The request is encoded in JSON, and is split in several levels. Each table below will represent a level, starting with the outermost one.

Request Body: Outer Level

Key	Type	Description
reference_id	String	Include a reference string that will be interconnected with the generated OTP.
subscriber	String	Mobile number (MSISDN) to deliver the message to. Number is in international format and is only digits between 7-15 digits long. First digit cannot be a 0.
code_length (*optional)	int	Defines the length of the generated OTP. If not set, by default the OTP length is 6 characters. The minimum value is 5 while the maximum value is 20.
code_type (*optional)	CodeType	Defines the type of the generated OTP. ["numeric"]: The OTP will contain only numeric characters. ["alpha"]: The OTP will contain only alphabetical characters. ["alphanumeric"]: The OTP will contain only alphanumeric characters. By default it's value is "numeric".
callback_url (*optional)	String	If set, the callback (delivery / status report) will be delivered to this URL, otherwise no callback will take place. Must be a valid URL starting with https://. For example https://yourserver/callback. A valid signed certificate must be used.
expire (*optional)	int	Defines the expiration time of the OTP. If not set, by default it will be 300 (in seconds).
message (*optional)	MESSAGE*	Defines the SMS content of your message. If not set, by default it will send an SMS containing only the generated OTP.
im_channels (*optional)	Array[IM_CHANNELS*]	Defines the IM content of your message. If not set the OTP request will be directed as an SMS request.

Request Body: MESSAGE*

Key	Type	Description
text	String	Contains the body of the SMS message to be delivered to the destination device. One can optionally specify {apifon_otp} within the message body that will be replaced later with the generated One Time Password. In the event your text is longer than 160 characters in 7bit, 140 in 8bit or 70 in 16bit, Apifon will split the message into parts. In that case, the response will tell you how many parts the message has been sent in.
dc	Data coding	Contains the information on how the text is encoded. Defaults to ‘0’. It can only be a number in the rand [0-2].The maximum number of characters you can fit into a single message depends on the encoding you are using: [0]: GSM7 bit Default Alphabet (160). Basic Latin subset of ASCII, as well as some characters of the ISO Latin 1 – 160 [1]: GSM 8-bit data encoding (140). 8-bit data encoding mode treats the information as raw data. According to the standard, the alphabet for this encoding is user-specific. [2]: UCS-2 (UTF-16 [16 bit]) Encoding (70). This encoding allows use of a greater range of characters and languages. UCS-2 can represent the most commonly used Latin and eastern characters at the cost of a greater space expense.
sender_id	String	The sender ID (a.k.a. from) for the SMS delivery. The sender ID can contain numbers or/and Latin characters. If numeric, minimum length is 1, maximum length is 16 digits. If alphanumeric, minimum length is 1, maximum length is 11 characters.

Request Body: IM_CHANNELS*

Key	Type	Description
text	String	Contains the body of the IM message to dispatch to the subscriber. The parameter {apifon_otp} MUST be explicitly defined in the text content and will be replaced by the generated OTP on the result text of the IM.
sender_id	String	The sender ID of the IM message to use when dispatching the OTP.
ttl	Integer (*optional)	The maximum time-to-live of the IM message in seconds. Values lower than 30 seconds will be rejected as invalid and any values greater than the overall expiration of the OTP (denoted by the field expire in the request) will result in your message discarding any potential failover. If ommited, defaults to either a) Maximum expiration of the OTP (in case of IM only OTP) or b) half of the overall expiration time of OTP (in case of IM with SMS failover).
device_target (*optional)	Enum	This field can be used in order to target a specific device when sending an IM OTP in case a user has multiple devices. Available Options: SMARTPHONE_ONLY/SMARTPHONE_AND_OTHER_DEVICES. Default: "SMARTPHONE_AND_OTHER_DEVICES".

OTP Response

Response body

{
    "request_id": "fc4a9c38-faed-42c3-affb-93571e9a8e36",
    "reference_id": "OTP-944706",
    "result": [{
            "message_id": "1c4ecbb0-f6db-44a3-95e9-8a581f1b48cd",
            "custom_id": null,
            "length": 37,
            "short_code": null,
            "short_url": null
        }
    ],
    "result_info": {
        "status_code": 200,
        "description": "OK"
    }
}

JSON Response

Key	Type	Description
request_id	String	A generated id for the given request.
reference_id	String	Whatever the user passed into reference_id. You will need this later on in order to validate the generated OTP.
result	List< RESULT_DETAILS >	A list with the results of the subscriber. This list will contain more than one RESULT_DETAILS in case the text was too long and had to be split into more than one SMS.
result_info	RESULT_INFO	A summary of the status of the request.

JSON Response: RESULT_DETAILS

Key	Type	Description
message_id	String	A generated id for the new message.
length	Int	The number of characters that the message contains.

JSON Response: RESULT_INFO

Key	Type	Description
status_code	String	A status code for the given request that follows the http standards ( 200 if OK, 403 if parameters are wrong, 401 if authentication error).
description	String	A human friendly message that describes the status code.

OTP Verification

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/otp/verify/OTP-944706/862994

Request body

Request body for the OTP verification service is an empty string.

The verification service can be used to make sure than the OTP submitted by the user is correct and has not expired. You need to provide the OTP submitted by the user to your system and the reference_id that was used to generate the OTP.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/otp

HTTP Path: /verify/{reference_id}/{apifon_otp}

HTTP Method: POST

Content-Type: application/json; charset=utf-8

OAuth2 Scopes Required: otpGateway

OTP Verification Response

Response body

{
    "request_id": "fc4a9c38-faed-42c3-affb-93571e9a8e36",
    "result_info": {
        "status_code": 0,
        "description": "Valid"
    }
}

After submitting a request using Apifon API, you will receive an HTTP response. The HTTP response will contain a JSON object.

Key	Type	Description
request_id	String	The generated id for the given request.
result_info	RESULT_INFO	A summary of the status of the request.

JSON Response: RESULT_INFO

Key	Type	Description
status_code	String	A status code for the given request that follows the http standards ( 200 if OK, 403 if parameters are wrong, 401 if authentication error).
description	String	A human friendly message that describes the status code.

Here is a list of all the responses you can get as a response to your verification request.

Status Code	HTTP Code	Description	Meaning
0	200	Valid	The OTP provided is valid.
1	200	Invalid	The OTP provided has already been validated.
2	403	Declined	The request was declined.
3	403	The request code was not found	Either your Reference ID or the OTP code is incorrect.
4	403	No code was provided	OTP Code was not provided.
5	403	No reference_id provided in request	Reference ID was not provided.
6	403	Expired	The expiration time of the OTP has passed.
7	403	The request code is invalid.	OTP is invalid.

Callback Responses

Callback

SMS: POST -YourCallbackUrl- HTTP/1.1

{
  "url": "https://yourserver/callback",
  "request_id": "eff655d8-0cb6-47b3-8828-96e1b80b55af",
  "reference_id": "Campaign #215",
  "data": [{
      "from": "Apifon",
      "to": "306999999999",
      "message_id": "e2d4424d-7d6a-49c2-b564-99b2b68c74cb",
      "custom_id": "312312412",
      "status": {
        "code": 7,
        "text": "delivered"
      },
      "error_code": "000",
      "timestamp": 1517922078,
      "price": "0.002",
      "vat": "0.00048",
      "mccmnc": "20210"
    }
  ],
  "account_id": 5411,
  "type": "SMS"
}

Viber: POST -YourCallbackUrl- HTTP/1.1

{
  "url": "https://yourserver/callback",
  "request_id": "ccb9111f-9ea0-4e01-882f-f72ee502e779",
  "reference_id": "Campaign #216",
  "data": [{
      "from": "Mookee",
      "to": "306999999999",
      "message_id": "6f3f5441-391f-473d-b822-cfb129f21238",,
      "custom_id": "312312412",
      "status": {
        "code": 7,
        "text": "delivered"
      },
      "timestamp": 1517926706,
      "price": "0.002",
      "vat": "0.00048",
    }
  ],
  "account_id": 5411,
  "type": "VIBER"
}

OTP: POST -YourCallbackUrl- HTTP/1.1

{
    "url": "https://yourserver/callback",
    "request_id": "fc4a9c38-faed-42c3-affb-93571e9a8e36",
    "reference_id": "OTP-944706",
    "data": [{
            "from": "Apifon",
            "to": "306999999999",
            "message_id": "1c4ecbb0-f6db-44a3-95e9-8a581f1b48cd",
            "status": {
                "code": 7,
                "text": "delivered"
            },
            "error_code": "000",
            "timestamp": 1518536806,
            "price": "0.002",
            "vat": "0.00048",
            "mccmnc": "20210"
        }
    ],
    "account_id": 5195,
    "type": "SMS"
}

Metadata example

{
  "url": "https://yourserver/callback",
  "request_id": "ecbd87a2-83f8-4d70-988d-2fd1bb092318",
  "reference_id": "SMS",
  "data": [{
      "from": "Apifon",
      "to": "306999999999",
      "message_id": "223ae0d2-8af6-4081-9f6d-7cb3f7a5720c",
      "status": {
        "code": 11,
        "text": "open"
      },
      "timestamp": 1583835537,
      "price": "0.002",
      "vat": "0.00048",
      "metadata" : {
          "url": "https://www.example.com",
          "short_code": "10oalo",
          "browser": "Chrome_80_0",
          "ip": "211.62.126.21",
          "micro_timestamp" : 1583835537251
      }
    }
  ],
  "account_id": 5195,
  "type": "SMS"
}

Delivery reports and any other relevant intermediary status are signaled back to the client using an HTTP callback. The URL invoked is obtained from the “callback_url” field in the original message request. The request generated to this URL is described here. The endpoint on the client side, must fully support this kind of request and respond accordingly.

If a callback_url was not specified in the request, a callback is not generated. In case of a batch request (a request that contains more than one subscribers) you should expect more than one callback responses, since more than one delivery report is obtained from the destination network in a very short time frame. The CallbackInfo JSON object is explained below.

HTTP_HEADER

Key	Value
content-type	Application/Json

CALLBACK_RESPONSE

Key	Type	Description
url	String	The client’s url.
request_id	String	The request id that is generated during the request.
reference_id	String	The reference id that was given during the request.
data	CALLBACK_INFO*	Contains all callback information. See table below.
account_id	Integer	The client’s account id.
type	String	SMS, VIBER, MAIL.

CALLBACK_INFO

Key	Type	Description
from	String	The sender id.
to	String	The number of the subscriber.
message_id	String	The generated id of the message.
custom_id	String	The custom id of the subscriber.
status**	MESSAGE_STATUS*	An embedded object for status.
error_code	String	The dlr error code.
timestamp	Long	The dlr timestamp (seconds since Epoch time).
price	String	The price of the message.
vat	String	The value-added tax of the message.
mccmnc	String	The mobile country code (MCC) and mobile network code (MNC) if applicable. (ex. “20201”).
metadata	Key-Value	Metadata related to the data of the callback.

MESSAGE_STATUS

Key	Type	Description
code	Integer	An integer that represents the given status.
text	String	Description of message status.

To view a list of all callback status codes click SMS Callback Statuses or IM Callback Statuses.

metadata Property

Some callbacks may contain a metadata object.

The metadata object in the callback request provides additional information like click events (on Viber buttons or shortened URLs) or error/status information.

1. Click Event Information

When the metadata object pertains to user interactions, it includes information about clicks on buttons in Viber messages or on shortened URLs. These fields capture details about the user’s environment when they interact with these elements.

Click Event Information Example

"metadata": { "url": "https://www.example.com", "short_code": "10oalo", "browser": "Chrome_80_0", "ip": "127.0.0.1", "micro_timestamp": 1583835537251 }

url (string): The URL clicked by the user, typically a tracking link or the destination URL.
short_code (string): A unique code used for tracking or identifying the shortened URL.
browser (string): The browser and version used by the user when they clicked the link, formatted as Browser_Version.
ip (string): The IP address associated with the click event, often for tracking or location purposes.
micro_timestamp (integer): The timestamp in microseconds at the moment of the click event.

2. Error/Status Information

Alternatively, the metadata object may include error or status codes to indicate specific issues encountered during message delivery.

Error/Status Information Example

"metadata": { "error_description": "value" }

error_description (string): A description of any error encountered during the message delivery process.

"user_blocked": "The ID was blocked by the user/The user blocked business messages completely on their device"
"no_viber_user": "The destination number is not registered as a Viber user"
"no_suitable_device": "Not an Android or iOS device with a Viber version that supports Business Messages"

SMS Callback Statuses

Key	Type	Description
Code	Text	Description
1	absent	No paging response from the Message Service.
3	accepted	Message accepted for delivery. This status is also returned by the SMS Failover.
4	accepted_smsc	Messaged delivered to the Mobile Network Operator and should be delivered soon.
5	call_barred	Subscriber enabled call barring.
7	delivered	Message delivered to destination successfully.
8	expired	The validity period of the message has expired.
11	open	The shortened URL embedded in the message was opened by the recipient.
18	rejected_smsc	Message rejected by SMSC Provider.
19	teleservice_not_provisioned	Destination has no SMS subscription.
21	unexpected_value	Messaged delivered to SMSC and an error occurred there.
22	unknown_sub	Number does not match to an MSISDN.
23	smpp_refused	Message refused by SMPP Provider.
24	smsc_refused	Message refused by SMSC Provider.
101	no_sender	Sender Id is not set.
103	invalid_sender	Sender Id is not valid.
105	lookup_invalid_msisdn	The destination number to send to is invalid.
106	unknown_sender_type	Does not recognize Sender Id Type.
107	account_not_allowed	The account has not been accepted.
109	no_coverage	Contact account manager.
110	no_price	Contact account manager for price.
111	spam_control	An identical message was already dispatched to the destination in a short timeframe.
112	no_route_plan	There is no rooting for the network you want to send.
113	invalid_account	The account has been suspended.
115	account_insufficient_credits	The message can't be sent due to low balance.

IM Callback Statuses

Key	Type	Description
Code	Text	Description
3	sent	The message was successfully delivered to the provider. The message is in a pending state until delivered or expired.
7	delivered	Message delivered to the destination successfully.
8	expired	The validity period of the message has expired.
10	seen	The user opened the Viber client and entered the conversation with the specific message. This event must be always preceded by a delivered event. The message is in a final state as delivered. This status is only dispatched when the user has enabled 'Seen' notifications on his IM application.
11	open	The shortened URL embedded in the message was opened by the recipient.
22	unknown_user	The message was successfully delivered to the provider but failed to deliver to the recipient. Usually this is caused when the destination is not a user of the IM application, has an older version installed or has disabled business messaging/blocked the Sender ID.
101	no_sender	Sender ID is not set or is invalid.
105	invalid_msisdn	The destination number to send to is invalid.
109	no_coverage	Contact account manager.
110	no_product	Contact account manager for price.
111	spam_control	An identical message was already dispatched to the destination in a short timeframe.
115	account_insufficient_credits	The message can't be sent due to low balance.
119	sender_id_disabled	The sender ID is disabled. Contact account manager.
120	no_active_subscription	There is no active subscription for the Sender ID in this timeframe. Contact account manager.
121	invalid_url	Message contains an invalid URL as the action link or the shorten link.
130	shared_sender_cap	Your shared Sender ID reached the maximum amount of messages it can be used for.

Balance

This service provides information about the account’s balance.

Balance Request

HMAC Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: ApifonWS 5b5a6ca0deb4bdba5bab:PSd5H7MDLQR3fehj+UYhEXndk0fuS+yPshFHQd6scbY=

OAuth2 Request headers

Content-Type: application/json
X-ApifonWS-Date: Thu, 29 Sep 2016 12:18:56 GMT
Authorization: Bearer 9c529aed-7d0e-3985-a20f-cd6d454268f8

Request URL

https://ars.apifon.com/services/api/v1/balance

Request body

No request body is supplied for the balance service.

Host URL: https://ars.apifon.com

Service Endpoint: /services/api/v1/balance

Content-Type: application/json; charset=utf-8

HTTP Method: POST

OAuth2 Scopes required: accountInfo

Balance Response

Response body

{
    "balance": "9864.0",
    "reserved": "0.0",
    "plafon": "0.0",
    "subscriptions": [{
            "senderId": "Apifon",
            "available": "300.0",
            "total": "300.0",
            "endDate": "Jun 30, 2018 11:59:59 PM"
        }
    ]
}

The details of the response can be found in the table below.

Key	Type	Description
balance	String	The total amount in your account.
reserved	String	The reserved amount in your account.
plafon	String	The amount to be credited.
subscriptions	Subscriptions	An array of subscription objects (more info below). [SUBSCRIPTION_1, SUBSCRIPTION_2, …]. Subscriptions will be an empty array if no subscription is currently active.

Subscriptions

Key	Type	Description
senderId	String	The sender ID of your subscription.
available	String	The available amount of your subscription.
total	String	The total amount of your subscription.
endDate	String	The expiration date of your subscription.

Status Codes

The response codes are mapped as follows:

Status Code	Meaning
200	Request completed successfully.
201	Request completed successfully and the resource has been created.
204	Request completed successfully, no content to return.
304	Not modified - The request was completed but the resource was not modified.
400	Bad Request - The request is invalid and was not understood by the API. Refer to the API reference of the specific endpoint you are trying to access.
401	Unauthorized – Header “Authorization” missing, invalid, or revoked; and / or, your host IP is not in the authorized IPs list.
403	The request contains invalid or illegal values.
404	Not Found - The endpoint on which the request was sent to, does not exist or the resource does not exist. Review the URL and the arguments of the request.
405	Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint.
408	Request timed out. Server failed to deliver a response in time.
409	Conflict. Please refer to the API reference of the specific endpoint you are trying to access.
415	Unsupported Media Type – If the request was in a content-type not supported by the endpoint (ex. text/plain instead of application/json).
429	Too many requests (Throttling).
500	Internal Server Error.

Error Responses

Request unauthorized (Invalid/Missing credentials)

{
  "status": "401",
  "title": "Unauthorized",
      "error_details": {
      },
      "error_report_code": 31b405aa-c843-562a-b5ca-96e1d4bb81ac
    }

Missing/Invalid parameters

{
  "status": "400",
  "title": "Request validation Error(s)",
      "error_details": {
        "campaign_defaults.from": Not a valid email address,
      },
      "error_report_code": 280ac334-c207-4196-972f-3bfd1083dd9d
    }

In case of an exception the API returns an error response that can be used to troubleshoot the error. In case of an error response we recommend reviewing the errors section in this guide and endpoint-specific errors for the endpoint you are trying to access. Generally a response with 4xx status code indicates a problem with the request. If you are seeing a response with 5xx status code that likely means there is an error on Apifon's side. You can contact our support team at support@apifon.com.

Key	Type	Description
status	String	Contains the status code of the request
title	String	A human readable String that contains generic information about the error.
error_details	Key-Value	A map containing information about the specific causes of the error.
error_report_code	String	A unique identifier assigned to your request. Please provide this ID when contacting support.

API Reference

Bounce List REST API

Add

Request Body: Outer Level

JSON Response

Get Block Subscribers

Query Parameters

JSON Response

JSON Response:META_DETAILS

JSON Response:LINKS_DETAILS

JSON Response:BLOCK_SUBSCRIBERS

JSON Response:BLOCK_SUBSCRIBERS_META

Possible Response statuses

Get Block Subscriber by destination

Query Parameters

Path Parameters

JSON Response

Possible Response statuses

Query Block Subscribers

Request Body

CONDITIONS

CONDITION_OPERATORS

Sort

JSON Response

Json Response: META_DETAILS

SUBSCRIBERS_DETAILS

Possible Response statuses

Remove Blocked Subscriber

Path Parameters

JSON Response

BLOCK_REASONS

List REST API

Double OPT-in

Add List

Request Body

CAMPAIGN_DEFAULTS*

GDPR_PROPERTIES**

DOUBLE_OPTIN***

JSON Response

Get Lists

Query Parameters:

JSON Response

JSON Response:META_DETAILS

JSON Response:LINKS_DETAILS

JSON Response:LIST_DETAILS

Possible Response statuses

Get List

Query Parameters

Path Parameters

JSON Response

Json Response: META_DETAILS

Json Response: CAMPAIGN_DEFAULTS

Json Response: DOUBLE_OPTIN

Json Response: GROUPS

JSON Response: SUBGROUP

Json Response: SUBSCRIBER_FIELDS

Json Response: GDPR_FIELDS

Json Response: GDPR_PROPERTIES

Json Response: FORM_URLS

Possible Response statuses

Update List

Path Parameters

Request Body

JSON Response

Remove List

Path Parameters

JSON Response

Add Subscriber field

Path Parameters

Request body

JSON Response

Update Subscriber field

Path Parameters

Request body

JSON Response

Remove Subscriber field

Path Parameters

JSON Response

Add GDPR field

Path Parameters