NAV
shell

Overview

Welcome to the Screendoor API documentation. We welcome any questions, comments, or feedback. Send an email to support@thecitybase.com if you’d like to get in touch.

All of our API endpoints start with https://screendoor.dobt.co/api/.

Authentication

Pagination

curl --include "https://screendoor.dobt.co/api/sites/1/projects?page=5&v=1&api_key=d9763djh1274"

# Example Response
HTTP/1.1 200 OK
Link: <https://screendoor.dobt.co/api/site/1/projects?page=1>; rel="first">,
  <https://screendoor.dobt.co/api/site/1/projects?page=173>; rel="last">,
  <https://screendoor.dobt.co/api/site/1/projects?page=6>; rel="next">,
  <https://screendoor.dobt.co/api/site/1/projects?page=4>; rel="prev">
Total: 4321

We use the Link header for pagination. When multiple pages of a resource exist, you’ll see a header like the one in the example response on the right.

By default, each page will contain up to 25 records, at which point, you’ll need to pass a ?page= parameter in order to retrieve the next page.

You can change the number of records that are returned by adding a ?per_page= parameter. For performance reasons, we limit this number to 100.

Versioning

The current API version is 1.

API Clients

Projects

List a site’s projects

You can see a list of the projects belonging to a specific site.

curl "https://screendoor.dobt.co/api/sites/1/projects?v=1&api_key=d9763djh1274"

# Example Response
[
{
  "id": 1,
  "sequential_id": 1,
  "name": "Hiring by email",
  "slug": "hiring-by-email",
  "description": null,
  "summary": null,
  "specifics": { },
  "visibility": "not_posted",
  "responses_due_at": null,
  "enable_qa": false,
  "questions_due_at": null,
  "require_registration": false,
  "iframe_custom_stylesheet_url": null,
  "iframe_thanks_method": 1,
  "iframe_thanks_custom_message": null,
  "iframe_thanks_redirect_url": null,
  "after_response_page": null,
  "after_response_page_html": null,
  "key_response_field_id": 1,
  "created_at": "2014-05-07T19:19:42.273Z",
  "updated_at": "2014-05-07T19:19:42.273Z",
  "submitted_responses_count": 11,
  "show_respondents": true,
  "show_askers": true,
  "email_responses": 3
}
]

HTTP Request

GET /sites/:site_id/projects

Create a project

Creates a new project.

curl "https://screendoor.dobt.co/api/sites/1/projects?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "name": "Hiring by email",
  "description": "<p>The description can include HTML!</p>"
}
'

# Example Response
{
  "id": 1,
  "sequential_id": 1,
  "name": "Hiring by email",
  "slug": "hiring-by-email",
  "description": null,
  "summary": null,
  "specifics": { },
  "visibility": "not_posted",
  "responses_due_at": null,
  "enable_qa": false,
  "questions_due_at": null,
  "require_registration": false,
  "iframe_custom_stylesheet_url": null,
  "iframe_thanks_method": 1,
  "iframe_thanks_custom_message": null,
  "iframe_thanks_redirect_url": null,
  "after_response_page": null,
  "after_response_page_html": null,
  "key_response_field_id": 1,
  "created_at": "2014-05-07T19:19:42.273Z",
  "updated_at": "2014-05-07T19:19:42.273Z",
  "submitted_responses_count": 11,
  "show_respondents": true,
  "show_askers": true,
  "email_responses": 3
}

HTTP Request

POST /sites/:site_id/projects

Retrieve a single project

Retrieves the details of a specified project.

curl "https://screendoor.dobt.co/api/sites/1/projects/1?v=1&api_key=d9763djh1274"

