SheepAPI Core

Get an auth token

A core auth token will provide access to all data resources for a flock.

$ http POST https://api.sheepcrm.com/api/v1/auth/ username=james@james-webster.co.uk password=password

HTTP/1.1 403 FORBIDDEN
{
    "error": "Unable to authenticate",
    "error_detail": "Username and Password do not match an account"
}

that’s not the password… With correct credentials you should get an api key returned.

HTTP/1.1 200 OK
{
        "api_key": "7ba68f4c99"
}

Making an authenticated request

Get a list of resource types for the client account (& records numbers) checks auth to the flock and provides a lookup for the different resource_types. resource_types are the Sheep name for what might normally be expected to be a database table or collection

$ http https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY"

HTTP/1.1 200 OK
{
  "resource_type": [
    {
      "count": 6,
      "name": "activity"
      "last_modified": "2017-03-28T18:57:47.637000",
    },
    {
      "count": 5,
      "name": "allocation"
      "last_modified": "2017-03-28T18:57:47.637000",
    },
    ...
    ]
}

List available databases (flocks)

A typical user will only be connected to a single database (flock) but you can verify which flocks a user has permissions to access with the base /api/v1/ call.

http GET https://api.sheepcrm.com/api/v1/ Authorization:"Bearer $API_KEY"
HTTP/1.1 200 OK

{
    "flocks": [
        {
            "identifier": "example",
            "name": "Sheep Example"
        },
        {
            "identifier": "example-association",
            "name": "Example Association"
        },
        {
            "identifier": "example-family",
            "name": "Example Family"
        },
    ]
}

Create a resource

Resources are the data objects in Sheep. Each resource has it’s own schema but the API calls to interact with resources are all the same.

/api/v1/$FLOCK/{resource_type}/

http POST https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name=Jim last_name=Lovell
HTTP/1.1 201 CREATED

{
    "bucket": "example",
    "data": {
        ...
        "first_name": "Jim",
        "last_name": "Lovell",
        ...
    },
    "display_value": "an empty person",
    "links": [
        ...
    ],
    "meta": {
        "created": "2020-02-12T13:47:45.695000",
        "last_updated": "2020-02-12T13:47:45.730000",
        "state": "updated"
    },
    "resource": "person",
    "uri": "/example/person/5e44020149c3a85acee1ff9b/"
}

(empty fields removed for brevity)

Get all resources of a given type

(Example limited to a page size of 1)

http https://api.sheepcrm.com/api/v1/$FLOCK/person/\?page_size\=1 Authorization:"Bearer $API_KEY"
HTTP/1.1 200 OK
{
    "grand_total": 1216,
    "links": [
        ...
    ],
    "page": 1,
    "page_size": 1,
    "pages": 1216,
    "results": [
        {
            "_id": null,
            "bucket": "example",
            "created": "2015-01-05T20:44:34.447000",
            "data": {
                "abilities": [
                    "usher"
                ],
                "address_lines": [
                    "Studio 6"
                ],
                "adult": true,
                "anniversary": null,
                "authorised_pickup": null,
                "automatic_email_opt_out": null,
                "bio": null,
                "colour": null,
                "comms_permission": [
                    null,
                    "sms",
                    "telephone"
                ],
                "connections": [
                    null,
                    "/example/organisation/54aaf9763078f80f3ed8ca0b/;Grant Recipient",
                    "/example/organisation/54aaf97b3078f80f3ed8cad7/;Accreditation Contact",
                    "/example/organisation/54aaf97b3078f80f3ed8cad7/;Garden Contact",
                    "/example/organisation/54aaf97d3078f80f3ed8cb42/;Charity Fundraiser",
                    "/example/organisation/54aaf9853078f80f3ed8cc9b/;Manager",
                    "/example/person/5746cfa53078f87b2bc3e177/;shared interest"
                ],
                "country": "UK",
                "date_of_birth": null,
                "date_of_death": null,
                "deceased": null,
                "domain": null,
                "driving_licence": null,
                "editable_formatted_name": null,
                "editable_salutation": null,
                "email": [
                    "danied@home.com;home",
                    "daniel.abbott@company.com;work__primary"
                ],
                "email_opt_out": false,
                "emergency_contact_details": null,
                "emergency_contact_details_2": null,
                "expertise": null,
                "external_ids": [
                    null
                ],
                "external_photo_url": null,
                "facebook_username": null,
                "first_name": "Daniel",
                "formatted_name": "Mr Daniel I Abbott",
                "gender": null,
                "geo": null,
                "gocardless_uid": null,
                "has_direct_debit_mandate": null,
                "hide_from_views": false,
                "initial": "I",
                "instagram_username": null,
                "interests": [
                    "Baking",
                    "Volunteering"
                ],
                "iso_country": "GB",
                "job_title": "Administrator",
                "known_as": null,
                "language": null,
                "last_name": "Abbott",
                "legacy_uid": null,
                "linkedin_public_profile": null,
                "locality": "Witney",
                "mailchimp_last_sync": null,
                "mailsort_code": null,
                "member_original_join_date": null,
                "member_since": null,
                "name_suffix": null,
                "notes": null,
                "photo": "https://s3-eu-west-1.amazonaws.com/sheepcrm/example/person/54aaf7b23078f80d90d8ca7b/photo/54.jpg",
                "photo_required": null,
                "postal_code": "OX28 6AL",
                "region": "Oxfordshire",
                "salutation": "Mr Abbott",
                "school": null,
                "school_year": null,
                "school_year_modifier": null,
                "sen": null,
                "skype_username": null,
                "sortable_name": "abbott daniel i mr",
                "source": null,
                "stripe_last_sync": null,
                "stripe_uid": null,
                "tags": [
                    "bad-tag",
                    "blue iguana",
                    "donor",
                    "family",
                    "gift-aid",
                    "mynewtag",
                    "trustee",
                    "🐑 member"
                ],
                "telephone": [
                    "01234 567 891;work",
                    "01993 700 100;home"
                ],
                "test": null,
                "time_zone": null,
                "title": "Mr",
                "twitter_username": "example",
                "vend_uid": null,
                "website": "example.com",
                "xero_last_sync": null,
                "xero_uid": null
            },
            "display_value": "Mr Daniel I Abbott",
            "id": "54aaf7b23078f80d90d8ca7b",
            "last_updated": "2020-02-24T00:09:05.852000",
            "links": [
                ...
            ],
            "permissions": {
                ...
            },
            "resource": "person",
            "state": "updated",
            "uri": "/example/person/54aaf7b23078f80d90d8ca7b/"
        }
    ],
    "total": 1216
}

