The Scripted API

Easy like Sunday Morning

Sign in or join to take full advantage of this Interactive Documentation

Authentication is required for many functions of the Scripted API. We use token-based authentication.

You can think of your business_id as your username, and your key as your password.

By default, we respond in JSON.

We can also respond in XML.

Specifying format is easy: format=xml

Create a Job

/jobs/create

Param
Description
Example
Encoded

form_fields (required)
A hash where the keys are identifiers, and the values are whatever you’d like our writer to know. The identifier, human name, description and type of every format-specific form_field is returned as an array by the List Format Ids function.

format_id (optional)
Defaults to Standard Blog Post. See List Format Ids.
industry_ids (optional)
Which industries should your writers understand? See List Industry Ids.
guideline_ids (optional)
Which guidelines should your writer follow? See List Guideline Ids.
delivery (optional)
Defaults to Standard (5 Days).
sandbox (optional)
You don’t actually want to create a job, do you?

Example Request



Unless industry_ids or guideline_ids are provided, the API will assume your most recent settings.

To update those settings,
log in to your dashboard
and click on the Create a Job tab.


Simulate Job Claiming for a Sandboxed Job

/jobs/sandbox_claim/abc123abc123 is the id of the sandboxed job for which you want to simulate the process of a writer claiming the job.

Simulate Job Submission for a Sandboxed Job

/jobs/sandbox_finish/abc123abc123 is the id of the sandboxed job for which you want to simulate the process of a writer submitting their work.


Show a Current Job

/jobs/show/abc123abc123 is the id of the job are showing. Use List Current Jobs to find the id.

Example Request

https://scripted.com/jobs/show/abc123?business_id=abc&key=123

Example Response

{ "id":"abc123",
  "topic":"My First Job on Scripted!",
  "count":1,
  "details":"Things to Mention: cats",
  "delivery":"standard",
  "business_id":"abc123",
  "guideline_ids":["def456"],
  "industry_ids":["ghi789"],
  "format_id":"jkl123",
  "form_fields":{"things_to_mention":"cats"},
  "state":"Claimed",
  "sandbox": false,
  "created_at":"2014-03-15T00:30:00Z",
  "deadline_at":"2014-03-20T00:30:00Z" }

Destroy a Current Job

/jobs/destroy/abc123abc123 is the id of the job that you want to destroy. This is the same id returned by Create a Job.

This function destroys a job.

Example Request

/jobs/destroy/abc123?business_id=abc&key=123

Heads Up! This function only works on unclaimed jobs.


List Industry Ids

All the publicly available industries. No authentication required.

/industries

You can also pass your business_id and key if you’d like the the API to return just your account’s default Industries.

Actual Response



List Guideline Ids

All the publicly available guidelines. No authentication required.

/guidelines

You can also pass your business_id and key if you’d like the the API to return just your account’s default Guidelines.

Actual Response



List Format Ids

All the publicly available formats. No authentication required.

/formats

Returns min_count as an integer, representing the minimum count for jobs of that format. For example, you cannot order Tweets in batches smaller than 50.

Returns pitchable as a boolean, which represents whether the format can be pitched.

Returns length_metric as a string, which is something like “350 words” or “140 characters”.

Returns form_fields as an array. The elements are as follows:

You can also pass your business_id and key if you’d like the the API to return any custom formats that have been assigned to your account.

Actual Response



Add a Default Industry

/industries/create/abc123abc123 is the id of the industry that you want to add to your default industries.


Set Default Industries

/industries/set_all?ids=abc123,def456abc123,def456 are the ids of all industries that you want to be your defaults.


Add a Default Guideline

/guidelines/destroy/abc123abc123 is the id of the guideline that you want to remove from your default guidelines.


Set Default Guidelines

/guidelines/set_all?ids=abc123,def456ids=abc123,def456 are the ids of all guidelines that you want to be your defaults.


List Current Jobs

Jobs that have not yet been submitted by our writers.

/jobs

Param
Description
Example
Encoded
search_terms (optional)
Search across topics and details.
page (optional)
For when you have lots of jobs. Defaults to 1.
per_page (optional)
How many jobs per page? Defaults to 30.
sandbox (optional)
Real or sandboxed jobs?

Example Request


Example Response

{"total":2,"page":1,"jobs":[
  { "id":"abc123",
    "topic":"My First Job on  Scripted!",
    "count":1,
    "format_id":"ghi789",
    "state":"Claimed",
    "created_at":"2014-03-13T00:30:00Z",
    "deadline_at":"2014-03-20T00:30:00Z" },
  { "id":"def456",
    "topic":"My second job on Scripted",
    "count":25,
    "format_id":"ghi789",
    "state":"Unclaimed",
    "created_at":"2014-03-15T00:30:00Z",
    "deadline_at":"2014-03-22T00:30:00Z" }
]}

