Faithlife Developer Center

Getting Started

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

Overview

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/

Authentication

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

Requests may only use the PLAINTEXT signature method over SSL.

Endpoints

Temporary Credentials URLhttps://auth.logos.com/oauth/v1/temporarytoken
Authorize URLhttps://auth.logos.com/oauth/v1/authorize
Access Credentials URLhttps://auth.logos.com/oauth/v1/accesstoken
Warning: All curl examples omit the OAuth header from the request. Real requests musts contain the header. Here is a full example where token and secret values should be appropriately interpolated based upon registration details obtained from Logos.
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}\""

Rate Limiting

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

Accounts API Types

Avatar URLs

Field Type Required Description
avatarUrlstringno
avatarUrlLargestringno

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.

Note: The client is responsible for converting between UTC and the user's local time zone.

Group

Field Type Required Description
aliasstringno
avatarUrlsAvatar Urlsno
citystringno
countryAbbrevstringno
descriptionstringno
emailstringno
expirationDateDateno
formattedAddressstringno
groupIdstringyes
isPinnedboolno
kindstringno
latitudedoubleno
longitudedoubleno
namestringno
organizationUrlstringno
phonestringno
preferredMembershipKindstringno
privacystringno
rawLocationstringno
shortDescriptionstringno
startDateDateno
stateAbbrevstringno
timeZonestringno
tokenstringno

User

Field Type Required Description
aliasstringyesUser's display name.
avatarUrlsAvatar Urlsno
birthDayintno
birthMonthintno
birthYearintno
dayPhonestringno
denominationstringno
descriptionstringno
emailstringno
eveningPhonestringno
genderstringno
homePageUrlstringno
idstringyes
isMarriedboolno
isSolicitableboolno
locationstringno
namestringyesUsers's real name
organizationstringno
organizationUrlstringno
shortDescriptionstringno
titlestringno
tokenstringnoA token that may be used in some routes in place of an id, intended to be more human readable.

Accounts API

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
Field Type Required Description
idsstringnoA comma delimited list of user id strings
qstringnoFree-form search text
offsetintno
limitintno

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
Field Type Required Description
namestringyes
privacystringyes
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
Field Type Required Description
idsstringnoA comma delimited list of group id strings
qstringnoFree-form search text
offsetintno
limitintno

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
Field Type Required Description
offsetintno
limitintno
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"
   }
 ]
}

Community API Types

Comment

Field Type Required Description
idstringyes
sourceAccountIdstringno
sourceDestinationIdstringno
textstringyes
urlstringno

Metadata

Field Type Required Description
idstringyes

Note

Field Type Required Description
idstringyes
destinationAccountIdstringno
metadataMetadatanoA collection of metadata.
resourceLocationsResource LocationnoA collection of resource locations.
sourceAccountIdstringno
textstringyes
titlestringyes
urlstringno

Reference

Field Type Required Description
Rawstringyes
Textstringyes

Resource Location

Field Type Required Description
referenceReferenceno
resourcestringyes
offsetstringno
selectionLengthstringno
versionstringno

Community Api

Create Comment

This method posts a comment to an account.

The response is a comment object.

POST /comments
Parameters
Field Type Required Description
destinationAccountIdstringyes
sourceAccountIdstringyes
textstringyes
urlstringno
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
Field Type Required Description
offsetintno
limitintno
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
Field Type Required Description
offsetintno
limitintno
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
}