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