# Example Response
{
  "id": 1,
  "sequential_id": 1,
  "name": "Hiring by email",
  "slug": "hiring-by-email",
  "description": null,
  "summary": null,
  "specifics": { },
  "visibility": "not_posted",
  "responses_due_at": null,
  "enable_qa": false,
  "questions_due_at": null,
  "require_registration": false,
  "iframe_custom_stylesheet_url": null,
  "iframe_thanks_method": 1,
  "iframe_thanks_custom_message": null,
  "iframe_thanks_redirect_url": null,
  "after_response_page": null,
  "after_response_page_html": null,
  "key_response_field_id": 1,
  "created_at": "2014-05-07T19:19:42.273Z",
  "updated_at": "2014-05-07T19:19:42.273Z",
  "submitted_responses_count": 11,
  "show_respondents": true,
  "show_askers": true,
  "email_responses": 3
}

HTTP Request

GET /sites/:site_id/projects/:project_id

Update a project

Updates the specified project by assigning values to the keys of the Project hash. The values of any keys you do not provide will be left unchanged.

curl "https://screendoor.dobt.co/api/sites/1/projects/1?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "name": "Hiring by email",
  "description": "<p>The description can include HTML!</p>"
}
'

# Example Response
{
  "id": 1,
  "sequential_id": 1,
  "name": "Hiring by email",
  "slug": "hiring-by-email",
  "description": null,
  "summary": null,
  "specifics": { },
  "visibility": "not_posted",
  "responses_due_at": null,
  "enable_qa": false,
  "questions_due_at": null,
  "require_registration": false,
  "iframe_custom_stylesheet_url": null,
  "iframe_thanks_method": 1,
  "iframe_thanks_custom_message": null,
  "iframe_thanks_redirect_url": null,
  "after_response_page": null,
  "after_response_page_html": null,
  "key_response_field_id": 1,
  "created_at": "2014-05-07T19:19:42.273Z",
  "updated_at": "2014-05-07T19:19:42.273Z",
  "submitted_responses_count": 11,
  "show_respondents": true,
  "show_askers": true,
  "email_responses": 3
}

HTTP Request

PUT /sites/:site_id/projects/:project_id

Delete a project

Deletes a project.

curl "https://screendoor.dobt.co/api/sites/1/projects/1?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /sites/:site_id/projects/:project_id

Project forms

List a project’s forms

You can see a list of the forms belonging to a specific project.

curl "https://screendoor.dobt.co/api/projects/2/forms?v=1&api_key=d9763djh1274"

# Example Response
{
  [
    {
      "id": "1",
      "field_data": [
        {
          "id": "ak01k23k",
          "type": "field",
          "field_type": "paragraph",
          "label": "Your Strategy"
        }
      ],
      "name": "My First Form",
      "description": "The initial form for my project."
    },
    {
      "id": "2",
      "field_data": [
        {
          "id": "b00urns",
          "type": "field",
          "field_type": "number",
          "label": "Your Numbers"
        }
      ],
      "name": "My Second Form",
      "description": "Another form for my project."
    }
  ]
}

Retrieve a single form

Returns a specific form by id for the given project_id.

curl "https://screendoor.dobt.co/api/projects/2/forms/1?v=1&api_key=d9763djh1274"

# Example Response
{
  "id": "1",
    "field_data": [
      {
        "id": "ak01k23k",
        "type": "field",
        "field_type": "paragraph",
        "label": "Your Strategy"
      }
    ],
  "name": "My First Form",
  "description": "The initial form for my project."
}

HTTP Request

GET /projects/:project_id/forms/:id

Update a form

Updates the specified form id belonging to the given project_id.

curl "https://screendoor.dobt.co/api/projects/2/forms/1?v=1&api_key=d9763djh1274" \
  -X PUT \
  -d field_data='[
{
  "id": "ak01k23k",
  "type": "field",
  "field_type": "text",
  "label": "Your Strategy"
}
]'

# Example Response
{
  "id": "1",
    "field_data": [
      {
        "id": "ak01k23k",
        "type": "field",
        "field_type": "paragraph",
        "label": "Your Strategy"
      }
    ],
  "name": "My First Form",
  "description": "The initial form for my project."
}

HTTP Request

