Orders API

GET/orders

Retrieve the details for all your orders, including details for individual articles within order.

Request

Note: Responses will be limited to 50 orders at a time. Larger volumes will need to be navigated via pagination.

The following fields will not be populated for Offering orders: attachment, purpose, project_notes, style_guide.

Request Headers

Header Value
Content-Type application/json
Accept application/json
Authorization Bearer (using bearer token from /oauth/token)

Response

Response Status Codes

Code Description
200 OK
400/401 Unauthorized
403 Forbidden
500 Internal Server Error

Example Successful Response

{
    "current_page": 1,
    "last_page": 1,
    "result_count": 1,
    "total_count": 1,
    "result": [
        {
            "id": 2889,
            "type": "article",
            "attachment": null,
            "purpose": "Article",
            "project_notes": "",
            "style_guide": null,
            "created_at": "2016-01-27 14:08:32",
            "articles": [
                {
                    "id": 13851,
                    "title": "Product X",
                    "instructions": "Write a description for Product X, using details from abc.com/productx",
                    "niche": "Style",
                    "min_word_count": 200,
                    "max_word_count": 300,
                    "price": 12.50,
                    "days_to_complete": 3,
                    "order_type": "Contact (4+ Star Writers)",
                    "writer": "duchess",
                    "pool": null,
                    "status": "Writing In-process",
                    "current_deadline": "2015-01-10",
                    "submitted_at": null,
                    "accepted_at": null,
                    "created_at": "2014-01-07 12:54:11"
                }
            ]
        }
    ]
}

Example Error Response

{
    "error": "forbidden",
    "error_description": "You are not authorized to access this resource"
}

POST/orders

Create a new order. You must have sufficient funds in your account before you can place an order. This can be checked before attempting to place your order using the /account endpoint.

Request

Note: Offering orders cannot be placed via API.

Request Headers

Header Value
Content-Type application/json
Accept application/json
Authorization Bearer (using bearer token from /oauth/token)

Request Parameters

Field Description Required
purpose

The intended use for the ordered articles, to classify the listing for easy browsing. Available options:

  • Article
  • Banner Ads
  • Blog Post
  • Brochure
  • Direct Mail
  • eBook
  • Editing
  • Facebook
  • Guest Post
  • Ideas
  • Landing Page
  • Other
  • Press Release
  • Product Description
  • Radio Script
  • Resume
  • Technical Writing
  • Translation
  • TV Script
  • Tweets
  • Video Script
  • Webinar
  • Website Copy
  • White Paper

Yes
project_notes Personal reference notes for the order. This is for your eyes only, to be used for organizational purposes. No
style_guide The name of your Style Guide which applies to the articles in this order. Style Guides can be created or edited via the Style Guide API. No
articles

Array containing the following individual article details:

Field Description Required
title Topic to be written Yes
instructions Detailed instructions to the Writer. Be as specific as possible and provide examples where appropriate. Yes
niche List of available niches can be viewed here No
min_word_count Minimum word count Yes
max_word_count Maximum word count Yes
price Total price for the article (not per word price) Yes
days_to_complete How many days the Writer will have to write the article Yes
order_type
  • Open — Makes article available for Writers to take freely.
  • Contact — Makes article available for Writers to apply to write, but Writer must be approved by you before they can take it.
  • Direct — Assign the article directly to the specific Writer supplied in the "assign_to" field.
  • Pool — Makes article available to all Writers who belong to the Writer Pool provided in the "assign_to" field.
Yes
assign_to

For Direct and Pool orders, simply provide the name of the desired Writer or Pool.

Open and Contact orders can be assigned to the following predefined Writer populations:

  • All Writers (default if none supplied)
  • 3+ Star Writers
  • 4+ Star Writers
  • Most Active Writers
Yes
Yes

Example Request Body

{
    "purpose": "Article",
    "project_notes": "Batch #4 for client X",
    "style_guide": null,
    "articles": [
        {
            "title": "Product X",
            "instructions": "Write a description for Product X, using details from abc.com/productx",
            "niche": "Style",
            "min_word_count": 200,
            "max_word_count": 300,
            "price": 12.50,
            "days_to_complete": 3,
            "order_type": "Contact",
            "assign_to": "4+ Star Writers"
        }
    ]
}

Response

Response Status Codes

Code Description
200 OK
400/401 Unauthorized
402 Insufficient Funds
403 Forbidden
422 Failed Validation
500 Internal Server Error

Example Successful Response

{
    "id": 2889,
    "type": "article",
    "attachment": null,
    "purpose": "Article",
    "project_notes": "Batch #4 for client X",
    "style_guide": null,
    "created_at": "2016-01-27 14:08:32",
    "articles": [
        {
            "id": 13851,
            "title": "Product X",
            "instructions": "Write a description for Product X, using details from abc.com/productx",
            "niche": "Style",
            "min_word_count": 200,
            "max_word_count": 300,
            "price": 12.50,
            "days_to_complete": 3,
            "order_type": "Contact (4+ Star Writers)",
            "writer": "duchess",
            "pool": null,
            "status": "Writing In-process",
            "current_deadline": "2015-01-10",
            "submitted_at": null,
            "accepted_at": null,
            "created_at": "2014-01-07 12:54:11"
        }
    ]
}

Example Error Response

{
    "error": "failed_validation",
    "error_description": "Some fields contained invalid values",
    "validation_errors": [
        "style_guide": "Style Guide 'Press Releases' not found",
        "articles": {
            "0": [
                "max_word_count": "Must be greater than minimum",
                "price": "Must be an amount greater than 0"
            ],
            "2": [
                "order_type": "Must be one of: Open, Contact, Direct, Writer Pool"
            ]
        }
    ]
}

Vaidation Errors

Validation errors for the "articles" array will be returned as an object with properties referencing the indices of the original array to identify which article the errors belong to. So in the example error response, we can see it was the first and third articles submitted had errors.

GET/orders/{order_id}

Retrieve the details for a specific order by ID, including details for individual articles within order.

Request

The following fields will not be populated for Offering orders: attachment, purpose, project_notes, style_guide.

Request Headers

Header Value
Content-Type application/json
Accept application/json
Authorization Bearer (using bearer token from /oauth/token)

Response

Response Status Codes

Code Description
200 OK
400/401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example Successful Response

{
    "id": 2889,
    "type": "article",
    "attachment": null,
    "purpose": "Article",
    "project_notes": "",
    "style_guide": null,
    "created_at": "2016-01-27 14:08:32",
    "articles": [
        {
            "id": 13851,
            "title": "Product X",
            "instructions": "Write a description for Product X, using details from abc.com/productx",
            "niche": "Style",
            "min_word_count": 200,
            "max_word_count": 300,
            "price": 12.50,
            "days_to_complete": 3,
            "order_type": "Contact (4+ Star Writers)",
            "writer": "duchess",
            "pool": null,
            "status": "Writing In-process",
            "current_deadline": "2015-01-10",
            "submitted_at": null,
            "accepted_at": null,
            "created_at": "2014-01-07 12:54:11"
        }
    ]
}

Example Error Response

{
    "error": "not_found",
    "error_description": "Not a valid resource"
}