Faithlife Developer Center

In order to make requests, OAuth credentials must be obtained by registering an application with Faithlife. For more on OAuth, see Authentication.

The Faithlife API is separated into two sections: Accounts and Community. The Accounts API encompasses user and group data, such as creating a group or user or determining what groups a user is a member of. The Community API encompasses all social interaction between accounts, such as commenting and creating notes.

API Format

API requests and responses that have a content section are JSON-encoded and must have the content type set to application/json.

URI Structure

Accounts requests are prefixed by https://accountsapi.logos.com/v2/

Community requests are prefixed by https://api.faithlife.com/community/v2/

API endpoints require requests to be signed in conformance to the OAuth 1.0a standard.

Requests may use the PLAINTEXT or HMACSHA1 signature methods.

Endpoints

Temporary Credentials URL	https://auth.faithlife.com/v1/temporarytoken
Authorize URL	https://auth.faithlife.com/v1/authorize
Access Credentials URL	https://auth.faithlife.com/v1/accesstoken

curl https://accountsapi.logos.com/v2/users/me -H "Authorization: OAuth \
oauth_consumer_key=\"{consumer_token}\",\
oauth_signature=\"{consumer_secret}%26{access_secret}\",\
oauth_signature_method=\"PLAINTEXT\",\
oauth_version=\"1.0\",\
oauth_token=\"{access_token}\""

All responses contain the X-RateLimit-Remaining and X-RateLimit-Limit headers. These headers indicates how many requests remain for the current hour and how many requests per hour are allowed, respectively.

For example, curl -i https://accountsapi.logos.com/v2/users/me should return:

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999

Avatar URLs

Field	Type	Required	Description
avatarUrl	string	no
avatarUrlLarge	string	no

Date

All fields denoted as the type in the API documentation are strings that conform to the ISO 8601 date / time interchange format and are formatted to the second in Coordinated Universal Time (UTC). In short, all strings will be formatted as YYYY-MM-DDTHH:MM:SSZ, where YYYY represents the year, MM represents the month, DD represents the day, HH represents the hour , MM represents the minute, and SS represents the second.

Group

Field	Type	Required	Description
alias	string	no
avatarUrls	Avatar Urls	no
city	string	no
countryAbbrev	string	no
description	string	no
email	string	no
expirationDate	Date	no
formattedAddress	string	no
groupId	string	yes
isPinned	bool	no
kind	string	no
latitude	double	no
longitude	double	no
name	string	no
organizationUrl	string	no
phone	string	no
preferredMembershipKind	string	no
privacy	string	no
rawLocation	string	no
shortDescription	string	no
startDate	Date	no
stateAbbrev	string	no
timeZone	string	no
token	string	no

User

Field	Type	Required	Description
alias	string	yes	User's display name.
avatarUrls	Avatar Urls	no
birthDay	int	no
birthMonth	int	no
birthYear	int	no
dayPhone	string	no
denomination	string	no
description	string	no
email	string	no
eveningPhone	string	no
gender	string	no
homePageUrl	string	no
id	string	yes
isMarried	bool	no
isSolicitable	bool	no
location	string	no
name	string	yes	Users's real name
organization	string	no
organizationUrl	string	no
shortDescription	string	no
title	string	no
token	string	no	A token that may be used in some routes in place of an id, intended to be more human readable.

Invite

Field	Type	Required	Description
accountId	string	no	Account to be invited.
inviteId	string	no
user	User	no
group	Group	no
emailInvite	EmailInvite	no

InviteCollection

Field	Type	Required	Description
total	int	no
invites	Invite	yes	List of Invites.
message	string	no

Membership

Field	Type	Required	Description
membershipId	string	yes

EmailInvite

Field	Type	Required	Description
email	string	no	Email address to send invite to.
emailInviteToken	string	no

Get Current User

GET /users/me

This method returns general information about the current user.

The response is a user object.

curl https://accountsapi.logos.com/v2/users/me

200 OK
{
    "alias": "John Doe",
    "avatarUrls": {
        "avatarUrl": "http://example.com/avatar.jpg",
        "avatarUrlLarge": "http://example.com/avatarLarge.jpg"
    },
    "birthDay": 1,
    "birthMonth": 1,
    "birthYear": 1985,
    "email": "someone@example.com",
    "gender": "M",
    "id": "12",
    "isSolicitable": false,
    "name": "John Doe",
    "organization": "Logos",
    "organizationUrl": "http://www.logos.com",
    "title": "Software Developer",
    "token": "example",
 }

Get User

GET /users/{userId}

This method returns general information about the specified user.

The response is a user object.

curl https://accountsapi.logos.com/v2/users/3

