Contacts
========


Find a person
-------------

:title:
	optional: title of the person e.g. Dr, Ms, Mrs, case sensitive
:first_name:
	optional. case sensitive
:last_name:
	optional. case sensitive
:email:
	optional: valid email address, case insensitive
:date_of_birth:
	optional: any reasonable date format but YYYY-MM-DD recommended
:postal_code:
	optional: postcode / zip code, case sensitive
:take_first_if_multiple:
	optional: as it suggests - if multiple matches are returned take the first (order undefined)

Matching rules:
	1. by email
	2. by first name, last name and date of birth
	3. by first name, last name and postcode
	4. by title, last name and postcode

.. code-block:: http

	$ http https://api.sheepcrm.com/api/v1/$FLOCK/find/person/ email==james@example.com "Authorization: Bearer $API_KEY"

	$ http https://api.sheepcrm.com/api/v1/$FLOCK/find/person/ first_name==James last_name==Webster postal_code=='NR28 8FL' "Authorization: Bearer $API_KEY"


Find an organisation
--------------------

:name:
	optional. case sensitive
:email:
	optional: valid email address, case insensitive
:postal_code:
	optional: postcode / zip code, case sensitive
:domain:
	optional: website domain (no http etc)
:take_first_if_multiple:
	optional: as it suggests - if multiple matches are returned take the first (order undefined)

Matching rules:
    1. by name and postcode
    2. by exact name
    3. by email
    4. by domain

.. code-block:: http

	$ http https://api.sheepcrm.com/api/v1/$FLOCK/find/organisation/ name=='Authentic Digital Ltd' "Authorization: Bearer $API_KEY"


Summary profile data
--------------------

*POLICY*: `person.summary` / `organisation.summary`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/summary "Authorization: Bearer $API_KEY"


Personal details for a person
-----------------------------

*POLICY*: `person.personal`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/person/{uid}/personal/detail "Authorization: Bearer $API_KEY"


Communications for a person
---------------------------

This communications call returns profile data about the contact concerning how to communicate with them. i.e. email, postal address etc

*POLICY*: `person.communications`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/person/{uid}/communications/detail "Authorization: Bearer $API_KEY"



Badges
------

*POLICY*: `badge.summary`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/badges/summary "Authorization: Bearer $API_KEY"

*POLICY*: `badge.detail`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/badges/detail "Authorization: Bearer $API_KEY"


Evidence records
----------------

*POLICY*: `evidence.summary`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/evidence/summary "Authorization: Bearer $API_KEY"

*POLICY*: `evidence.detail`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/evidence/detail "Authorization: Bearer $API_KEY"


Privacy / GDPR
--------------

*POLICY*: `gdpr`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/gdpr/all "Authorization: Bearer $API_KEY"

	{
	    "consents": [
	        {
	            ...
	        }
	    ],
	    "contact_uri": "/{bucket}/{organisation|person}/{uid}/",
	    "contract": [
	        {
	            ...
	        }
	    ],
	    "legitimate_interests": [
	        {
	            ...
	        }
	    ]
	}

Membership
----------

*POLICY*: `membership`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/membership/summary "Authorization: Bearer $API_KEY"

*POLICY*: `membership.all`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/membership/all "Authorization: Bearer $API_KEY"


Get all the connections for a contact
-------------------------------------

:limit:
	return first N connections
:connection_type:
	return on connections of a specified type
:hidden:
	include hidden connections (Y/N); hidden connections are not included by default


.. code-block:: http

	$ http https://api.sheepcrm.com/api/v1/$FLOCK/connections/ "Authorization: Bearer $API_KEY" uri=={UID}
	HTTP/1.0 200 OK

	{
	    "connections": [
	        {
	            "automatic": null,
	            "bidirectional": null,
	            "connection_note": null,
	            "connection_type": null,
	            "destination": "/example/person/5aafb4de0490573922b9da91/",
	            "end_date": null,
	            "hidden": false,
	            "label": "contact",
	            "sort_order": 1000,
	            "source": "/example/organisation/5a57701704905781f28622ac/",
	            "start_date": "2019-08-20T12:30:42.523000"
	        },
	        ...
	{

Adding connections to a contact
-------------------------------

:source:
	*required* - the 'from' or `source` of the connection

:destination:
	*required* - the 'to' or `destination` of the connection

:label:
	recommended - a descriptive label for the connection

:connection_note:
	optional - free text note to explain the connection or to record background information

:start_date:
	optional - start date for the connection

:end_date:
	optional - end date for the connection

:bidirectional:
    optional - create a 2nd connection with the source and destination swapped (default is False)

.. code-block:: http

	$ http https://api.sheepcrm.com/api/v1/$FLOCK/connections/ "Authorization: Bearer $API_KEY" source=/example/organisation/5fa523e480859e33dc285c86/ destination=/example/person/5c02fb8b601d090e125020de/ label=friends

	HTTP/1.0 200 OK
	{
    	"connection_obj": null,
    	"connection_uri": "/example/connection/61800b989d13abcb30ba91e4/",
    	"status": "created"
	}

Forms
-----

Retrieve form responses for a single contact


*POLICY*: `form.summary`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/form/summary "Authorization: Bearer $API_KEY"

*POLICY*: `form.detail`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/form/detail "Authorization: Bearer $API_KEY"

Invoices
--------

Retrieve invoices for a single contact

.. note::

    Invoices use the `quote` resource so the permissions are names `quote.X` not `invoice.X`


*POLICY*: `quote.summary`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/invoices/summary "Authorization: Bearer $API_KEY"

*POLICY*: `quote.detail`

.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/invoices/detail "Authorization: Bearer $API_KEY"

Finding duplicates
------------------

Duplicate records represent data quality degradation and when health and emergency contact information duplicate records can be a serious problem. This API call looks across a range of fields for similar records and suggests them for a human to decide if a merge is required.

:limit:
	optional - maximum number of results returned - default is 20

:threshold:
    optional - minimum match score - default is zero


.. code-block:: http

	http https://sls-api.sheepcrm.com/api/v2/{bucket}/{organisation|person}/{uid}/duplicates/ "Authorization: Bearer $API_KEY"


	HTTP/1.1 200 OK
	{
	    "duplicates": [
	        {
	            "display_value": "Mr David Example",
	            "notes": [
	                "match on first_name (david -> david) +10",
	                "match on last_name (example -> example) +10",
	                "match on locality (sheffield -> sheffield) +15",
	                "match on region (southyorkshire -> southyorkshire) +10",
	                "match on primary_telephone (07701473459 -> 07701473459) +40",
	                "match on postal_code (s791fx -> s791fx) +25"
	            ],
	            "similarity": 110,
	            "summary": "based on primary telephone",
	            "uri": "/example/person/5967467f0490573d302b44f4/"
	        }
	    ]
	}

Merging duplicates
------------------

When two records have been identified as duplicates they can be queued for merging. Fields and linked records associated with the `duplicate` will be merged into the `original` record. Field merging uses an 'under-write' policy: if the field is missing on the original it is added, if it is present on the original the field is not changed. A journal entry will be added to the original record listing the fields and linked records which have been modified. If the merge is successful the duplicate record will be deleted.

A merge may cause hundreds of records to be moved or modified, this is processed by a background task and cannot be automatically undone (It isn't quite as hard as un-stirring milk from coffee but it is close...).

.. code-block:: http

	http PUT https://api.sheepcrm.com/api/v1/{bucket}/{organisation|person}/merge/{duplicate uid}/into/{original uid} "Authorization: Bearer $API_KEY"


	HTTP/1.1 200 OK
	{
	    'message': 'Dupe queued'
	}