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 (a publisher account is required to get a key).  To get an API key, you need to create an account at The Content Authority.  Log into your account and then 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

To get started, you must consider if you need the use of callbacks. When callbacks are turned on, when orders arrive at a critical stage that requires your interaction, our server will contact a specified web address with details of that order allowing your application to approve, post, or reject the order it receives. Callbacks are handled by each individual label on the publisher account and can be specified through the LabelService. The URL for services and requests are 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 specified in the POST data. Failure to submit the API key will result in an error. A Example Request Made With CURL $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 (the equivalent will be given in XML as requested (refer to Response Format for all the available options)).  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/ 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 XML (default) or JSON When creating a query for the API, you can specify format of the returned results by using the variable “format”. By default it is set as XML however you can use “json” to get the 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

Required parameters: $key

Response: Pub_ID, Credits The purpose of AccountStatus is allow your application to see how many credits are left in the account.

StandardOrderService

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

QualityList

Required parameters: $key

Response: Tier, Name, Price The purpose of QualityService is to enable you to see the available quality levels and their price per word.

OrderList

Required parameters: $key, $label = label_id

Response: Returns multiple items. Each item will have: Order_ID, Step, Writer_ID, Title, Keywords, Text The purpose of OrderList is to allow your application to get all the orders of a given label.

CreateOrder

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

Response: Returns multiple items. Each item will have: Order_ID The purpose of CreateOrder is to allow your application to create orders remotely.

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

Required parameters: $key, $order

Response: Order_ID, Refunded_Amount The purpose of CancelOrder is to allow your application to cancel orders remotely. 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)

GetOrderInformation

Required parameters: $key, $order

Response: Order_ID, Step, Writer_ID, Title, Keywords, Instructions, Text, Approved The purpose of GetOrderInformation is to 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.

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

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) The purpose of ApproveOrder is to allow your application to remotely approve and rate orders. Ratings: 1 = Satisfactory, 2 = Above Expectations, 3 = Excellent above-and-beyond work

ReviseOrder

Required parameters: $key, $order, $notes

Response: The status and message about the revision (status = 200 means the request for revision has gone through) The purpose of ReviseOrder is to allow your application to remotely ask for revisions for orders.

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

Required parameters: $key

Response: Multiple items. Each item will contain: Label_ID, Name The purpose of LabelList is to return a list of labels and their IDs for your application to use.

SetCallback

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

Response: Status of request. The purpose of SetCallback is to allow your application to set where you want messages from the server to go.

RewriteService

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

CreateRewrite

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 The purpose of CreateRewrite is to allow your application to create new Rewrite Orders

RewriteStatus

Required parameters: key, rewrite

  • rewrite – the rewrite order ID

Response: Will return “In Queue”, “Being Written”, “Complete”, “Being Redone” The purpose of RewriteStatus is to allow your application to view the status of a rewrite order.

RewriteRevision

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 The purpose of RewriteRevision is to allow your application request a revision for a rewrite

CancelRewrite

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 The purpose of CancelRewrite is to allow your application to cancel Rewrites that you do not need.

QueueRewrites

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] The purpose of QueueRewrites is to allow your application to 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 create the rewrites when the order is complete. The label used will be the same as the specified Standard Order.

RewriteLabel

Required parameters: key, label

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

Response: A list of rewrite orders under the specified label The purpose of RewriteLabel is to allow your application to view the rewrites IDs under the specified label. This is particularly useful when using QueueRewrites function.

RewriteDetailsById

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 The purpose of RewriteDetailsById is to allow your application to view a specific rewrite that has been completed so that you can use its text in your application.

OrderList

Required parameters: $key, $label = label_id Response: Returns multiple items. Each item will have: Order_ID, Step, Writer_ID, Title, Keywords, Text The purpose of OrderList is to allow your application to get all the orders of a given label.

DirectOrderService

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

CreateOrder

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 The purpose of CreateOrder is to allow your application to create new Direct Orders.

VerifyCanOrder

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 The purpose of VerifyCanOrder is to allow your application to determine whether an order with the given parameters can be placed without actually placing it.

DORevision

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 The purpose of DORevision is to allow your application request a revision for a direct order.

CancelDO

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 The purpose of CancelDO is to allow your application to cancel direct orders that you do not need.

FavoriteWriterList

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, this is given under the label Scheduled_Return_Date The purpose of FavoriteWriterList is to allow your application to see the writers you have favorited and the Away status for each.

PoolList

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) The purpose of PoolList is to allow your application to get the pool IDs and writer counts for all your custom writer pools.

GetPoolDetails

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, this is given under the label Scheduled_Return_Date The purpose of GetPoolDetails is to allow your application to see the writers in a given pool and the Away status for each.

RulesetList

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 The purpose of RulesetList is to allow your application to see a writer’s available rulesets and the order placement requirements for each of them.

GetOrderInformation

Required parameters: key, order Response: Order_ID, Step, Writer_ID, Title, Keywords, Instructions, Text, Approved The purpose of GetOrderInformation is to 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.