PUT /projects/:project_id/form

Options

Parameter Type Default Description
field_data JSON-encoded Array Sorry, the form schema is not yet documented.

Add a field to the initial form

Adds a single field to the project’s initial form. You can manually specify an id in the field_data hash, or you can leave it blank to have one created for you.

curl "https://screendoor.dobt.co/api/projects/2/form/fields?v=0&api_key=d9763djh1274" \
  -X POST \
  -d position=0 \
  -d field_data='
{
  "type": "field",
  "field_type": "text",
  "label": "Your Strategy"
}'

# Example Response
{
  "id": "1",
    "field_data": [
      {
        "id": "ak01k23k",
        "type": "field",
        "field_type": "paragraph",
        "label": "Your Strategy"
      }
    ],
  "name": "My First Form",
  "description": "The initial form for my project."
}

HTTP Request

POST /projects/:project_id/form/fields

Options

Parameter Type Default Description
field_data JSON-encoded Hash Sorry, the form schema is not yet documented.
position Integer The zero-indexed position where this field should be inserted in the form. By default, it will be inserted as the last field in the form.

Update a field in the initial form

Updates a single field in the project’s initial form.

curl "https://screendoor.dobt.co/api/projects/2/form/fields/ak01k23k?v=0&api_key=d9763djh1274" \
  -X PUT \
  -d field_data='
{
  "type": "field",
  "field_type": "text",
  "label": "Your Strategy"
}'

# Example Response
{
  "id": "1",
    "field_data": [
      {
        "id": "ak01k23k",
        "type": "field",
        "field_type": "paragraph",
        "label": "Your Strategy"
      }
    ],
  "name": "My First Form",
  "description": "The initial form for my project."
}

HTTP Request

PUT /projects/:project_id/form/fields/:id

Options

Parameter Type Default Description
field_data JSON-encoded Hash Sorry, the form schema is not yet documented.

Delete a field from the initial form

Deletes a single field from the project’s initial form.

curl "https://screendoor.dobt.co/api/projects/2/form/fields/ak01k23k?v=0&api_key=d9763djh1274" \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /projects/:project_id/form/fields/:id

Project statuses

List a project’s statuses

Returns a list of statuses belonging to a specified project.

curl "https://screendoor.dobt.co/api/projects/2/statuses?v=1&api_key=d9763djh1274"

# Example Response
[
{
  "name": "Open",
  "responses_count": 10
}
]

HTTP Request

GET /projects/:project_id/statuses

Create a status

Creates a status for the specified project.

curl "https://screendoor.dobt.co/api/projects/2/statuses?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "name": "Open"
}
'

# Example Response
{
  "name": "Open",
  "responses_count": 10
}

HTTP Request

POST /projects/:project_id/statuses

Options

Parameter Type Default Description
name string

Retrieve a single status

Retrieves a status by name.

curl "https://screendoor.dobt.co/api/projects/2/statuses/Open?v=1&api_key=d9763djh1274"

# Example Response
{
  "name": "Open",
  "responses_count": 10
}

HTTP Request

GET /projects/:project_id/statuses/:name

Update a status

Updates the specified status.

curl "https://screendoor.dobt.co/api/projects/2/statuses/ThisIsAStatusName?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "name": "Open"
}
'

# Example Response
{
  "name": "Open",
  "responses_count": 10
}

HTTP Request

PUT /projects/:project_id/statuses/:name

Reorder statuses

Sets a new sort order for a project’s statuses.

curl "https://screendoor.dobt.co/api/projects/2/statuses/reorder?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "names": ["Open", "Archived"]
}
'

# Example Response
[
{
  "name": "Open",
  "responses_count": 10
},
{
  "name": "Archived",
  "responses_count": 0
}
]

HTTP Request

POST /projects/:project_id/statuses/reorder

Delete a status

Deletes a status by name. Will return a 400 Bad Request if you try to delete the only status for a project.

