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

The Services Available

There are currently three services available to use. AccountService, StandardOrderService, 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

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

LabelService

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

RewriteService

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

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.

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

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)

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
)

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)

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.