OrderList

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 The purpose of OrderList is to allow your application to see all the direct orders of a given label. (Canceled orders are not included.)

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

Required parameters: $key, $order Response: Order_ID, Refunded_Amount The purpose of CancelOrder is to allow your application to cancel orders remotely. 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)

UAWService

The purpose of UAWService is to allow clients and developers to order, manage, and look-up UAW (Unique Article Wizard) style articles and sets using remote applications and software. CreateOrder

Required parameters: $key, $label (label name), $type,  $topic, $word_count, $qty, $extra_titles (optional), $resource_boxes (optional), $at_1, $au_1, $at_2 (optional), $au_2 (optional), $instructions

  • label – the label name you want to group orders under (used for look-up in the future)
  • type – see UAWService::GetOptions for available types, designates quality level and whether you want a single article or a set.  You will use the “handle” from the GetOptions call here.
  • topic – topic/keywords that describe the article to the writer and is used to determine content
  • word_count – word count for the article as described in UAWService::GetOptions
  • qty – number of sets/articles with the given settings
  • extra_titles – extra titles to be written by the writer, see UAWService::GetOptions for acceptable values (only available for set orders)
  • resource_boxes – resource boxes to be written by the writer using the anchor texts/urls, see UAWService::GetOptions for acceptable values (only available for set orders)
  • at_1 – Anchor Text 1 for resource box (only required for set orders)
  • au_1 – Anchor URL 1 for resource box (only required for set orders)
  • at_2 – (optional) Anchor Text 2 for resource box (only required for set orders)
  • au_2 – (optional) Anchor URL 2 for resource box (only required for set orders)
  • instructions – special instructions given to the writer about how to write the article (or content desired within)
Response:
Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [message] => Successfully completed the order.
            [Order IDs] => Array
                (
                    [0] => u92083-0-0
                    [1] => u92083-0-1
                )

            [Credits Remaining] => 7012.94
            [Label] => 70272
        )

    [isSuccessful] => 1
)

GetOptions

Required parameters: $key

Response:

Returns a list of available options to be used with CreateOrder.

GetOrders

Required parameters:  $key, $label (ID)

Response:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Orders] => Array
                (
                   [14] => Array
                        (
                            [ID] => u92085-0-1
                            [Created] => 2012-10-09 20:31:24
                            [Completed] => 0000-00-00 00:00:00
                            [Stage] => initial_approval
                            [Type] => high article
                            [Topic] => test
                            [Word Count] => 500
                            [Anchor Text 1] => 
                            [URL 1] => 
                            [Anchor Text 2] => 
                            [URL 2] => 
                            [Extra Titles] => 0
                            [Resource Boxes] => 0
                            [Instructions] => test
                            [Titles] => 
                            [Articles] => 
                            [Titles Results] => 
                            [Resource Boxes Results] => 
                            [Revision] => 
                            [Canceled] => 0
                            [Rating] => 0.0
                        )

                )

        )

    [isSuccessful] => 1
)

GetOrderInformation Required parameters:  $key, $order (ID) Response:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [Orders] => Array
                (
                    [0] => Array
                        (
                            [ID] => u11111-0-0
                            [Created] => 2012-10-03 00:00:00
                            [Completed] => 2012-10-09 15:28:14
                            [Stage] => completed
                            [Type] => standard single
                            [Topic] => test topic
                            [Word Count] => 500
                            [Anchor Text 1] => 
                            [URL 1] => 
                            [Anchor Text 2] => 
                            [URL 2] => 
                            [Extra Titles] => 0
                            [Resource Boxes] => 0
                            [Instructions] => test
                            [Titles] => Array
                                (
                                    [0] => Test test test test
                                )

                            [Articles] => Array
                                (
                                    [0] => Asu yelem pupog miw [...]
                                )

                            [Titles Results] => Array
                                (
                                    [0] => Test test test test
                                )
                            [Resource Boxes Results] => Array
                                (
                                    [0] => Test test test test
                                )
                            [Revision] => 
                            [Canceled] => 0
                            [Rating] => 3.0
                        )

                )

        )

    [isSuccessful] => 1
)

  CancelOrder

Required parameters:  $key, $order (ID)

Response:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [message] => Successfully canceled and refunded the order.
            [amount] => 6.00
        )

    [isSuccessful] => 1
)

RevisionRequest

Required parameters:  $key, $order (ID), $reason (why is this order getting a revision request?)

Response:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [message] => Successfully submitted revision request.
        )

    [isSuccessful] => 1
)

ApproveOrder

Required parameters:   $key, $order (ID), $rating (1 – 5 (best))

Response:

Array
(
    [httpcode] => 200
    [responseBody] => Array
        (
            [message] => Successfully submitted approval request.
        )

    [isSuccessful] => 1
)

Callbacks

The callback allows our server to communicate with your application when critical steps occur that require your approval. Our server will send a HTTP POST request via CURL to a URL designated with SetCallback 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 including requesting a revision or approving the completed order.