curl "https://screendoor.dobt.co/api/projects/2/statuses/Open?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /projects/:project_id/statuses/:name

Project labels

List a project’s labels

Returns a list of labels belonging to a specified project.

curl "https://screendoor.dobt.co/api/projects/2/labels?v=1&api_key=d9763djh1274"

# Example Response
[
{
  "name": "Missing info",
  "color": "464b6d",
  "responses_count": 2
}
]

HTTP Request

GET /projects/:project_id/labels

Create a label

Creates a label for the specified project.

curl "https://screendoor.dobt.co/api/projects/2/labels?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "name": "Missing info",
  "color": "464b6d"
}
'

# Example Response
{
  "name": "Missing info",
  "color": "464b6d",
  "responses_count": 2
}

HTTP Request

POST /projects/:project_id/labels

Options

Parameter Type Default Description
name string
color string Randomly chosen A 6-digit hex color code

Retrieve a single label

Retrieves a label by name.

curl "https://screendoor.dobt.co/api/projects/2/labels/Missing%20info?v=1&api_key=d9763djh1274"

# Example Response
{
  "name": "Missing info",
  "color": "464b6d",
  "responses_count": 2
}

HTTP Request

GET /projects/:project_id/labels/:name

Update a label

Updates the specified label.

curl "https://screendoor.dobt.co/api/projects/2/labels/ThisIsALabelName?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "name": "Missing info"
}
'

# Example Response
{
  "name": "Missing info",
  "color": "464b6d",
  "responses_count": 2
}

HTTP Request

PUT /projects/:project_id/labels/:name

Delete a label

Deletes a label by name.

curl "https://screendoor.dobt.co/api/projects/2/labels/Missing%20info?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /projects/:project_id/labels/:name

Responses

List a project’s responses

Returns a list of responses to a specified project. Note that in order to retrieve the assignees or archived_responses keys in the returned data, you’ll need to use the single response endpoint.

curl "https://screendoor.dobt.co/api/projects/2/responses?v=1&api_key=d9763djh1274"

# Example Response
[
{
  "id": 3,
  "sequential_id": 3,
  "project_id": 2,
  "form_id": 1,
  "initial_form_id": null,
  "pretty_id": "ykylz0kz293b",
  "submitted_at": "2014-05-07T19:19:43.230Z",
  "responses": {
      "1": "Vivian Cronin",
      "2": "emmanuelle@goyette.co.uk",
      "3": "New application for your job on Startuply",
      "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n",
      "5": "3"
  },
  "rating_aggregates": {},
  "average_rating": null,
  "num_ratings": 0,
  "created_at": "2014-05-07T19:19:43.280Z",
  "updated_at": "2014-05-07T19:20:51.485Z",
  "status": "Starred",
  "labels": [],
  "user": null,
  "submission_source": {
    "type": "frontend",
    "hostname": "forms.fm"
  }
}
]

HTTP Request

GET /projects/:project_id/responses

Query Parameters

Parameter Default Description
sort "id" One of "id", "submitted_at", "responses_updated_at", "status", "has_signature", "num_ratings", "responder", "responder_email", "assigned", "average_rating", "edit_status"
direction "asc" Either "asc" or "desc"
trash false Set this to true to view responses that are in the trash.

In addition to the parameters above, this endpoint accepts the same query parameters as Screendoor’s responses page.

To find the correct parameters, consider using advanced search to construct a query. Then copy the ?advanced_search= part of the resulting URL.

(Since API keys aren’t associated with individual users, you will not be able to use query parameters that refer to “my rating.”)

Response Data

See Retrieve a single response

Create a response

Creates a response to the specified project’s initial form.

curl "https://screendoor.dobt.co/api/projects/2/responses?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "response_fields": {
    "1": "Vivian Cronin",
    "2": "emmanuelle@goyette.co.uk",
    "3": "New application for your job on Startuply",
    "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n"
  },
  "skip_email_confirmation": true,
  "skip_notifications": true,
  "skip_validation": true,
  "status": "Starred",
  "labels": ["Great", "Needs more information"]
}
'

