SheepAPI Documentation

Contents:

• SheepAPI Self-service
• sheepAPI Public Service
• SheepAPI Core
• Messaging Service
• Search Service
• OAuth2 Client Registration
• Policies
• Solution Catalog
• Release Notes

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.

Discord

We are experimenting with a Discord chat server to help our users. Join and say hello: https://discord.gg/GE8g88Ktds

New API Documentation

These documents are being replaced with OpenAPI documentation at https://sls-api.sheepcrm.com/.well-known/docs.html If there are contradictions please let us know and assume the newer OpenAPI documents are correct.

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 https://api.sheepcrm.com/api/v1/ping/

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 https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY"

http https://api.sheepcrm.com/api/v1/example/ 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

200

OK

201

create

403

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

404

not found (also returned on bad user credentials)

409

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

4xx

client error

5xx

Sheep error up

HTTP Verbs

GET

Read

PUT

Update

POST

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).

DELETE

Delete

Terminology

api_key

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

flock

The client identifier/database also known as a bucket

resource_type

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

resource

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}

API Throttling

We reserves the right to modify the rate limits at any time. For the up-to-date information on rate limits, you can review the HTTP response headers returned from rate-limited endpoints.

If you receive a rate limit-related response header, it will include numeric information detailing your status.

x-rate-limit-limit

The maximum number of requests available in the current time frame per hour and per minute

x-rate-limit-remaining

The number of remaining requests in the current time frame.

x-rate-limit-reset

The number of seconds (approximately) until the limit resets

The rate limit string:

e.g. [ ‘40, 400;window=60, 1000;window=3600’ ] 40 calls remaining, the minute window limit is 400, the hour window is 1000