Core API

The sheepCRM Core API provides RESTful access to all data resources within a flock (database). This guide covers authentication, basic operations, querying, and pagination.

Getting Started

Get an auth token

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

POST https://api.sheepcrm.com/api/v1/auth/
Content-Type: application/json

{"username": "user@example.com", "password": "password"}

With incorrect credentials:

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

With correct credentials:

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

For cURL users:

curl https://api.sheepcrm.com/api/v1/auth/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"user@example.com","password":"password"}'

Making an authenticated request

Get a list of resource types for the client account (with record counts). This 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.

GET 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"
    }
  ]
}

Declaring the name of your application

The HTTP APPLICATION header identifies the source of requests and provides better support. The value should be a short string that identifies your organisation and the application or service making the request.

Caution

In future, calls without an APPLICATION header will have a limited throttle applied.

GET https://api.sheepcrm.com/api/v1/$FLOCK/
Authorization: Bearer $API_KEY
APPLICATION: AgencyX/MyApp/1.0

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.

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"
        }
    ]
}

CRUD Operations

Create a resource

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

POST https://api.sheepcrm.com/api/v1/$FLOCK/{resource_type}/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"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",
    "meta": {
        "created": "2020-02-12T13:47:45.695000",
        "last_updated": "2020-02-12T13:47:45.730000",
        "state": "updated"
    },
    "resource": "person",
    "uri": "/example/person/5e44020149c3a85acee1ff9b/"
}

Get all resources of a given type

Example limited to a page size of 1:

GET https://api.sheepcrm.com/api/v1/$FLOCK/person/?page_size=1
Authorization: Bearer $API_KEY

HTTP/1.1 200 OK
{
    "grand_total": 1216,
    "page": 1,
    "page_size": 1,
    "pages": 1216,
    "results": [
        {
            "bucket": "example",
            "created": "2015-01-05T20:44:34.447000",
            "data": {
                "first_name": "Daniel",
                "last_name": "Abbott",
                "formatted_name": "Mr Daniel I Abbott",
                "email": [
                    "daniel@home.com;home",
                    "daniel.abbott@company.com;work__primary"
                ],
                "tags": [
                    "donor",
                    "family",
                    "gift-aid"
                ]
            },
            "display_value": "Mr Daniel I Abbott",
            "id": "54aaf7b23078f80d90d8ca7b",
            "last_updated": "2020-02-24T00:09:05.852000",
            "resource": "person",
            "state": "updated",
            "uri": "/example/person/54aaf7b23078f80d90d8ca7b/"
        }
    ],
    "total": 1216
}

Get a single resource record

Using the URI from a previous response (e.g. /example/person/5e44020149c3a85acee1ff9b/):

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

HTTP/1.1 200 OK
{
    "bucket": "example",
    "data": {
        "first_name": "Jim",
        "last_name": "Lovell",
        "formatted_name": "Jim Lovell",
        "salutation": "Sir"
    },
    "display_value": "Jim Lovell",
    "meta": {
        "created": "2020-02-12T13:47:45.695000",
        "last_updated": "2020-02-12T13:47:45.813000",
        "state": "updated"
    },
    "resource": "person",
    "uri": "/example/person/5e44020149c3a85acee1ff9b/"
}

Update a record

PUT a JSON packet with the fields to update (multiple fields allowed):

PUT https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"first_name": "Jim"}

HTTP/1.1 200 OK
{
    "first_name": "Jim"
}

Updating with a file

The journal resource has a files field. Example using httpie to upload a photo:

PUT https://api.sheepcrm.com/api/v1/example/journal/623c6d09eb69265e5de83da5/
Authorization: Bearer $API_KEY

files@'beer.jpg;type=image/jpg'

HTTP/1.1 200 OK
{
    "errors": {},
    "updates": {
        "files": [
            "https://sheepcrm.s3.amazonaws.com/example/journal/623c6d09eb69265e5de83da5/files/beer.jpg"
        ]
    }
}

Delete a single record

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

Restore a deleted record

POST https://api.sheepcrm.com/api/v1/example/person/5e44020149c3a85acee1ff9b/restore/
Authorization: Bearer $API_KEY

Obfuscate a single record