200 OK
{
  "alias": "Bob Pritchett",
  "avatarUrls": {
    "avatarUrl": "http://example.com/avatar.jpg",
    "avatarUrlLarge": "http://example.com/avatarLarge.jpg"
  },
  "description": {},
  "homePageUrl": "http://www.bobpritchett.com",
  "id": "3",
  "location": "Bellingham, Washington",
  "name": "Bob Pritchett",
  "organization": "Logos Bible Software",
  "organizationUrl": "https://www.logos.com",
  "shortDescription": "CEO of Logos Bible Software, author of Fire Someone Today.
            Interested in entrepreneurship, ebooks, technology, and food."
  "title": "President/CEO"
  "token": "bobpritchett",
}

Get Users

GET /users

This method searches all users or returns general information about specified users based upon query parameters.

The response is a collection of user objects.

Parameters

ids	string	no	A comma delimited list of user id strings
q	string	no	Free-form search text
offset	int	no
limit	int	no

Exactly one of "ids" or "q" must be specified.

curl https://accountsapi.logos.com/v2/users?ids=3

200 OK
{
  "users": [{
    "alias": "Bob Pritchett",
    "avatarUrls": {
      "avatarUrl": "http://example.com/avatar.jpg",
      "avatarUrlLarge": "http://example.com/avatarLarge.jpg"
    },
    "description": {},
    "homePageUrl": "http://www.bobpritchett.com",
    "id": "3",
    "location": "Bellingham, Washington",
    "name": "Bob Pritchett",
    "organization": "Logos Bible Software",
    "organizationUrl": "http://www.logos.com",
    "shortDescription": "CEO of Logos Bible Software, author of Fire Someone Today.
            Interested in entrepreneurship, ebooks, technology, and food."
    "title": "President/CEO",
    "token": "bobpritchett",
  }]
}

Create Group

POST /groups

This method creates a group.

The response is a group object.

Parameters

name	string	yes
privacy	string	yes

curl -X POST https://accountsapi.logos.com/v2/groups
{
  "name": "My Group",
  "privacy": "open"
}

201 Created
{
  "id": "GROUP ID",
  "token": "my-group-token"
}

Get Group

GET /groups/{groupId}

This method returns general information about the specified group.

The response is a group object.

curl https://accountsapi.logos.com/v2/groups/bham-foodies

200 OK
{
    "avatarUrls": {
      "avatarUrl": "http://example.com/avatar.jpg",
      "avatarUrlLarge": "http://example.com/avatarLarge.jpg"
    },
    "city": "Bellingham",
    "countryAbbrev": "US",
    "description": "A place for dedicated food lovers to recommend new places
                    to eat or their favorite diners in town.",
    "formattedAddress": "Bellingham, WA, USA",
    "groupId": "998714",
    "isInviteOnly": false,
    "isPinned": false,
    "kind": "specialInterest",
    "latitude": 48.759551999999999,
    "longitude": -122.488224,
    "name": "Bham Food Lovers",
    "preferredMembershipKind": "member",
    "privacy": "open",
    "searchName": "Bham Food Lovers",
    "stateAbbrev": "WA",
    "token": "bham-foodies"
}

Get Groups

GET /groups

This method lists groups that meet the specified criteria.

The response is a collection of group objects.

Parameters

ids	string	no	A comma delimited list of group id strings
q	string	no	Free-form search text
offset	int	no
limit	int	no

Exactly one of "ids" or "q" must be specified.

curl https://accountsapi.logos.com/v2/groups?q=bham

200 OK
{
   "total": 1,
   "groups": [
     {
       "alias": "Bham Food Lovers",
       "avatarUrls": {
         "avatarUrl": "http://example.com/avatar.jpg",
         "avatarUrlLarge": "http://example.com/avatarLarge.jpg",
       },
       "city": "Bellingham",
       "countryAbbrev": "US",
       "dateCreated": "2012-02-24T17:49:27Z",
       "dateModified": "2012-04-30T18:52:49Z",
       "description": "A place for dedicated food lovers to recommend new
                       places to eat or their favorite diners in town.",
       "formattedAddress": "Bellingham, WA, USA",
       "groupId": "998714",
       "isInviteOnly": false,
       "isPinned": false,
       "kind": "specialInterest",
       "latitude": 48.759551999999999,
       "longitude": -122.488224,
       "name": "Bham Food Lovers",
       "preferredMembershipKind": "member",
       "privacy": "open",
       "stateAbbrev": "WA",
       "token": "bham-foodies"
   }
 ]
}

Get Groups For User

GET /users/{userId}/groups

This method lists the groups that the specified user is a member of.

The response is a collection of group objects.

Parameters

offset	int	no
limit	int	no

curl https://accountsapi.logos.com/v2/users/9999999999/groups

200 OK
{
   "total": 1,
   "groups": [
     {
       "alias": "Bham Food Lovers",
       "avatarUrls": {
         "avatarUrl": "http://example.com/avatar.jpg",
         "avatarUrlLarge": "http://example.com/avatarLarge.jpg",
       },
       "city": "Bellingham",
       "countryAbbrev": "US",
       "dateCreated": "2012-02-24T17:49:27Z",
       "dateModified": "2012-04-30T18:52:49Z",
       "description": "A place for dedicated food lovers to recommend new
                       places to eat or their favorite diners in town.",
       "formattedAddress": "Bellingham, WA, USA",
       "groupId": "998714",
       "isInviteOnly": false,
       "isPinned": false,
       "kind": "specialInterest",
       "latitude": 48.759551999999999,
       "longitude": -122.488224,
       "name": "Bham Food Lovers",
       "preferredMembershipKind": "member",
       "privacy": "open",
       "stateAbbrev": "WA",
       "token": "bham-foodies"
   }
 ]
}

