Subscription

Subscriptions provide a way for application developers to receive notifications from CallFire once a monitored event is occurred. The mechanism of callbacks in CallFire API v1.1 called subscriptions.

If you are using CallFire API v2 take a look at Webhooks API which replaced Subscriptions API. You can find an information about their differences and recommendations to use at CallFire Webhooks page.

Subscriptions endpoint

API path: https://www.callfire.com/api/1.1/rest/subscription

All api endpoints return response in XML format by default, to get response in JSON put .json at the end of API path.

Create subscription

This operation registers a URI endpoint to start receiving CallFire notification events on. Returned is the id that can be used later to query, update, or delete the subscription. The id is also returned as part of all notification events as 'subscriptionId'. A URI endpoint will need to be provided that can handle the HTTP notification events coming from CallFire.com

You can find samples of notification payload for different events on Notification samples page.

Limitation: max number of subscriptions - 10.000 per account.

Operation parameters

Example request

$ curl https://www.callfire.com/api/1.1/rest/subscription.json \
    -X POST \
    -u login:password \
    -d Enabled=true \
    -d Endpoint=http://customer-service.com/callback \
    -d NotificationFormat=JSON \
    -d TriggerEvent=OUTBOUND_TEXT_FINISHED \
    -d BroadcastId=12345 \
    -d ToNumber=67076:KEYWORD

Example response

response code - 201 Created

{
    "ResourceReference": {
        "Id":609951003,
        "Location":"https://www.callfire.com/api/1.1/rest/subscription/609951003"
    }
}

Get all account's subscriptions

Return a list of all subscriptions registered to an account.

Operation parameters

Example request

$ curl https://www.callfire.com/api/1.1/rest/subscription.json?MaxResults=2 \
    -u login:password

Example response

response code - 200 OK

{
  "ResourceList":{
    "@totalResults":2,
    "Subscription":[
      {
        "@id":567040003,
        "Enabled":false,
        "NonStrictSsl":false,
        "NotificationFormat":"EMAIL",
        "TriggerEvent":"INBOUND_TEXT_FINISHED",
        "SubscriptionFilter":{
          "ToNumber":"67076:ANTLR"
        }
      },
      {
        "@id":609076003,
        "Enabled":true,
        "NonStrictSsl":false,
        "Endpoint":"http://79b55ae6.ngrok.io",
        "NotificationFormat":"JSON",
        "TriggerEvent":"OUTBOUND_TEXT_FINISHED",
        "SubscriptionFilter":{
        }
      }
    ]
  }
}

Get single subscription

Return a subscription registered to an account using id returned from CreateSubscription request

Operation parameters

Example request

$ curl https://www.callfire.com/api/1.1/rest/subscription/6090706003.json \
    -u login:password

Example response

response code - 200 OK

{
  "Resource":{
    "Subscription":{
      "@id":609076003,
      "Enabled":true,
      "NonStrictSsl":false,
      "Endpoint":"http://79b44ae6.ngrok.io",
      "NotificationFormat":"JSON",
      "TriggerEvent":"OUTBOUND_TEXT_FINISHED",
      "SubscriptionFilter":{
      }
    }
  }
}

Update subscription

Update existing subscription by ID. Use this to enable or disable notification events, change the notification endpoint URI, or change the filtering so only receive notification for a subset of events.

Operation parameters

Example request

$ curl https://www.callfire.com/api/1.1/rest/subscription/609951003.json \
    -X PUT \
    -u login:password \
    -d Enabled=false \
    -d Endpoint=http://new-service.com/callback \
    -d NotificationFormat=XML

Example response

response code - 204 No content

Delete subscription

Delete subscription to stop receiving CallFire notification events at the registered URI postback endpoint.

Operation parameters

Example request

$ curl https://www.callfire.com/api/1.1/rest/subscription/6090706003.json \
    -X DELETE \
    -u login:password

Example response

response code - 204 No content