Forms
=====

View all forms for a user
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

    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



.. code-block:: http

    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.


.. code-block:: http

    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


.. code-block:: http

    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
^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. code-block:: http

	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
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	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`.

.. code-block:: http

    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": [],
	}