Developer API

Documentation and support for the The Content Authority API

Thank you for your interest in the API! This API is designed to allow developers to create their own tools and applications that can access the core functionality of this site and enable them to access their orders, create new orders, and check their account status. With the API, a software developer can make REST queries to our server and receive responses in XML format. These responses can be used to create dynamic applications that require content from our writers. This documentation’s core purpose is to describe the functionality of the API and its core functions. If you have any bugs to report or any suggestions for the API, please email: support@thecontentauthority.com

API Requirements

  • To use the API, you need an API key. To get an API key, you need to create a client account at The Content Authority.  Then, log in to your account and go to the Manage Account page.  You will find your key under the Developer API heading.
  • Ability to make REST requests to the server

The Services Available

There are currently three services available to use. AccountServiceStandardOrderService, and LabelService

Getting Started

The URL for services and requests is simple and easy to remember.

The Basic URL Syntax

http://thecontentauthority.com/api/[TheService]/[TheRequest]/

An Example Request

http://thecontentauthority.com/api/StandardOrderService/QualityList/

All requests require the API key (designated “key”) to be specified in the POST data. Failure to submit the API key will result in an error.

An Example Request Made with cURL in PHP

$args = array("key"=>"MY API KEY","order"=>$order,"notes"=>$notes,"format"=>"json");
$url = "http://thecontentauthority.com/api/StandardOrderService/ReviseOrder/";
$query = http_build_query($args, '', '&');
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST ,1);
curl_setopt($ch, CURLOPT_POSTFIELDS ,$query);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION ,1);
curl_setopt($ch, CURLOPT_HEADER ,0); // DO NOT RETURN HTTP HEADERS
curl_setopt($ch, CURLOPT_RETURNTRANSFER ,1); // RETURN THE CONTENTS OF THE CALL
$response = curl_exec($ch);
curl_close($ch);

$response = json_decode($response,true);
echo "<pre>";
print_r($response);
echo "</pre>";

Example API Failure Response

{“httpcode”:400,”responseBody”:{“message”:”Parameters that were expected were not received.”},”isSuccessful”:0}

This is the JSON result from a failed request. (An XML version will be given instead if that is the requested format. Refer to Response Format for all the available options.) This is just an example; what you see may vary depending on the request and exact nature of the problem.

Let’s break down the response:

  • httpcode – this is the error or success based on the httpcode number system.  For most developers this doesn’t matter as we now simply include the “isSuccessful” variable.
  • responseBody – this is where all the returned data is stored.
  • message – This is the response message in plain language.  If you have an error, this is an important part of the response you should read.
  • isSuccessful – either 0 or 1 depending on if the call was successful.  If it is set as 1, you can be confident that whatever action you requested to be done was successful.

Testing The API

When testing the API, use http://sandbox.thecontentauthority.com/api/ instead of the normal URL.

An Example Request Using the Sandbox

http://sandbox.thecontentauthority.com/api/StandardOrderService/QualityList/
The sandbox will give you dummy results and the data or API key that you will use will not affect those results.

Response Format

When creating a query for the API, you can specify format of the returned results by using the variable “format”. If omitted (or an invalid choice is selected), XML is used. The other option is “json” which will return results in JSON format.

$args = array(“key”=>”MY API KEY”,”order”=>$order,”notes”=>$notes,“format”=>”json”);

The Services

AccountService

The purpose of the AccountService is to enable you to get vital information about your account. The only possible request you can make with AccountService is: AccountStatus

AccountStatus

See how many credits are left in the account.

Required parameters: $key

Response: Pub_ID, Credits

StandardOrderService

The purpose of the StandardOrderService is to allow applications to view, create, and approve orders. The requests available are: QualityList,OrderListCreateOrderCancelOrderGetOrderInformationApproveOrderReviseOrder

QualityList

See the available quality levels and their price per word.

Required parameters: $key

Response: Tier, Name, Price