Get Invites For User

GET /invites

This method lists the current user's pending invites.

The response is an inviteCollection object.

Parameters

offset	int	no
limit	int	no

curl https://accountsapi.logos.com/v2/invites

200 OK
{
   "total": 1,
   "invites": [
   {
     "inviteId": "123",
     "user": {
       "id": "456",
       "alias": "John Doe",
       "name": "John Doe",
     },
     "group": {
       "groupId": "789",
     }
   }
 ]
}

Get Invites For Group

GET /groups/{groupId}/invites

This method lists the group's pending invites.

The response is an inviteCollection object.

Parameters

offset	int	no
limit	int	no

curl https://accountsapi.logos.com/v2/groups/123/invites

200 OK
{
   "total": 1,
   "invites": [
   {
     "inviteId": "123",
     "user": {
       "id": "456",
       "alias": "John Doe",
       "name": "John Doe",
     },
     "group": {
       "groupId": "789",
     }
   }
 ]
}

Invite Users To Group

POST /groups/{groupId}/invites

This method creates invites for a group.

Parameters

invites

InviteCollection

no

curl -X POST https://accountsapi.logos.com/v2/groups/123/invites
{
   "invites": [
   {
     "accountId": "456"
   },
   {
     "emailInvite": 
	 {
	   "email": "exampleUser@example.com"
	 }
   }
 ]
}

202 Accepted

Accept Invite To Group

POST /invites/{inviteId}/accept

This method accepts and invitation to a group.

The response is a membership object.

curl -X POST https://accountsapi.logos.com/v2/invites/123/accept

201 Created
{
  "membershipId": "123",
}

Delete Membership

DELETE /memberships/{membershipId}

This method removes a user's group membership.

curl -X DELETE https://accountsapi.logos.com/v2/memberships/123

204 No Content

Comment

id	string	yes
sourceAccountId	string	no
sourceDestinationId	string	no
text	string	yes
url	string	no

Metadata

id

string

yes

Note

id	string	yes
destinationAccountId	string	no
metadata	Metadata	no	A collection of metadata.
resourceLocations	Resource Location	no	A collection of resource locations.
sourceAccountId	string	no
text	string	yes
title	string	yes
url	string	no

Reference

Raw	string	yes
Text	string	yes

Resource Location

reference	Reference	no
resource	string	yes
offset	string	no
selectionLength	string	no
version	string	no

Create Comment

This method posts a comment to an account.

The response is a comment object.

POST /comments

Parameters

destinationAccountId	string	yes
sourceAccountId	string	yes
text	string	yes
url	string	no

curl -X POST https://api.faithlife.com/community/v2/comments
{
  "destinationAccountId": "USER OR GROUP ID",
  "sourceAccountId": "USER OR GROUP ID",
  "text": "This is a comment",
}

201 Created
{
   "id": "COMMENT ID"
 }

Get Group Newsfeed

This method gets the newsfeed for the specified group.

The response is a collection of comment objects.

GET /groups/{groupId}/newsfeed

Parameters

offset	int	no
limit	int	no

curl https://api.faithlife.com/community/v2/groups/999999/newsfeed

200 OK
{
   "items": [{
       "kind": "comment",
       "comment": {
           "destinationAccountId": "999999",
           "sourceAccountId": "3",
           "text": "This is a comment"
       }, ...
   ],
   "total": 10
}

Get Group Notes

This method gets the notes for the specified group.

The response is a collection of note objects.

GET /groups/{groupId}/notes

Parameters

offset	int	no
limit	int	no

curl https://api.faithlife.com/community/v2/groups/999999/notes

200 OK
{
   "notes": [{
       "id": "1234",
       "destinationAccountId": "999999",
       "sourceAccountId": "3",
       "text": "This is a note"
       "metadata": [{
           "kind": "BibliaReference",
           "data": {
               "Url": "http://bible.faithlife.com/books/esv/Mark%202.1",
               "CoverUrl": "http://covers.logoscdn.com/lls_1.0.710/50x80/cover.jpg",
               "Content": "And when he returned to Capernaum after some days, it was reported that he was at home.",
               "Reference": "Mark 2:1",
               "ResourceTitle": "English Standard Version",
               "ResourceShortTitle": "ESV"
               }
           }],
       "resourceLocations": [{
           "resource": "esv",
           "version": "1.0",
           "reference": {
               "raw": "bible+esv.62.2.1",
               "text": "Mark 2:1"
               }
           }]
       }, ...
   ],
   "total": 5
}