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/"
            },
            {
                "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-601aca59d901ce602fa2b594"
                "uri": "/example/form_response/601aca59d901ce602fa2b594/"
            }
        ],
        "person_uri": "/example/person/5e983d3f49c3a815ef7521fc/"
    }

Start a form response

Logged in self-service user required.

type

sheep_form - 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/example-form_response-601aca59d901ce602fa2b594 "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

question

a fully qualified form question. (section reference (.) question ref)

answer

the answer to the question

OR

answers

a dictionary of question answer pairs

skip_validation

optional. if True the question will not be validated against the form

http PUT https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/example-form_response-601aca59d901ce602fa2b594 "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/",
        "legacy_uid": null,
        "overall_feedback": null,
        "overall_internal_comments": null,
        "response": {
            "about_you.title": "Ms"
            "about_you.first_name": "Sally"
            "feedback.value": "3"
        },
        "score": null,
        "section_feedback": null,
        "section_internal_comments": null,
        "status": "started",
        "submission_date": null,
        "tags": []
    }

Question failing validation

http PUT https://api.sheepcrm.com/api/v1/$FLOCK/user/forms/example-form_response-601aca59d901ce602fa2b594 "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/example-form_response-601aca59d901ce602fa2b594 "Authorization: Bearer $APP_API_KEY" question=not-a-question answer=3 skip_validation=True
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": "3",
        "not-a-question": "3",
    },
    "score": null,
    "section_feedback": null,
    "section_internal_comments": null,
    "status": "started",
    "submission_date": null,
    "tags": []
}

Request a form be returned

When a form is submitted it can no longer be edited by the user. The form may enter a complex workflow for review, approval and scoring. Returning a form that is mid-review has consquences which only the client can foresee and permit. If a 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 as this will be different for each client and possibly each form type.

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/example-form_response-601aca59d901ce602fa2b594/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/",
        "legacy_uid": null,
        "overall_feedback": null,
        "overall_internal_comments": null,
        "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": [],
    }