OrderList

Get all the orders of a given label.

Required parameters: $key, $label = label_id

Response: Returns multiple items. Each item will have: Order_ID, Step, Writer_ID, Title, Keywords, Text

CreateOrder

Create orders.

Required parameters: $key, $label = label_name, $tier, $words, $keywords, $instructions, $quantity

Response: Returns multiple items. Each item will have: Order_ID

EXAMPLE JSON SUCCESS RESULT:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Service] => StandardOrderService
            [Request] => CreateOrder
            [Response] => Array
                (
                    [0] => 9Fw0sAsA2A
                    [1] => wT87IB145T
                )

            [Label ID] => 625
            [Cost] => 30.00
        )

    [isSuccessful] => 1
)
CancelOrder

Cancel a standard order. The only orders that can be canceled are ones that haven’t been accepted or written by a writer (all orders on step 1 and some orders on step 2).

Required parameters: $key, $order

Response: Order_ID, Refunded_Amount

GetOrderInformation

Get specific information about a requested order. You can check to see if the order is approved or not as well as where it is in the order process.

Required parameters: $key, $order

Response: Order_ID, Step, Writer_ID, Title, Keywords, Instructions, Text, Approved

EXAMPLE JSON SUCCESS RESULT:

Completed Order

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [Int ID] => 0
                            [Order ID] => ApIt3s1
                            [Step] => 4
                            [Step Name] => Completed
                            [Writer ID] => 0
                            [Title] => great  article, write me!
                            [Keywords] => great article, write me!
                            [Instructions] => Hey, I'm a great article and you should write me!
                            [Text] => Old text...
                            [Approved] => 1
                            [Approve By] => 2013-02-01 16:11:27
                            [Revision] => 0
                            [Revision History] => Array
                                (
                                    [0] => Array
                                        (
                                            [Change Made] => Yes
                                            [Created] => 2013-01-29 08:28:29
                                            [Old Text] => Old  Text...
                                            [Revised Text] => New Text!!
                                        )

                                )
                        )
                )

        )

    [isSuccessful] => 1
)

Incomplete Order

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [Int ID] => 518539
                            [Order ID] => s119156-0-0
                            [Step] => 1
                            [Step Name] => Initial Approval
                            [Writer ID] => 0
                            [Title] => My Title
                            [Keywords] => my keywords
                            [Instructions] => my instructions
                            [Text] => 
                            [Approved] => 0
                            [Approve By] => 0000-00-00 00:00:00
                            [Revision] => 0
                            [Revision History] => No avaiable history
                        )

                )

        )

    [isSuccessful] => 1
)
ApproveOrder

Approve and rate orders.

Required parameters: $key, $order, $rating = integer(1-3)

Response: The status and message about the approval (status = 200 means the order has been approved successfully)

Ratings: 1 = Satisfactory, 2 = Above Expectations, 3 = Excellent above-and-beyond work

ReviseOrder

Ask for revisions for orders.

Required parameters: $key, $order, $notes

Response: The status and message about the revision (status = 200 means the request for revision has gone through)

LabelService

The purpose of the LabelService is allow applications to view available labels and set the callback for each label. Available requests: LabelList,SetCallback

LabelList

Return a list of labels and their IDs for your application to use.

Required parameters: $key

Response: Multiple items. Each item will contain: Label_ID, Name

SetCallback

Set where you want messages from the server to go. See the “Callbacks” section below for more details.

Required parameters: $key, $label = label_id, $callback = url

Response: Status of request.

RewriteService

The purpose of the RewriteService is allow applications to view, create, and manage Rewrite Orders.

CreateRewrite

Create new Rewrite Orders.

Required parameters: key, keywordswordslabeltextquantity

  • keywords – the keywords for the rewrite order, needs to be comma separated
  • words – the word count of the order
  • label – the label for the order
  • text – the complete article text for the order to be rewritten
  • quantity – the number of rewrites wanted for the rewrite order

