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.

Quick Links...

How is version 1.1 better?
Prerequisites
Generation of access and refresh tokens
Campaign Scopes
Calling an API
Sample request

How is version 1.1 better?

There are two major advantages of using version 1.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.

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.
Zoho Accounts will forward this request to the corresponding Zoho Campaigns account owner.
The Zoho Campaigns owner will verify this request and grants permission/access to the requested scopes.
As an acknowlegement to the granted request, Zoho Accounts will send a grant code to you.
Using this grant code, you can request for access token from Zoho Accounts.
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.

Note :

If the scope is specified incorrectly, we will return an "INVALID_SCOPE" error.

Module	Scope Name	Description
Campaigns	ZohoCampaigns.campaign.CREATE	To create campaigns and merge tags
	ZohoCampaigns.campaign.READ	To view a report or the details of a campaign
	ZohoCampaigns.campaign.UPDATE	To update campaigns and coupons
	ZohoCampaigns.campaign.DELETE	To delete a campaign
Contacts	ZohoCampaigns.contact.CREATE	To create contacts or mailing lists
	ZohoCampaigns.contact.READ	To view details or a report of contacts or mailing lists.
	ZohoCampaigns.contact.UPDATE	To update contacts or mailing lists.
	ZohoCampaigns.contact.DELETE	To 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. To call an API, you must paste your access token in the header section.

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

Sample request

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]