Navbar
Example
  • API Reference
  • API Reference

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

    The API reference also includes resources related to:

    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.

    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.

    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.

    Add GDPR 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/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.

    Update GDPR 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/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

    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.

    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.

    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)

    Subscribe 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/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

    4
    

    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:

    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.

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

    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:

    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

    4
    

    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"
        }
    }
    

    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_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

    Some callbacks may contain a metadata object.

    The metadata object may contain additional properties for the callback you received.

    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.