Response: List of created rewrite orders

RewriteStatus

View the status of a rewrite order.

Required parameters: key, rewrite

  • rewrite – the rewrite order ID

Response: Will return “In Queue”, “Being Written”, “Complete”, “Being Redone”

RewriteRevision

Request a revision for a rewrite.

Required parameters: key, rewritenotes

  • rewrite – the rewrite order ID
  • notes – the reason why you’re requesting a revision

Response: Will return success message or error

CancelRewrite

Cancel a rewrite order that you do not need.

Required parameters: key, rewrite

  • rewrite – the rewrite order ID

Response: Will return success message or error. Rewrites cannot be canceled if they have been completed or are being worked on

QueueRewrites

Create rewrites from Standard Orders. The Standard Order does not need to be complete in order to queue rewrites for it. The system will automatically request the rewrites when the order is complete. The label used will be the same as the specified Standard Order.

Required parameters: key, order, words, keywords, quantity

  • order – the order ID you want to make rewrites of
  • words – the word count of the rewrite you want (cannot be greater than the standard order)
  • keywords – the keywords for the rewrite article
  • quantity – the number of rewrite articles you want

Response: Will return error or Response: Success, Orders: [list of order ids of generated Rewrites], Cost: [the cost]

RewriteLabel

View the order IDs of rewrites under the specified label. This is particularly useful when using QueueRewrites function.

Required parameters: key, label

  • label – the name of the label you want information from

Response: A list of rewrite orders under the specified label

RewriteDetailsById

View a specific rewrite that has been completed so that you can use its text in your application.

Required parameters: key, rewrite

  • rewrite – the order ID of the rewrite you want the details of

Response: Either “That order is not completed yet” or details of the completed rewrite including Order (ID), Title, Text, Completed

OrderList

Get all the orders of a given label.

Required parameters: $key, $label = label_id

Response: Returns multiple items. Each item will have: Order ID, Step, Writer ID, Title, Keywords, Text, Time Complete, Posted

DirectOrderService

The purpose of the DirectOrderService is to allow applications to view, create, and manage Direct Orders.

CreateOrder

Create new Direct Orders.

Required parameters for any direct order: key, label, words, quantity, keywords, instructions Additional parameters are required depending on whether you are using a writer’s ruleset or a custom writer pool for the order. You must choose one of these methods. Which parameters you use determine which type of order is placed. Do not include any writer pool parameters if placing a ruleset order or vice versa. Additional parameters for ruleset orders: writer, ruleset_id Additional parameters for writer pool orders: pool, specified_rate

  • label – the label for the order
  • words – the word count of the order
  • quantity – the number of articles wanted for the direct order
  • keywords – the keywords for the direct order (comma separated list)
  • instructions – instructions given to the writer
  • writer – the writer ID of the writer whose ruleset the order will use (ruleset orders only)
  • ruleset_id – the ruleset ID to use (ruleset orders only)
  • pool – the ID of the customer writer pool to use (writer pool orders only)
  • specified_rate – the cost per word you are willing to pay for the order (writer pool orders only)

Response: List of created direct orders

VerifyCanOrder

Determine whether an order with the given parameters can be placed without actually placing it.

Required parameters are identical to those for CreateOrder

Response: Either a message indicating order is valid and also the cost of the order or an error message

DORevision

Request a revision for a direct order.

Required parameters: key, ordernotes

  • order – the direct order ID
  • notes – the reason why you’re requesting a revision

Response: Will return success message or error

CancelDO

Cancel a direct order that you do not need.

Required parameters: key, order

  • order – the direct order ID

Response: Will return success message or error. Direct orders cannot be canceled if they have been completed or are being worked on

FavoriteWriterList

See the writers you have favorited and the Away status for each.

Required parameters: key

