SheepCRM member auth

sheep-member-self-service.md

Sheep Member self-service integration guide

Notes:

• replace {flock} with the client identifier
• 201 = create
• 404 = not found (also returned on bad user credentials)
• 409 = conflict (auth and structure ok but a problem with the data values)
• curl defaults to GET the -d switch is an http POST

Login / Create a self-service member api token (bearer token)

Required: email, password

curl https://api.sheepcrm.com/api/v1/{flock}/user/auth/ -d "[email protected]&password=password" 
{
   "first_name" : "James",
   "username" : "159d5521d2",
   "bearer_token" : "159d5521d2:ae2be0da4f",
   "last_name" : "Webster",
   "email": "[email protected]",
   "session_expiry" : "2017-01-10T15:01:05.401000"
}

Pre-auth

Required: email

curl https://api.sheepcrm.com/api/v1/{flock}/user/preauth/ -d "[email protected]" 
{
   "next_step": "password",
   "username" : "159d5521d2",
   "status": "active"
   "email": "[email protected]",
}

next steps can be 'password', 'activation' or 'blocked'

Find a user account (system token required)

Required: email

curl https://api.sheepcrm.com/api/v1/{flock}/user/[email protected] -H "Authorization: Bearer {full api token}"
{
   ...
}

Create a user account (system token required)

Required: email

Optional: password (send to random string if not present)

curl https://api.sheepcrm.com/api/v1/{flock}/user/ -d "[email protected]&password=password" -H "Authorization: Bearer {full api token}"
{
   "email": "[email protected]", 
   "status": "created", 
   "username": "2c58216a85"
}

or

409 {"error": "existing user account found"}
409 {"error": "existing person found without user account"}

Get details for single user

curl https://api.sheepcrm.com/api/v1/{flock}/user/159d5521d2/ -H "Authorization: Bearer {token}" 
{
   "person" : {
      "postal_code" : "...",
      "region" : "...",
      "address_lines" : [
         "...",
         "..."
      ],
      "locality" : "..."
   },
   "first_name" : "James",
   "session_expiry" : "2017-01-10T15:01:05.401000",
   "last_name" : "Webster",
   "email": "[email protected]",
   "username" : "159d5521d2"
}

Get just the person details for a user

curl https://api.sheepcrm.com/api/v1/{flock}/user/159d5521d2/person/ -H "Authorization: Bearer {token}" 
{
   "postal_code" : "...",
   "region" : "...",
   "address_lines" : [
      "...",
      "..."
   ],
   "locality" : "..."     
}

Logout

logout is conceptually a delete on the auth token

curl https://api.sheepcrm.com/api/v1/{flock}/user/auth/ -H "Authorization: Bearer {token}" -X DELETE
{
   "status" : "ok"
}

Get details - fails after logout

curl https://api.sheepcrm.com/api/v1/{flock}/user/159d5521d2/ -H "Authorization: Bearer {token}" 
{
   "error" : "permission denied"
}

Request a password reset email

curl https://api.sheepcrm.com/api/v1/{flock}/user/reset/ -d "[email protected]"
{
   "status" : "ok"
}

set password using token

curl https://api.sheepcrm.com/api/v1/{flock}/user/password/ -d "token=78b0c64f9c:80200d669a&password=foofoo"
{
   "status" : "ok"
}

set password when authenticated

required: password

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/password/ -H "Authorization: Bearer {token}" -X PUT -d "password=foobar"
{
   "status" : "ok"
}

Editing records

• HTTP PUT is used to modify an existing resource.
• The payload is expected to be valid JSON.
• Multiple updates to the same record can be combined into a single call.

List fields

Sheep support list fields e.g. tags, email, telephone

{"tags": ["apple", "pear"]}

Append to a list fields by sending a single value

PUT {"tags":"orange"}
{"tags": ["apple", "pear", "orange"]}

Replace the list by sending a list

PUT {"tags":["apple", "orange"]}
{"tags": ["apple", "orange"]}

PUT {"tags":[]}
{"tags": []}

Delete a list item by removing and sending the whole list: e.g. remove pear

{"tags": ["apple", "pear"]}
PUT {"tags":["apple"]}
{"tags": ["apple"]}

User account editable fields