Query logic

Append the field name with a modifier to use query logic. e.g. amount__gte=5 results where amount is 5 or more

__and:and list __eq:exact __gt:greater than __gte:greater than or equals __lt:less than __lte:less than or equals __ne:not equal to __near:near __none:none of __or:or list __raw:raw __startswith:starts with __startswithi:starts with case insensitive

Querying

Each resource type can be queried using the same RESTful methods

All people called James (/{flock}/person/?first_name=james)

http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name==james

All people called James Webster (/{flock}/person/?first_name=james&last_name=webster&mode=AND)

http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name==james last_name==webster mode==AND

All people called James or last name Webster (/{flock}/person/?first_name=james&last_name=webster&mode=OR)

http https://api.sheepcrm.com/api/v1/$FLOCK/person/ Authorization:"Bearer $API_KEY" first_name==james last_name==webster mode==OR

Get a single resource record

e.g. uri = /example/person/5e44020149c3a85acee1ff9b/

This is the record that we created earlier with just the first name “Jim” and last name “Lovell”. Most other data fields are empty null but some are generated by the system e.g. formatted_name

http https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY"
HTTP/1.1 200 OK

{
    "bucket": "example",
    "data": {
        "abilities": [
            null
        ],
        "address_lines": [
            null
        ],
        "adult": null,
        "anniversary": null,
        "authorised_pickup": null,
        "automatic_email_opt_out": null,
        "bio": null,
        "colour": null,
        "comms_permission": [
            null
        ],
        "connections": [
            null
        ],
        "country": null,
        "date_of_birth": null,
        "date_of_death": null,
        "deceased": null,
        "domain": null,
        "driving_licence": null,
        "editable_formatted_name": null,
        "editable_salutation": null,
        "email": [
            null
        ],
        "email_opt_out": null,
        "emergency_contact_details": null,
        "emergency_contact_details_2": null,
        "expertise": null,
        "external_ids": [
            null
        ],
        "external_photo_url": null,
        "facebook_username": null,
        "first_name": "Jim",
        "formatted_name": "Jim Lovell",
        "gender": null,
        "geo": null,
        "gocardless_uid": null,
        "has_direct_debit_mandate": null,
        "hide_from_views": false,
        "initial": null,
        "instagram_username": null,
        "interests": [
            null
        ],
        "iso_country": null,
        "job_title": null,
        "known_as": null,
        "language": null,
        "last_name": "Lovell",
        "legacy_uid": null,
        "linkedin_public_profile": null,
        "locality": null,
        "mailchimp_last_sync": null,
        "mailsort_code": null,
        "member_original_join_date": null,
        "member_since": null,
        "name_suffix": null,
        "notes": null,
        "photo": null,
        "photo_required": null,
        "postal_code": null,
        "region": null,
        "salutation": "Sir",
        "school": null,
        "school_year": null,
        "school_year_modifier": null,
        "sen": null,
        "skype_username": null,
        "sortable_name": "lovell jim",
        "source": null,
        "stripe_last_sync": null,
        "stripe_uid": null,
        "tags": [
            null
        ],
        "telephone": [
            null
        ],
        "test": null,
        "time_zone": null,
        "title": null,
        "twitter_username": null,
        "vend_uid": null,
        "website": null,
        "xero_last_sync": null,
        "xero_uid": null
    },
    "display_value": "Jim Lovell",
    "links": [
        ...
    ],
    "meta": {
        "created": "2020-02-12T13:47:45.695000",
        "last_updated": "2020-02-12T13:47:45.813000",
        "state": "updated"
    },
    "resource": "person",
    "uri": "/example/person/5e44020149c3a85acee1ff9b/"
}

Delete a single record

you can recover the record using the UI but not currently via the API

http DELETE https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY"

Update a record

PUT a json packet, multiple fields allowed

http PUT https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/ Authorization:"Bearer $API_KEY" first_name=Jim

HTTP/1.1 200 OK

{
        "first_name": "Jim",
}

Obfuscate a single record

obfuscate a record to remove personal data but keep the record for auditing and reporting.

http PUT https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/obfuscate/ Authorization:"Bearer $API_KEY"

Get the display value for a single resource record

http https://api.sheepcrm.com/api/v2/example/person/5e44020149c3a85acee1ff9b/display Authorization:"Bearer $API_KEY"
HTTP/1.1 200 OK

{
"display_value": "Jim Lovell"
}

Get the avatar for a single resource record

http https://api.sheepcrm.com/api/v2/example/person/5e44020149c3a85acee1ff9b/avatar
HTTP/1.1 200 OK

        +------------------------------+
        | NOTE: binary data not shown  |
        +------------------------------+