Response: A list containing data for each writer you have favorited through TCA. Data includes writer_id, Nickname, and Is Away (1 if the writer is away, 0 otherwise). If the writer is away and has scheduled a return date, the data also includes it under Scheduled Return Date

PoolList

Get the pool IDs and writer counts for all your custom writer pools.

Required parameters: key

Response: A list containing data for each of your saved custom writer pools. Data consists of ID, Name, and Writers (the number of writers in the pool)

GetPoolDetails

See the writers in a given pool and the Away status for each.

Required parameters: key, pool

  • pool – the writer pool ID

Response: Name, being the name of the pool, and Writers, being a list of data for each writer in it. Writer data includes writer_id, Nickname, and Is Away (1 if the writer is away, 0 otherwise). If the writer is away and has scheduled a return date, the data also includes it under Scheduled Return Date

RulesetList

See a writer’s available rulesets and the order placement requirements for each of them.

Required parameters: key, writer

  • writer – the writer ID

Response: Rulesets, a list containing data for each of the writer’s available rulesets. Data includes ID, Name, Description, Minimum Word Count, Maximum Word Count, Cost Per Word, Tags

GetOrderInformation

Get specific information about a requested direct order. You can check to see if the order is approved or not as well as where it is in the order process.

Required parameters: key, order Response: Order_ID, Step, Writer_ID, Title, Keywords, Instructions, Text, Approved

OrderList

See all the direct orders of a given label. (Canceled orders are not included.)

Required parameters: key, label

  • label – the label ID

Response: Returns multiple items. Each item will have: Order_ID, Step, Writer_ID, Instructions, Title, Keywords, Text, Time_Complete, Posted

ContentAndBacklinksService

The purpose of ContentAndBacklinksService is to allow client’s and developers to utilize our powerful semi-automatic article marketing solution.   Utilizing our talented writers, we write authoritative articles which are posted on other sites with up to two links that direct readers to whichever site you choose. Some of the functions found for this service return a “stage” parameter.  The stages that can be returned to you are:

  1. initial_approval
  2. writer_queue
  3. writer_writing
  4. editing
  5. client_approval
  6. completed
  7. revision
  8. canceled
client_approval is the most important stage in terms of what you should be looking for as that is when an order has been completed and is ready for your approval/revision.  After 72 hours, the status will change from client_approval to completed and you will lose the ability to request any revisions.

CreateOrder

Required parameters:  key, label, at1, au1, qty, instructions, post_to, post_to_account

Optional parameters: at2, au2

  • label – the string name of the label for the order (it will be used for the GetOrders request)
  • at1 – Anchor Text 1, this is the keyword that you wish to use in the first link
  • au1 – Anchor URL 1, this is the URL for the keyword you want to point to for the first link
  • at2 – Anchor Text 2 (optional), this is the keyword that you wish to use in the second link
  • au2 – Anchor URL 2 (optional), this is the URL for the keyword you want to point to for the second link
  • qty – Quantity, the number of articles with the given settings to be ordered
  • instructions – Specific instructions for the writers about the article.
  • post_to – the name of the site you want the article to be posted to (refer to the GetSites request for the list of sites)
  • post_to_account – The account you want to post us to use. If you want to use a personal account, you’ll need to set it up within the site (http://thecontentauthority.com/client/submit-content.php?tab=settings, refer to the GetSites request for the list of sites/accounts)

Example Successful Response

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Invoice ID] => 90541
            [Total Cost] => 10
            [Credits Left] => 7893.15
            [message] => Successfully completed the order.
        )

    [isSuccessful] => 1
)

Example Failed Response

Array
(
    [httpcode] => 400
    [responseBody] => Array
        (
            [message] => Quantity must be greater than 1
        )

    [isSuccessful] => 0
)

GetSites

Required parameters:  key