Edits to the user account will update the person record too (where the field is valid) i.e. an update to the first name of the user account will also update the first name of the person record. (see Person editable fields)

Editable fields: 'first_name', 'last_name', 'email', 'external_photo_url', 'timezone'

note: payload is json, method is PUT

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/ -X PUT -d '{"first_name":"Jim"}' -H "Authorization: Bearer {token}"
{
  "errors": {},
  "updates": {    
    "first_name": "Jim",
  }
}

Person editable fields

These are edits to the person record not the user account. Use this method to update person specific fields or to update the peson without changing the user account.

editable fields: 'first_name', 'last_name', 'address_lines', 'locality', 'comms_permission', 'region', 'postal_code', 'country', 'email', 'telephone', 'external_photo_url', 'timezone'

note: payload is json, method is PUT

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/person/ -X PUT -d '{"region":"Norfolk"}' -H "Authorization: Bearer {token}"
{
  "errors": {},
  "updates": {    
    "region": "Norfolk",
  }
}

Membership

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/ -H "Authorization: Bearer {token}"
{
    "memberships": [
        {...},        
        {...},
    ],
}

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/{muid}/ -H "Authorization: Bearer {token}"
{
    "amount": null,
    "billing_contact": "..."
    "currency": "..."
    "end_date": "..."
    "gift_aid": "..."
    "linked_members": "..."
        "..."
    ],
    "max_linked_members": "..."
    "member": "..."
    "membership_number": "..."
    "membership_plan_type": "..."
    "membership_record_status": "..."
    "membership_type": "..."
    "membership_type_for_display": "..."   
    "start_date": "..."
    "tags": "..."
        null
    ],
    "uri": "..."
    "muid": "..."
    "user_role": "owner|linked_member",
}

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/{muid}/linked/ -H "Authorization: Bearer {token}"
[
    {
        "email": "[email protected]",
        "first_name": "Michael",
        "last_name": "Mitchell",
        "uri": "..."
    },
    {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Lovett",
        "uri": "...",
        "luid": "..."
    }
]

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/{muid}/linked/{luid}/ -H "Authorization: Bearer {token}"
{
    "email": "[email protected]",
    "first_name": "Michael",
    "last_name": "Mitchell",
    "uri": "...",
    "luid": "..."
}

add a new linked member

required: first_name, last_name, email (will create a person record if it doesn't exist)

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/{muid}/linked/ -X POST -d '{"first_name":"Jim", "last_name":"Lovell", "email":"[email protected]"}' -H "Authorization: Bearer {token}"
{
    "status": "ok",
}

delete a new linked member

curl https://api.sheepcrm.com/api/v1/{flock}/user/{username}/membership/{muid}/linked/{luid}/ -X DELETE -H "Authorization: Bearer {token}"
{
    "status": "ok",
}

Fields exposed

address_lines
comms_permission
country
deceased
display_value
email
email_opt_out
external_photo_url
facebook_username
first_name
formatted_name
initial
instagram_username
job_title
known_as
language
last_name
linkedin_public_profile
locality
member_since
membership_record_status
membership-{n}
name_suffix
photo
postal_code
region
salutation
sortable_name
telephone
time_zone
title
twitter_username
uri
website

### membership plans
"amount" // number
"billing_contact"  // sheep uri 
"currency": // string 3 letter currency code lower case e.g. gbp | usd | eur
"end_date": // datetime
"gift_aid": // boolean
"member": // sheep uri 
"membership_number": // string
"membership_record_status": // active | lapsed | cancelled | incomplete | future
"membership_type": // sheep uri 
"membership_type_for_display": // string
"start_date": // datetime
"tags": // list of string

Create an event access code

required: email, password, event_uid

optional: partner (default is eventbrite)

The intention is to collect a users credential and if successful to redirect them to the event.

curl https://api.sheepcrm.com/api/v1/{flock}/user/events/access_code/ -X POST -d '{"email":"[email protected]", "password":"password", "event_uid":"1234567"}' 
{
   "email": "[email protected]", 
   "event_url": "https://www.eventbrite.co.uk/e/1234567/?discount=abcdefg", 
   "first_name": "James", 
   "last_name": "Webster", 
   "username": "1234abcde" 
}