SheepAPI Documentation

SheepAPI is the platform that supports SheepCRM, SheepTeams and SheepApp and the many partners that connect to Sheep data. The API is divided into two parts: the core system API and the self-service API. For apps wanting to provide an interface for a single contact the self service API will be of most use. The core API gives access to all data.


We are experimenting with a Discord chat server to help our users. Join and say hello:

Getting started

You need to have already registered for a Sheep database and have an active user account. We’ll use the wonderful httpie http client in this document. See their site for installation instructions for your platform. Sheep APIs follow the RESTful design model wherever possible. HTTP verbs should be expected to work on all resources unless otherwise documented. We recommend testing API calls using httpie before implementing in code. If you need to submit a bug report please provide a working (failing) httpie example.

We recommend httpie and the syntax is cleaner and generally simpler to read. If you are a cURL fan or can’t install httpie we recommend the Everything cURL book for tips on using cURL.

The examples will frequently refer to $FLOCK in the URL. You should replace this with the database that you want to work with. On a Mac use export FLOCK=example (replacing example…) then most URL examples can be copied directly.

Check Sheep is up

and check that your environment is working properly.


HTTP/1.1 200 OK
    "message": "pong"

Checking your permissions

Once you have successfully ‘pinged’ the API try an authenticated call. To do this you will need to set two environment variables or replace the tokens with your actual values in the example. (If you don’t have an API key you can set your own by logging into SheepCRM then navigate to the Profile settings or see Get an auth token in these docs.).

export FLOCK=example
export API_KEY=my-secret-api-key
http$FLOCK/ Authorization:"Bearer $API_KEY"
http Authorization:"Bearer my-secret-api-key"

You are expecting a HTTP 200 response with a list of resources as your response. A 403 FORBIDDEN response indicates a problem with your API key or your permissions.

HTTP Access codes






forbidden - you do not have access to this resource (check you Auth/API Key)


not found (also returned on bad user credentials)


conflict (auth and structure ok but a problem with the data values)


client error


Sheep error up

HTTP Verbs






Create. Note: The system tries to stop accidental duplicates so a POST will check before creating. If you need to create a record which the system may think is a dupe then either send more data (to show uniqueness) or create with unique data and then update. (legacy_uid is a good field that you can control).





The bearer token provided by the auth call. The bearer token must be supplied as a header for all authenticated calls.


The client identifier/database also known as a bucket


These are the data type / tables / models used by Sheep. person, organisation, booking, ticket, payment are all examples of resource types.


A single record of a given resource type

primary resources

person, organisation, booking, group

secondary resources

e.g. payment, ticket, membership These are records which attach to primary resources

sheep uri

Sheep URIs are used extensively to refer to resources they are comprised of /$FLOCK/{resource_type}/{uid}/

slugified uri

A Sheep URI as a string $FLOCK-{resource_type}-{uid}