# Example Response
{
  "id": 3,
  "sequential_id": 3,
  "project_id": 2,
  "form_id": 1,
  "initial_form_id": null,
  "pretty_id": "ykylz0kz293b",
  "submitted_at": "2014-05-07T19:19:43.230Z",
  "responses": {
      "1": "Vivian Cronin",
      "2": "emmanuelle@goyette.co.uk",
      "3": "New application for your job on Startuply",
      "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n",
      "5": "3"
  },
  "rating_aggregates": {},
  "average_rating": null,
  "num_ratings": 0,
  "created_at": "2014-05-07T19:19:43.280Z",
  "updated_at": "2014-05-07T19:20:51.485Z",
  "status": "Starred",
  "labels": [],
  "user": null,
  "submission_source": {
    "type": "frontend",
    "hostname": "forms.fm"
  }
}

HTTP Request

POST /projects/:project_id/responses

Options

Parameter Type Default Description
response_fields hash {} See the spec below
skip_email_confirmation boolean false If false, the respondent receives an email confirming submission of the response.
skip_notifications boolean false If false, administrators receive notification that the response was submitted.
skip_validation boolean false If false, validation errors are raised if the response is invalid.
status string set inside Screendoor The only possible values are statutes set within the Screendoor project.
labels array [] Possible values in the array: label names already used in the project and new labels names.

Retrieve a single response

Retrieves a response with the given :response_id.

curl "https://screendoor.dobt.co/api/projects/2/responses/3?v=1&api_key=d9763djh1274"

# Example Response
{
  "id": 3,
  "sequential_id": 3,
  "project_id": 2,
  "form_id": 1,
  "initial_form_id": null,
  "pretty_id": "ykylz0kz293b",
  "submitted_at": "2014-05-07T19:19:43.230Z",
  "responses": {
      "1": "Vivian Cronin",
      "2": "emmanuelle@goyette.co.uk",
      "3": "New application for your job on Startuply",
      "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n",
      "5": "3"
  },
  "rating_aggregates": {},
  "average_rating": null,
  "num_ratings": 0,
  "created_at": "2014-05-07T19:19:43.280Z",
  "updated_at": "2014-05-07T19:20:51.485Z",
  "status": "Starred",
  "labels": [],
  "user": null,
  "submission_source": {
    "type": "frontend",
    "hostname": "forms.fm"
  },
  "archived_responses": [
    {
      "id": 4,
      "responses_updated_at": "2014-05-07T19:19:43.230Z",
      "responses": { }
    }
  ],
  "assignees": [
    {
      "type": "User",
      "id": 10,
      "name": "Richard Ayoade"
    },
    {
      "type": "ProjectTeam",
      "id": 93,
      "name": "HR"
    }
  ]
}

HTTP Request

GET /projects/:project_id/responses/:response_id

Query Parameters

Parameter Default Description
response_format raw raw, text, or html

Response Data

The submission_source field contains information on where the response was submitted from. submission.type will be one of the following:

submission.hostname will be one of the following:

Update a response

Updates the specified response.

curl "https://screendoor.dobt.co/api/projects/2/responses/2?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "response_fields": {
    "1": "Veronica Cronin",
    "2": "emmanuelle@goyette.co.uk"
  },
  "status": "Accepted"
}
'

# Example Response
{
  "id": 3,
  "sequential_id": 3,
  "project_id": 2,
  "form_id": 1,
  "initial_form_id": null,
  "pretty_id": "ykylz0kz293b",
  "submitted_at": "2014-05-07T19:19:43.230Z",
  "responses": {
      "1": "Vivian Cronin",
      "2": "emmanuelle@goyette.co.uk",
      "3": "New application for your job on Startuply",
      "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n",
      "5": "3"
  },
  "rating_aggregates": {},
  "average_rating": null,
  "num_ratings": 0,
  "created_at": "2014-05-07T19:19:43.280Z",
  "updated_at": "2014-05-07T19:20:51.485Z",
  "status": "Starred",
  "labels": [],
  "user": null,
  "submission_source": {
    "type": "frontend",
    "hostname": "forms.fm"
  }
}

HTTP Request

PUT /projects/:project_id/responses/:response_id

Options

Parameter Type Default Description
response_fields hash {} See the spec below
force_validation boolean false If false, validations errors are raised if the response is invalid.
status string set inside Screendoor The only possible values are statutes set within the Screendoor project.
labels array [] Possible values in the array: label names already used in the project and new label names.

Delete a response

Moves the response with the given :response_id to the trash.

curl "https://screendoor.dobt.co/api/projects/2/responses/3?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /projects/:project_id/responses/:response_id

Recover a response

Recovers the response with the given :response_id from the trash.

curl "https://screendoor.dobt.co/api/projects/2/responses/3/recover?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST

# Example Response
{
  "id": 3,
  "sequential_id": 3,
  "project_id": 2,
  "form_id": 1,
  "initial_form_id": null,
  "pretty_id": "ykylz0kz293b",
  "submitted_at": "2014-05-07T19:19:43.230Z",
  "responses": {
      "1": "Vivian Cronin",
      "2": "emmanuelle@goyette.co.uk",
      "3": "New application for your job on Startuply",
      "4": "To Whom it May Concern: I am very interested in working at your company. The widgets you make are AMAZING, and I would love to be a part of it. I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly. Plus, I even know what to do with the options we did not select. Adding me to your team means saving time, saving money and getting back to doing the work you love doing.\n",
      "5": "3"
  },
  "rating_aggregates": {},
  "average_rating": null,
  "num_ratings": 0,
  "created_at": "2014-05-07T19:19:43.280Z",
  "updated_at": "2014-05-07T19:20:51.485Z",
  "status": "Starred",
  "labels": [],
  "user": null,
  "submission_source": {
    "type": "frontend",
    "hostname": "forms.fm"
  }
}

HTTP Request

POST /projects/:project_id/responses/:response_id/recover

Permanently destroy a response

Delete a response forever, skipping the trash.

curl "https://screendoor.dobt.co/api/projects/2/responses/3/delete_forever?v=1&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /projects/:project_id/responses/:response_id/delete_forever

Spec for the response hash

In order to encode a response to a Screendoor form, you must use the format defined below. In each key-value pair, the key is the ID of your response field, and the value depends on the type of that field. (You can find the ID of a response field in Screendoor’s form builder, at the bottom of the “Edit field” pane.) See an example of a complete payload above.

Field type Format
Text "foo"
Paragraph "I have many skills, but the most important ones are my abilities to collect information from people, screen it effectively, select the right options, and follow through with the right options quickly."
Choose Many (Checkboxes) { "checked": ["Choice #1", "Choice #2"], "other_checked": true, "other_text": "foobar!" }
Choose One (Radio) { "checked": ["Choice #1"], "other_checked": true, "other_text": "foobar!" }
Confirm true
Dropdown "Choice #2"
Date { "month": "2", "day": "15", "year": "2015"}
Time { "am_pm": "PM", "hours": "6", "minutes": "01", "seconds": "30"}
Phone "4151234567"
Email "foo@bar.com"
Address { "country": "US", "street": "123 Main St.", "city": "Pleasantville", "state": "Illinois" }
Table { "column one": ["row 1", "row 2"], "column two": ["row 1", "row 2"] }
Numeric "123.45"
Website "http://www.google.com"
Price { "dollars": "12", "cents": "99" }
File [{ "id": "b42Unp-Oj_qeyCWNDaTBXr8nygNq5x4-" }, { "id": "another_file_id" }]

