Find a person


optional: title of the person e.g. Dr, Ms, Mrs, case sensitive


optional. case sensitive


optional. case sensitive


optional: valid email address, case insensitive


optional: any reasonable date format but YYYY-MM-DD recommended


optional: postcode / zip code, case sensitive


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

$ http$FLOCK/find/person/ "Authorization: Bearer $API_KEY"

$ http$FLOCK/find/person/ first_name==James last_name==Webster postal_code=='NR28 8FL' "Authorization: Bearer $API_KEY"

Find an organisation


optional. case sensitive


optional: valid email address, case insensitive


optional: postcode / zip code, case sensitive


optional: website domain (no http etc)


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

$ http$FLOCK/find/organisation/ name=='Authentic Digital Ltd' "Authorization: Bearer $API_KEY"

Summary profile data

POLICY: person.summary / organisation.summary

http{bucket}/{organisation|person}/{uid}/summary "Authorization: Bearer $API_KEY"

Personal details for a person

POLICY: person.personal

http{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

http{bucket}/person/{uid}/communications/detail "Authorization: Bearer $API_KEY"


POLICY: badge.summary

http{bucket}/{organisation|person}/{uid}/badges/summary "Authorization: Bearer $API_KEY"

POLICY: badge.detail

http{bucket}/{organisation|person}/{uid}/badges/detail "Authorization: Bearer $API_KEY"

Evidence records

POLICY: evidence.summary

http{bucket}/{organisation|person}/{uid}/evidence/summary "Authorization: Bearer $API_KEY"

POLICY: evidence.detail

http{bucket}/{organisation|person}/{uid}/evidence/detail "Authorization: Bearer $API_KEY"

Privacy / GDPR

POLICY: gdpr

http{bucket}/{organisation|person}/{uid}/gdpr/all "Authorization: Bearer $API_KEY"

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


POLICY: membership

http{bucket}/{organisation|person}/{uid}/membership/summary "Authorization: Bearer $API_KEY"

POLICY: membership.all

http{bucket}/{organisation|person}/{uid}/membership/all "Authorization: Bearer $API_KEY"

Get all the connections for a contact


return first N connections


return on connections of a specified type


include hidden connections (Y/N); hidden connections are not included by default

$ http$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


required - the ‘from’ or source of the connection


required - the ‘to’ or destination of the connection


recommended - a descriptive label for the connection


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


optional - start date for the connection


optional - end date for the connection


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

$ http$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"


Retrieve form responses for a single contact

POLICY: form.summary

http{bucket}/{organisation|person}/{uid}/form/summary "Authorization: Bearer $API_KEY"

POLICY: form.detail

http{bucket}/{organisation|person}/{uid}/form/detail "Authorization: Bearer $API_KEY"


Retrieve invoices for a single contact


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

POLICY: quote.summary

http{bucket}/{organisation|person}/{uid}/invoices/summary "Authorization: Bearer $API_KEY"

POLICY: quote.detail

http{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.


optional - maximum number of results returned - default is 20


optional - minimum match score - default is zero

http{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…).

http PUT{bucket}/{organisation|person}/merge/{duplicate uid}/into/{original uid} "Authorization: Bearer $API_KEY"

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