List Finished Jobs

Jobs that have been submitted by our writers for your approval (or edits).

/finished_jobs

Param
Description
Example
Encoded
search_terms (optional)
Search across topics and details.
needs_review (optional)
Only list jobs that need your review.
needs_final_review (optional)
Only list rewrites that need your review.
page (optional)
For when you have lots of finished jobs. Defaults to 1.
per_page (optional)
How many jobs per page? Defaults to 30.
sandbox (optional)
Real or sandboxed jobs?

Example Request


Example Response

{"total":2,"page":1,"jobs":[
  { "id":"abc123", 
    "topic":"My First Job on  Scripted!",
    "count":1,
    "format_id":"ghi789",
    "document_id":"abc123",
    "state":"Needs Review",
    "created_at":"2014-03-10T00:30:00Z",
    "submitted_at":"2014-03-15T00:30:00Z",
    "deadline_at":"2014-03-15T00:30:00Z",
    "review_deadline_at":"2014-03-18T00:30:00Z",
    "final_review_deadline_at":null },
  { "id":"def456", 
    "topic":"My second job on Scripted",
    "count":25,
    "format_id":"ghi789",
    "document_id":"mno456",
    "state":"Needs Final Review",
    "created_at":"2014-03-10T00:30:00Z",
    "submitted_at":"2014-03-15T00:30:00Z",
    "deadline_at":"2014-03-15T00:30:00Z",
    "review_deadline_at":"2014-03-18T00:30:00Z",
    "final_review_deadline_at":"2014-03-21T00:30:00Z" }
]}

needs_final_review trumps needs_review.

If you pass both as parameters, needs_review will be ignored.


Get a Finished Job’s Content

/finished_jobs/show/abc123abc123 is the id of the job whose content you are pulling. Use List Finished Jobs to find the id.

By default, we’ll return the job’s content as an array of plain text, but you can also specify html.

Example Request

https://scripted.com/finished_jobs/show/abc123?content_format=html&business_id=abc&key=123

Example Response

{ "id":"abc123",
  "topic":"My First Job on Scripted!",
  "count":1,
  "details":"Things to Mention: cats",
  "delivery":"standard",
  "business_id":"123abc",
  "guideline_ids":["def456"],
  "industry_ids":["ghi789"],
  "format_id":"jkl123",
  "document_id":"mno456",
  "form_fields":{"things_to_mention":"cats"},
  "state":"Needs Final Review",
  "sandbox": false,
  "content":["'My first Job on Scripted' is not really a valid topic. Soooo I'm not sure what you want me to write here. But I'll give it a shot, because I'm a Scripted Writer and I rock."],
  "created_at":"2014-03-10T00:30:00Z",
  "submitted_at":"2014-03-15T00:30:00Z",
  "deadline_at":"2014-03-15T00:30:00Z",
  "review_deadline_at":"2014-03-18T00:30:00Z",
  "final_review_deadline_at":"2014-03-21T00:30:00Z",
  "tip":5
}


Review a Finished Job

/finished_jobs/update/abc123abc123 is the id of the job that you want to review. Use List Finished Jobs to find the id.

For every job, you’re entitled to one round of edit requests.

If you want the writer to fix something, send your request with a chief_complaint:

/finished_jobs/update/abc123?chief_complaint=Please+make+this+longer&business_id=abc&key=123

Otherwise, if you’re satisfied, you can let us know by sending accepted=true.

/finished_jobs/update/abc123?accepted=true&business_id=abc&key=123

Optional Params

Description

Type

add_to_favorites (optional)
Add the writer of this job to your pool of favorites.
Boolean

remove_from_favorites (optional)
Remove the writer of this job from your pool of favorites.
Boolean

accuracy (optional)
Does this piece reflect the instructions posted? On a scale of 1 to 5, where:

  • 1 means No! I see no clear correlation to the assignment.
  • 2 means Somewhat, but it's not the direction I wanted.
  • 3 means It's close, but there are a few sections that don't quite fit.
  • 4 means Yes, with a couple minor exceptions.
  • 5 means Yup! This writer nailed it!
Integer

quality (optional)
Is this piece well-written? On a scale of 1 to 5, where:

  • 1 means No! It is totally unintelligible.
  • 2 means No. It is rife with grammatical errors.
  • 3 means It's okay. There are a few sections I'd like to change, though.
  • 4 means Yes, with a couple minor exceptions.
  • 5 means Wow! Billy Shakespeare, is that you!?
Integer

If your writer has already submitted edits, and your job’s state is Needs Final Review, then any request without accepted=true will be interpreted as a rejection.


Simulate Edits Submitted for a Sandboxed Job

/finished_jobs/sandbox_submit_edits/abc123abc123 is the id of the sandboxed finished job for which you want to simulate the writer submitting their edits.

From the Blog: