sheepForms

Forms in Sheep are built from a hierarchy: questions at the bottom, which can be grouped into a section, sections are added to a form template, and templates are finally made public inside a sheep form.

To construct a form you must start at the bottom and work up:

1. Define your questions
2. Group questions into sections (you must have at least one)
3. Create the form template
4. Create the Sheep Form that will use the template

Tip

Once questions, sections or templates have been created they can be reused multiple times, so consider carefully how to phrase questions to optimise re-use.

Form Field Types

Field Type	Description
boolean	Yes/no dropdown.
boolean-simple	Renders as checkbox-simple.
boolean-switch	Renders as switch with “yes/no”.
choice	Single choice from a pre-defined list.
choice-from-url	Single choice defined by an API endpoint.
date	Browser date input.
email	Browser email input.
extra-large-text	Textarea.
file	Single file upload.
image	Single file upload.
profile_photo	Single file upload with link to photo guidance.
large-text	Textarea.
multi-choice	Multiple choice from a pre-defined list.
multi-choice-checkbox	Multiple choice from a pre-defined list rendered as checkboxes.
multi-choice-from-url	Multiple choices defined by an API endpoint.
multi-file	Multiple file upload.
multi-select-from-url	Multiple select, defined by an API endpoint.
number	Browser number input.
telephone	Browser text input.
text	Browser text input.
text-list	Multiple text inputs.
time	Browser text input.

Create a New Form

POST https://api.sheepcrm.com/api/v1/$FLOCK/sheep_form/
Authorization: Bearer $API_KEY

Create a new sheep form, a new form template and link them

POST https://api.sheepcrm.com/api/v1/$FLOCK/sheep_form/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"new_form_template": true}

Sections in a Form Template

Add a section

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_template/{ID}/section/
Authorization: Bearer $API_KEY

Remove a section

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_template/{ID}/section/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"section_uri": "/example/form_section/5f904b1dcd59d5157793fb08/"}

Questions in a Form Section

Add a question

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_section/{ID}/question/
Authorization: Bearer $API_KEY

Remove a question

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_section/{ID}/question/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"question_uri": "/example/form_question/5f904b1dcd59d5157793fb08/"}

Form Responses

The Sheep Forms (templates, sections and questions) define the reusable form that a user will complete. The answers a user provides are stored in a form_response. A form response will have a reference to the form it is referring to and the contact that is completing the form.

Response statuses

Status	Description
started	The user is in the process of answering.
submitted	The user has completed and submitted their form. Further user edits are not possible.
withdrawn	The user has asked to withdraw their submission.
accepted	The response has been accepted (e.g. an application to join) or simply closed/complete.
rejected	The response was not accepted.

Status fields are configurable but certain statuses are required to exist. As a form response changes state, Sheep trigger events are created which can be connected through actions to deliver automation (e.g. sending an email when a form moves to accepted).

The standard core API can be used to create, update and delete form responses. Deleting a form response will not delete any associated attachments or score sheets.

Submitting Answers to a Form Response

Parameter	Description
answers	A dictionary of question and answers.
question	Single question (unique, fully qualified name). Use as alternative to answers.
answer	Single answer. Use with question.
skip_validation	Boolean. Default is False. Questions are validated against the form before submitting.

PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/answers/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"answers": {"fully-qualified-question": "my answer"}}

HTTP/1.1 200 OK
{
    "data": {
        "fully-qualified-question": "my answer"
    }
}

Commenting on a Form Response

Parameter	Description
section_uri	Required. The section the comment refers to.
comment	The comment (markdown supported).

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/comment/
Authorization: Bearer $API_KEY

Providing Feedback on a Form Response

Parameter	Description
section_uri	Required. The section the feedback refers to.
feedback	The feedback text (markdown supported).

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/feedback/
Authorization: Bearer $API_KEY

Scoring a Form

Forms can be scored (marked) directly or scored by a separate score sheet. Separate score sheets are only recommended if multiple independent scores are required.

Set the mark/score on the form response directly

Parameter	Description
question	Required. The question the mark or score applies to.
mark	Required. The mark or score (numeric, integer).

PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/mark_question/
Authorization: Bearer $API_KEY

Delete / remove / reset mark for a question

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/mark_question/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"question": "the-question-name"}

Set the mark/score on a score sheet

PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_score/{ID}/mark_question/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"question": "the-question-name", "mark": 8}

Delete / remove / reset mark on a score sheet

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_score/{ID}/mark_question/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"question": "the-question-name"}

Add a scorer to a form

Parameter	Description
user	Required. The scorer.

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/
Authorization: Bearer $API_KEY

Delete a scorer

Parameter	Description
score_sheet	Required. The score sheet to delete.
force	Optional. A score sheet will not be deleted if it has been started by the scorer unless forced.

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/
Authorization: Bearer $API_KEY

Change the scorer

Parameter	Description
user	Required. The scorer.
score_sheet	Required. The score sheet to modify.
force	Optional. A score sheet will not be modified if it has been started by the scorer unless forced.

PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/
Authorization: Bearer $API_KEY

View all the scores for a form response

Get access to all the scores for a form response, their mean and the totals:

GET https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scores/
Authorization: Bearer $API_KEY

Assigning a User to a Form Response

Users can be assigned/pinned to a form response. What the assignment means will depend on the context and wider configuration. User assignments can be used in conjunction with permissions to control access to certain form responses.

Add a user to a form

POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/users/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"user": "/sheepcrm/user/{uid}/"}

Remove a user from a form

DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/users/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"user": "/sheepcrm/user/{uid}/"}