Before you start a Call Campaign, set a clear objective. We have some use cases here and guidelines here. Based on the business objective, configure a call flow. Campaigns API attempts to make calls to comma seperated ‘From’ numbers specified in the request. When a call is picked up, the flow is executed and status reported. A Campaign schedule determines when to start and end the campaign.  Retry logic determines how and when to attempt to call a phone number again in case of failures. 


To use Campaigns API, including sample code, please refer our developer portal


Below are some important considerations to keep in mind while using the API.


  • When a request has an invalid number, then the entire request is failed with the number available in the failure message

  • The request will fail on the first invalid number found, the rest of the data is not processed. The developer is encouraged to use the phone number lib to validate his data before sending. 

  • Terminal states of a campaign are ‘completed’, ‘failed’,’deleted’,canceled. Intermediate states are created, in-progress and ,paused.

    • Campaign States (intermediate)

      • created - A campaign API request that was successfully accepted by the system

      • in-progress - A campaign that has started

      • paused - A campaign, that was scheduled was requested to be paused explicitly

    • Campaign States (Terminal):

      • failed - None of the calls were made (5xx /4xx / invalid numbers) for all of the phone numbers for the campaign. Immediate failures are marked as failed as well with HTTP status code reflecting the reason for failure

      • completed - all / partial calls (where the end time was reached) were made successfully.

      • canceled - A campaign was ‘paused’ but was not resumed ever and end_at was reached is marked as canceled. All the remaining calls for the campaign are marked as failed.

      • deleted - Campaign can be marked deleted only if it has not started.

  • Call status

    • in-progress - When the call is triggered

    • failed - no retry was allowed and the status was ‘no-answer’, ‘busy’ or ‘failed’ state

    • completed - When this call was ‘completed’ by Exotel

  • CustomFields are part of the report. CustomFields value is applicable to all numbers uniformly. 

  • Campaigns are marked as ‘failed’ if all calls were not attempted. If all calls were attempted, then that call campaign is successful, however status of individual calls will be determine success/failure of each call.

  • Call to a number that failed (including retries) is marked as “failed” 

  • DELETE is possible only on campaigns that have not yet started.

  • A campaign that is in progress, the below fields can be updated

    • Callbacks 

    • Action

  • When end_at is specified, Exotel makes best effort to ensure that calls are completed within that period but is not guaranteed. POST request with end_at will return 200 OK irrespective of whether all calls can be made or not. All numbers that were not called because of timer expiry will be marked as ‘canceled’

  • Report captures numbers that were not dialed for a failed campaign as well

  • Long Running Campaigns: 

    • A cut-off time, 10.30am - 9 pm is provisioned, which will imply that no call is made beyond the cut off time. 

  • Paused campaigns without end time specified will expire after 30 days from the start_at time.

  • Throttle limits - 200 API requests per min with 60 concurrent channels


Video explaining the feature:






Availability - Beta


As we continue to build new products and features in order to serve our customers better, we release new products in beta and it’s a great way for you to integrate this solution to take early advantage and improve capabilities of your system.


What is beta?


Products which are released under beta are new solutions/features that we  continue to build/tweak based on feedback from customers and closely monitor for issues. This is to ensure that such newly launched products meet the high quality standard of Exotel general availability guidelines.

There might be modifications during the beta phase, and the final version of the release can vary from beta. However, any non-compatible change or major modifications which can impact the users, shall be communicated to the customers.



Support for beta release
During the beta phase, customers can provide feedback or raise issues via our Customer Happiness team - hello@exotel.com


However, since these products are in beta, the time taken to respond to some of the queries or issues may be longer as it will be directly handled by our product and engineering teams and not covered by our standard support SLAs.