Introduction

The Zerys API allows any organization the ability to build custom, 3rd party applications that interact with our Zerys database. Our API will allow users of your applications to easily place content orders, view status updates, review content, request revisions, view reports, and more.

This documentation will provide your team the necessary details and instructions they will need to make specific calls and requests to and from our system. When making a call, the result will be returned to you in XML/JSON format so you can easily integrate the data directly into your own application.

Requirements

Use of the Zerys API requires the following:

  1. A Zerys for Agencies Account – your API Account Manager will help you setup your Zerys account, including your primary username (email) and password. We can create separate profiles for any other users in your organization you wish to be copied on account updates such as funding receipts, status updates, etc.
  2. A Token Security Key - Your Zerys API Account Manager will provide you with a unique API key that will need to be passed along with every call and request you make for security reasons. You can use the demo key provided below for testing purposes.
  3. Funding – you’ll need to deposit funds into your Zerys account before placing orders. You’ll need to maintain a balance in your account that is enough to cover all purchases made at the time of ordering. As you approve and purchase documents, the cost of each document will be deducted from your remaining balance. Any unused funds can be refunded back to your payment method at any time. To add funds and view your balance at any time, you can either login to your Zerys for Agencies account here, or make a “getbalance” call through the API

How it Works – Overview

Once your token key and funding is setup, you can begin placing content orders by passing all the required fields shown below. Once an order is placed, the status of the title will update to “Assigned”. The title will be posted and offered only to the most experienced and highest ranked writers in our network of over 85,000 writers, using a proprietary algorithm that ensures only the highest rated writers in our cast network always get first access to all jobs. If a job is not taken quickly by a writer, the job will gradually be opened up to the next batch of most experienced and high rated writers until the job is taken.

Jobs with higher price offers are typically taken within a matter of minutes. Jobs with lower price offers may take a bit longer to be taken, but are almost always taken within 24 hours. In general, the higher the price offer you make, the higher caliber writer you will attract, and the better quality content you’ll get. Over time, we will identify the top performing writer candidates and create a pool of the best writers and add them to your team of writers so that future orders will first go to them. So over time, the quality will get better and better.

Once the writer takes the job, the status of the job will update to “In Progress”.

Once the content is submitted to you by the writer, you’ll be able to review each piece and take one of the following review actions:

  • Approve
  • Decline

If you approve a piece, you’ll then be able to display the content in your application.

You’ll also be able to view other summary data about your account and your orders. There are thousands of data points and all are not shown here. Just let us know the specific data point you’d like to show and we will provide the request to you to pull it.


API Base URL: https://api.zerys.com

API Endpoints & Authentication

All requests to the API are sent via the HTTP POST method to one of our API endpoint URLs.

  • XML Content-Type: text/xml
  • JSON Content-Type: application/json

Please use the below to get the authentication, passing the below parameter in request to get the access token.
DEMO user name and api key:

  • Zerys Api UserName: apidemo@zerys.com
  • Zerys Api Key: 00EABD0D-BC84-4345-A616-30D3F6186AB7

Authentication Endpoint: https://api.zerys.com/token

Request

Parameter Description
UserName Zerys Api UserName
Password Zerys Api Key
grant_type password (pass password as grant_type)

Response

Parameter Description
access_token access token to authorize the api calls. Please pass this token as bearer token in Authorization header
(eg: Authorization: Bearer {access_token})
token_type Bearer
expires_in token validity in seconds

Order

Use this method to place an order for a title:

Request

Parameter Description Format
client Name of the Client String 200 character
Project Name of the project String 500 character
Keyword Keyword for the title String 100 character
Title Title of the article String 200 character
Max_words Maximum words for the article Number
Writer Pass writer pen name
ex: deb-123 for direct assignment and empty for Favorite Writer Job Board
String
Instructions Use this to give Instruction to writer String 2000
Cents_per_word price per word in cents
For Job Board - Anyone of the value (3, 4, 5, 6, 7, 8, 9, 10, 12, 15, 25, 30)
Decimal

Response

Parameter Description Format
Success True or False bool
Message Success message / reason for failure String
Client_id Unique Number assigned for the client Number
Project_id Unique Number assigned for the project for the client Number
Title_id Unique Number for the title belongs to the project of the client Number
Balance Remaining balance available for the client in the account Numeric

Get Titles

Use this method to get a list of all titles belonging to a project for a given client, by status:

Request

Parameter Description Format
Client Name of the Client String 200 character
Project Name of the project String 500 character
Status Status of the Title
› assigned
› in_progress
› my_review (Pending Agency Review)
› client_review (Pending Client Review)
› approved
› cancelled
String 500 character

Response

Parameter Description Format
Content_unique_id Unique Number Assigned for the article belongs to the title of the project Number
Title_id Unique Number for the title belongs to the project of the client Number
Project Name of the project String 500 character
Keyword Keyword for the title String 100 character
Title Title of the article String 200 character
Content Article written by the writer using the keyword and title given by us String
Max_words Max word given by us for the article while ordering Number
Cents_per_word Cost per word for the article Numeric
Writer Writer Pen-name (deb-123) who wrote the article String
Words_written The words written by the writer for the article Number
Status Status of the Title String 500 character
Amount Calculated amount for the article written by the writer as per formula Numeric
Etc_days Estimated Completion date Number
Deadline Deadline set for the article as per the word count Datetime
Ordered_date When the title is ordered Datetime
Approved_date When the title is approved by the client Datetime

Approve

Use this method to approve the article written by the writer:

Request

Parameter Description Format
Title_id Unique Number assigned for the title of the project which belongs to particular client Number
Notes_to_writer Approval notes to the writer from client String 2000 character
Bonus
(Optional) If the Client wants to give any additional amount to the writer appreciating his work we can use Bonus parameter Numeric

Response

Parameter Description Format
Success True/ False bool
Message Success message or Failure message String 500 character
Balance Remaining balance available for the client in the account Numeric

Decline

Use this method to reject an article written by a writer:

Request

Parameter Description Format
Title_id Unique Number for the title belongs to the project of the client Number
Reason Reason for Declining the title String 2000 character

Response

Parameter Description Format
Success True/ False bool
Message Success message or Failure message String 500 character
Balance Remaining balance available for the client in the account Numeric

Get Content

Use this method to retrieve and view the content for a particular document submitted to you for review by a writer:

Request

Parameter Description Format
Content_unique_id (Optional) Unique Number Assigned for the article belongs to the title of the project Number
Title_id Unique Number assigned for the title of the content Number

Response

Parameter Description Format
Content_unique_id Unique Number Assigned for the article belongs to the title of the project Number
Title_id Unique Number assigned for the title of the content Number
Project Name of the project String 500 character
Keyword Keyword for the title String 100 character
Title Title of the article String 200 character
Content Article written by the writer using the keyword and title given by us String
Max_words Max word given by us for the article while ordering Number
Cents_per_word Cost per word for the article Numeric
Writer Writer Pen-name (deb-123) who wrote the article String
Words_written The words written by the writer for the article Number
Status Status of the Title String 500 character
Amount Total amount Numeric
Etc_days Estimated Completion date Number
Deadline Deadline set for the article as per the word count Datetime
Ordered_date When the title is ordered Datetime
Approved_date When the title is approved by the client Datetime