Forms

View all forms for a user

http GET https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/

HTTP/1.1 200 OK
{
    "form_responses": [
        {
            "contact_ref": "/example/person/5e983d3f49c3a815ef7521fc/",
            "form_ref": "/example/sheep_form/5f916fc6f18daf30f45c3844/",
            "created": "2021-02-03T16:07:53.787000",
            "legacy_uid": null,
            "overall_feedback": null,
            "overall_internal_comments": null,
            "response": null,
            "score": null,
            "section_feedback": null,
            "section_internal_comments": null,
            "status": "started",
            "submission_date": null,
            "tags": [],
            "uid": "example-form_response-601ac8ced901ce5f06280a1f",
            "uri": "/example/form_response/601ac8ced901ce5f06280a1f/"
        }
    ],
    "person_uri": "/example/person/5e983d3f49c3a815ef7521fc/"
}

Start a form response

Logged-in self-service user required.

Parameter	Required	Description
sheep_form	Yes	Sheep form URI

http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/ sheep_form=/example/sheep_form/5f916fc6f18daf30f45c3844/ "Authorization: Bearer $APP_API_KEY"

HTTP/1.1 201 Created
{
    "person_uri": "/example/person/5e983d3f49c3a815ef7521fc/",
    "uid": "example-form_response-601aca59d901ce602fa2b594",
    "uri": "/example/form_response/601aca59d901ce602fa2b594/"
}

Read a form response

Logged-in self-service user required.

http GET https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/{form_response_uid} "Authorization: Bearer $APP_API_KEY"

HTTP/1.0 200 OK
{
    "contact_ref": "/example/person/5e983d3f49c3a815ef7521fc/",
    "form_ref": "/example/sheep_form/5f916fc6f18daf30f45c3844/",
    "form_response": "/example/form_response/601aca59d901ce602fa2b594/",
    "legacy_uid": null,
    "overall_feedback": null,
    "overall_internal_comments": null,
    "response": {
        "about_you.title": "Ms",
        "about_you.first_name": "Sally",
        "feedback.value": "5"
    },
    "score": null,
    "section_feedback": null,
    "section_internal_comments": null,
    "status": "started",
    "submission_date": null,
    "tags": []
}

Update a form response

Parameter	Required	Description
question	Yes (unless using answers)	A fully qualified form question: section_reference.question_ref
answer	Yes (unless using answers)	The answer to the question
answers	Yes (unless using question/answer)	A dictionary of question-answer pairs
skip_validation	No	If true the question will not be validated against the form

http PUT https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/{form_response_uid} "Authorization: Bearer $APP_API_KEY" question=feedback.value answer=3

HTTP/1.0 200 OK
{
    "contact_ref": "/example/person/5e983d3f49c3a815ef7521fc/",
    "form_ref": "/example/sheep_form/5f916fc6f18daf30f45c3844/",
    "form_response": "/example/form_response/601aca59d901ce602fa2b594/",
    "response": {
        "about_you.title": "Ms",
        "about_you.first_name": "Sally",
        "feedback.value": "3"
    },
    "status": "started",
    "submission_date": null,
    "tags": []
}

Question failing validation

http PUT https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/{form_response_uid} "Authorization: Bearer $APP_API_KEY" question=not-a-question answer=3

HTTP/1.0 400 Bad Request
{
    "error": "question `not-a-question` is not part of form /example/sheep_form/5f916fc6f18daf30f45c3844/"
}

Bypass question validation

http PUT https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/{form_response_uid} "Authorization: Bearer $APP_API_KEY" question=not-a-question answer=3 skip_validation=True

HTTP/1.0 200 OK
{
    "response": {
        "about_you.title": "Ms",
        "about_you.first_name": "Sally",
        "feedback.value": "3",
        "not-a-question": "3"
    },
    "status": "started"
}

Request a form be returned

When a form is submitted it can no longer be edited by the user. The form may enter a workflow for review, approval, and scoring.

• If the form status is submitted, the status will automatically be reset to started.
• For any other status, a tag will be added to the response and a sheep_event is triggered.
• The client can connect actions to the form_return_requested trigger (e.g. a reminder created, email sent).
• Any workflow or communication with the applicant is for the client to decide.

The response will return the form response with an extra field return_status which will be requested or succeeded.

http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/{form_response_uid}/request_return/ "Authorization: Bearer $APP_API_KEY" reason="I messed up question 3 and would like to change my answer."

HTTP/1.0 200 OK
{
    "contact_ref": "/example/person/5e983d3f49c3a815ef7521fc/",
    "form_ref": "/example/sheep_form/5f916fc6f18daf30f45c3844/",
    "form_response": "/example/form_response/601aca59d901ce602fa2b594/",
    "response": {
        "about_you.title": "Ms",
        "about_you.first_name": "Sally",
        "feedback.value": "5"
    },
    "return_event_uri": "/example/sheep_event/605c7168ccc6f2a974ca6387/",
    "return_status": "requested",
    "return_reason": "I messed up question 3 and would like to change my answer.",
    "score": null,
    "section_feedback": null,
    "section_internal_comments": null,
    "status": "started",
    "submission_date": null,
    "tags": []
}