Access token

Zoho Campaigns is introducing a new version of our APIs: version 1.1. This version uses Oauth 2.0 protocol to provide authentication through access and refresh tokens. This document will explain how version 1.1. works in detail.

How is version 1.1 better?

There are two major advantages of using version 1.1 over version 1:

  • The access token has a limited lifetime. Only a developer who has completed the authentication process and has a refresh token will be able to generate a new access token. This way, we can be sure that the access token cannot be misused.
  • The access token is obtained by specifying the scope required for a particular action. This restricts access to only what is actually required and prevents any additional actions being performed.
  • All JSON parameters in the request should be encoded for enhanced security.

Prerequisites

There are some basic requirements to meet to access API version 1.1:

  • A client registered in Zoho Accounts. Click here to learn how to register a client.
  • A general idea about scopes available in Zoho Campaigns.

Generation of access and refresh tokens

This is the most important step in using version 1.1. You must generate access and refresh tokens before you can start using this version of API.

  1. Using your registered client, send an authorization request to Zoho Accounts. You have to include the necessary scopes for which you require access in this request.
  2. Zoho Accounts will forward this request to the corresponding Zoho Campaigns account owner. 
  3. The Zoho Campaigns owner will verify this request and grants permission/access to the requested scopes.
  4. As an acknowlegement to the granted request, Zoho Accounts will send a grant code to you.
  5. Using this grant code, you can request for access token from Zoho Accounts.
  6. Access and refresh tokens will be generated and sent to the you. With the help of access token, you can now use version 1.1 APIs.
Note :
  • You need to follow this cycle every time you need access and refresh token.
  • Access tokens expire after one hour. If an access token expires, developers can use the refresh token to generate a new access token.

How do I encode my parameters?

Given below is the encoding procedure for different languages to encode data,

  • JAVA - URLEncoder.encode("{Contact Email:patricia@zylker.com}", "UTF-8")
  • Ruby - URI::encode("{Contact Email:patricia@zylker.com}")
  • PHP- urlencode("{Contact Email:patricia@zylker.com}")

Scope

Campaigns give resource access based on the scope of the task at hand. We have module-specific scopes, under which the user can only access resources under authorized scopes If you need to access a resource under an unauthorized scope you will need authorization from the account owner.

ModuleScope NameDescription
CampaignsZohoCampaigns.campaign.CREATETo create campaigns and merge tags
ZohoCampaigns.campaign.READTo view a report or the details of a campaign
ZohoCampaigns.campaign.UPDATETo update campaigns and coupons
ZohoCampaigns.campaign.DELETETo delete a campaign
ContactsZohoCampaigns.contact.CREATETo create contacts or mailing lists
ZohoCampaigns.contact.READTo view details or a report of contacts or mailing lists.
ZohoCampaigns.contact.UPDATETo update contacts or mailing lists.
ZohoCampaigns.contact.DELETETo delete mailing lists

Other additional scopes

  • ZohoCampaigns.campaign.CREATE-UPDATE - To create, clone, and edit a campaign. (CREATE,UPDATE)
  • ZohoCampaigns.campaign.WRITE - To create, modify, and delete campaigns. (CREATE,UPDATE, DELETE)
  • ZohoCampaigns.campaign.ALL - To view, create, modify, and delete campaigns. (READ, CREATE, UPDATE, DELETE)
  • ZohoCampaigns.contact.CREATE-UPDATE - To create and edit contacts or mailing lists.(CREATE,UPDATE)
  • ZohoCampaigns.contact.WRITE - To create, edit, and delete contacts or mailing lists.(CREATE,UPDATE, DELETE)
  • ZohoCampaigns.contact.ALL - To create, edit, view, and delete contacts or mailing lists. (READ, CREATE, UPDATE, DELETE)

Calling an API

Once you've generated access and refresh tokens, you can start making API calls. Calling an API works similarly to in the previous version, with just a few changes to parameters and you must now paste your access token in the header section.

  • Header: Authorization: Zoho-oauthtoken
  • API Root Endpoint: https://campaigns.zoho.com/api/v1.1/

Sample request

The parameters may vary slightly in this version. No access-related entities are used in Campaigns API requests in this version.
The API call to create a campaign in API version 1.1 is below.

XML/JSON

https://campaigns.zoho.com/api/v1.1/recentsentcampaigns?resfmt=[XML/JSON]