To get this ID, first upload a file using the endpoint described below.
Map Marker [40.7700118", -73.9800453]

Uploading files

In order to include a file in the response fields hash, you must first upload it using the following endpoint.

curl "https://screendoor.dobt.co/api/form_renderer/file?v=1&response_field_id=123" \
  -X POST \
  -F "file=@/path/to/file"

# Example Response
{
  "ok":true,
  "file_id":"b42Unp-Oj_qeyCWNDaTBXr8nygNq5x4-"
}

Response labels

List a responses’ labels

Returns a list of labels belonging to a specified project.

curl "https://screendoor.dobt.co/api/responses/3/labels?v=0&api_key=d9763djh1274"

# Example Response
[
{
  "name": "Missing info",
  "color": "464b6d"
}
]

HTTP Request

GET /responses/:response_id/labels

Add one or more labels to a response

The labels must already exist inside the project.

curl "https://screendoor.dobt.co/api/responses/3/labels?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "labels": ["Missing info", "Top quality"]
}
'

# Example Response
[
  {
    "name": "Missing info",
    "color": "464b6d"
  },
  {
    "name": "Top quality",
    "color": "464b6d"
  }
]

HTTP Request

POST /responses/:response_id/labels

Remove a label from a response

Removes a label from a response by name. If the response does not have that label applied, a 404 will be returned.

curl "https://screendoor.dobt.co/api/responses/3/labels/Missing%20info?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /responses/:response_id/labels/:name

Replace labels for a response

The labels must already exist inside the project.

curl "https://screendoor.dobt.co/api/responses/3/labels?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "labels": ["Missing info"]
}
'

# Example Response
[
{
  "name": "Missing info",
  "color": "464b6d"
}
]

HTTP Request

PUT /responses/:response_id/labels

Remove all labels from a response

Removes all labels from a response.

curl "https://screendoor.dobt.co/api/responses/3/labels?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /responses/:response_id/labels

Response assignments

A response can be assigned to many teams and/or users. An “assignment parameter” takes the format of :type,:id, where type is either ProjectTeam or User, and id is the identifier for that record.

For example, to reference User #9, we would use the parameter User,9.

List a responses’ assignments

Returns a list of assignees for the specified response.

curl "https://screendoor.dobt.co/api/responses/3/assignees?v=0&api_key=d9763djh1274"

# Example Response
[
{
  "type": "ProjectTeam",
  "id": "9",
  "name": "HR Monitors"
}
,
{
  "type": "User",
  "id": "4",
  "name": "Richard Ayoade"
}
]

HTTP Request

GET /responses/:response_id/assignments

Add one or more assignees to a response

The teams and/or users must already exist inside of the project.

curl "https://screendoor.dobt.co/api/responses/3/assignments?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "assignees": ["ProjectTeam,9", "User,4"]
}
'

# Example Response
[
{
  "type": "ProjectTeam",
  "id": "9",
  "name": "HR Monitors"
}
,
{
  "type": "User",
  "id": "4",
  "name": "Richard Ayoade"
}
]

HTTP Request

POST /responses/:response_id/assignments

Remove an assignment from a response

Removes an assignment from a response by the “assignment parameter.” If the response does not have that user or team assigned, a 404 will be returned.

curl "https://screendoor.dobt.co/api/responses/3/assignments/ProjectTeam,9?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /responses/:response_id/assignments/:assignment_parameter

Replace assignments for a response

The teams and/or users must already exist inside of the project.

curl "https://screendoor.dobt.co/api/responses/3/assignments?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "assignees": ["ProjectTeam,9"]
}
'

# Example Response
[
{
  "type": "ProjectTeam",
  "id": "9",
  "name": "HR Monitors"
}
]

HTTP Request

PUT /responses/:response_id/assignments

Remove all assignments from a response

Removes all assignments from a response.

curl "https://screendoor.dobt.co/api/responses/3/assignments?v=0&api_key=d9763djh1274" \
  -H 'Content-Type: application/json' \
  -X DELETE

# Example Response
Status: 204 No Content

HTTP Request

DELETE /responses/:response_id/assignments

shell