Faithlife Developer Center

Getting Started

In order to make requests, OAuth credentials must be obtained by registering an application with Faithlife. 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 use the PLAINTEXT or HMACSHA1 signature methods.

Endpoints

Temporary Credentials URLhttps://auth.faithlife.com/v1/temporarytoken
Authorize URLhttps://auth.faithlife.com/v1/authorize
Access Credentials URLhttps://auth.faithlife.com/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.

Invite

Field Type Required Description
accountIdstringnoAccount to be invited.
inviteIdstringno
userUserno
groupGroupno
emailInviteEmailInviteno

InviteCollection

Field Type Required Description
totalintno
invitesInviteyesList of Invites.
messagestringno

Membership

Field Type Required Description
membershipIdstringyes

EmailInvite

Field Type Required Description
emailstringnoEmail address to send invite to.
emailInviteTokenstringno

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
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
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
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
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"
   }
 ]
}

Get Invites For User

GET /invites

This method lists the current user's pending invites.

The response is an inviteCollection object.

Parameters
offsetintno
limitintno
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
offsetintno
limitintno
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
invitesInviteCollectionno
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

Community API Types

Comment

idstringyes
sourceAccountIdstringno
sourceDestinationIdstringno
textstringyes
urlstringno

Metadata

idstringyes

Note

idstringyes
destinationAccountIdstringno
metadataMetadatanoA collection of metadata.
resourceLocationsResource LocationnoA collection of resource locations.
sourceAccountIdstringno
textstringyes
titlestringyes
urlstringno

Reference

Rawstringyes
Textstringyes

Resource Location

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
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
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
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
}