Example Successful Response

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Sites] => Array
                (
                    [350 - General] => Array
                        (
                            [accounts] => Array
                                (
                                    [0] => TCA Account
                                )

                            [cost] => 17
                            [words] => 600
                            [tier] => Excellent
                        )

                    [350 - HealthNBeauty] => Array
                        (
                            [accounts] => Array
                                (
                                    [0] => TCA Account
                                )

                            [cost] => 17
                            [words] => 600
                            [tier] => Excellent
                        )

                    [Angelfire - General] => Array
                        (
                            [accounts] => Array
                                (
                                    [0] => TCA Account
                                )

                            [cost] => 17
                            [words] => 600
                            [tier] => Excellent
                        )

                    [...]

                    [Xanga - HealthNBeauty] => Array
                        (
                            [accounts] => Array
                                (
                                    [0] => TCA Account
                                )

                            [cost] => 13
                            [words] => 400
                            [tier] => Excellent
                        )
                )
        )

    [isSuccessful] => 1
)

What the heck does all this mean?

With GetSites we return a list of sites (by name) along with the available accounts for that site.  Typically “TCA Account” is available however some sites will require you to make your own personal account.  Cost is the cost per article for the given site.  Words is the minimum word count our writers have to write for the article.  Tier determines which writers, by quality, can accept and write the article, by choose tiers that best match the site we’re posting to to help ensure the post’s longevity.

GetOrders

Required parameters:  key, label

  • label – the label (string or ID)
Example Successful Response
Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Label] => my test
            [Orders] => Array
                (
                    [s90529-0-0] => Array
                        (
                            [ID] => s90529-0-0
                            [Status] => Being Written
                            [Post ID] => 
                            [Post URL] => N/A
                            [Post Date] => N/A
                            [Indexed] => No
                            [Rank] => N/A
                        )

                    [s90548-0-0] => Array
                        (
                            [ID] => s90548-0-0
                            [Status] => Being Written
                            [Post ID] => 
                            [Post URL] => N/A
                            [Post Date] => N/A
                            [Indexed] => No
                            [Rank] => N/A
                        )

                )

        )

    [isSuccessful] => 1
)

What the heck does this all mean? With GetOrders we return all of the Content & Backlinks you’ve ordered with a given label.  Ultimately this list will help you determine the status of the order (whether it’s being written, posted, or completed) and give you some meta data about the order.  Post ID is the internal ID used on orders being posted, reference “Submit Content” tab.   When posted, Post URL is the URL to your posted article.  Post Date refers to the date the post was posted.   Indexed refers to if the post was indexed by the search engines.  Rank is based on SEOMoz’s domain rank system to determine authority the article’s links may have.

CancelOrder

Cancel a Content & Backlinks order. The only orders that can be canceled are ones that haven’t been accepted or written by a writer (all orders on step 1 and some orders on step 2)

Required parameters: $key, $order Response: Order_ID, Refunded_Amount

Callbacks

Callbacks allow our server to communicate with your application when critical steps occur for an order, such as the order being completed (so it needs your approval). Our server will send an HTTP POST request to the callback URL associated with the label to which the order belongs. You designate this URL using SetCallback, part of LabelService (documented above).

Note that every order assigned to a label will use the same callback URL. You won’t need to use SetCallback more than once for any given label unless you need to change the URL.

On the other hand, newly created labels do not have a callback URL. You will have to call SetCallback for each label you create if you want all orders to use this system.

The POST request we send will use the following parameters: $status, $order = order_id

Possible Values for Status:

  1. Complete
  2. Revision

Using the designated status, you can make appropriate decisions with your application, such as requesting a revision or approving the completed order.

Callback data is only sent once per event. Because the odd circumstance may occur where your application fails to receive them (e.g. if your site is down at the wrong moment), it is recommended that your application does not rely on them exclusively. Instead, query the API using periodic checks (perhaps daily) to look at your order’s status and then supplement this with callbacks where a speedy reaction is beneficial.

Please do not call the API too frequently for these periodic checks, however. Abuse of the API in this or any other way may result in the offending individuals’ access to the API being limited or revoked.