Obfuscate a record to remove personal data but keep the record for auditing and reporting:

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

Get the display value for a single resource record

GET 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

GET https://sls-api.sheepcrm.com/api/v2/example/person/5e44020149c3a85acee1ff9b/avatar

HTTP/1.1 200 OK
(binary image data)

Getting a signed URL

Some resources do not require authentication but are signed for additional security (e.g. a membership card):

GET https://api.sheepcrm.com/api/v2/example/member/5e44020149c3a85acee1ff9b/card/

HTTP/1.0 401 Unauthorized
{
    "description": "a signature parameter is required when requesting a signed url",
    "title": "signature missing"
}

GET https://api.sheepcrm.com/api/v2/example/member/5e44020149c3a85acee1ff9b/card/?signature=38c36ebd5fa6...

HTTP/1.0 200 OK

Query Logic

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

Modifier	Description
__and	AND (works with lists in v1)
__andlist	(v2 only) AND list, e.g. tags__andlist=tag1,tag2 returns records with both tag1 and tag2
__contains	String field contains the value, e.g. first_name__contains=jam matches “james”
__eq	Exact match
__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 (works with lists in v1)
__orlist	(v2 only) OR list, e.g. tags__orlist=tag1,tag2 returns records with either tag1 or tag2
__raw	Raw
__startswith	Starts with
__startswithi	Starts with (case insensitive)

Querying examples

Each resource type can be queried using the same RESTful methods.

All people called James:

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

All people called James Webster (AND mode):

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

All people called James or last name Webster (OR mode):

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

Special queries

Include deleted records with include_deleted=Y:

GET https://api.sheepcrm.com/api/v1/$FLOCK/{resource}/?include_deleted=Y
Authorization: Bearer $API_KEY

Show only deleted records:

GET https://api.sheepcrm.com/api/v1/$FLOCK/{resource}/?include_deleted=Y&state=deleted
Authorization: Bearer $API_KEY

Smart dates

The following strings can be used in place of a date to represent a relative date:

Smart Date	Description
last month	Today minus one month
last week	Today minus one week
last year	This time last year
next month	This time next month
next week	This time next week
next year	This time next year
start_of_month	Start of this month
start_of_year	Start of this year
today	Now, including current time
tomorrow	This time tomorrow
year_ago	This time a year ago
yesterday	This time yesterday

Paging Results

Queries against the Sheep API use a default page size of 25. The page size can be set using the page_size parameter and used in conjunction with the page parameter to iterate through all results. The pages value provided in data packet indicates how many pages to expect. Internally we use page sizes up to 1000 (beyond 1000 it is typically quicker to make multiple smaller calls). The maximum allowed is currently 1500.

{
    "grand_total": 1216,
    "page": 1,
    "page_size": 25,
    "pages": 49,
    "results": []
}

To query all results you should read the number of pages from the first response and loop until the page requested matches the number of pages available:

GET https://api.sheepcrm.com/api/v1/$FLOCK/person/?first_name=james
GET https://api.sheepcrm.com/api/v1/$FLOCK/person/?first_name=james&page=2
GET https://api.sheepcrm.com/api/v1/$FLOCK/person/?first_name=james&page=3

Note

Sheep uses page-based pagination, not cursor-based pagination. Applications must be aware of the limitations, e.g. data changing between page requests, possible duplicates and missing records across pages.

Recalculating a Record

Some resources accept a force param to recalculate related resources (force will typically be slower):

POST https://api.sheepcrm.com/api/v1/{flock}/{resource_type}/{uid}/recalc/

HTTP/1.0 200 OK
{
    "status": "OK",
    "force": false
}

Touch

Update the timestamp on a record:

POST https://api.sheepcrm.com/api/v1/{flock}/{resource_type}/{uid}/touch/

Asynchronous Tasks

Some tasks are long running and are handled asynchronously. The response will include a task_id which can be used to check the status of the task. The task_id will be a sheep_event for system or non-user initiated tasks and a journal notification where the task result will be of interest to the user. The task_id can be used to check the status of the task: the tag field on the record will be updated with the status of the task. The body of the task will be updated with the result of the task.

Note

Not all asynchronous tasks follow this design pattern. If you are unsure please contact support.