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. AccountService, StandardOrderService, and LabelService
Getting Started
The URL for services and requests is simple and easy to remember.
— The Basic URL Syntax
https://app.thecontentauthority.com/api/[TheService]/[TheRequest]/
— An Example Request
https://app.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 = "https://app.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 https://sandbox.thecontentauthority.com/api/ instead of the normal URL.
— An Example Request Using the Sandbox
The sandbox will give you dummy results and the data or API key that you will use will not affect those results.https://sandbox.thecontentauthority.com/api/StandardOrderService/QualityList/
— 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
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, OrderList, CreateOrder, CancelOrder, GetOrderInformation, ApproveOrder, ReviseOrder
See the available quality levels and their price per word.
Required parameters: $key
Response: Tier, Name, Price
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
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 )
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
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 )
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
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
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
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.
Create new Rewrite Orders.
Required parameters: key, keywords, words, label, text, quantity
- 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
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”
Request a revision for a rewrite.
Required parameters: key, rewrite, notes
- rewrite – the rewrite order ID
- notes – the reason why you’re requesting a revision
Response: Will return success message or error
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
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]
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
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.
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
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, order, notes
- order – the direct order ID
- notes – the reason why you’re requesting a revision
Response: Will return success message or error
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
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
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
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:
- Complete
- 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), your application should not rely on callbacks 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.