Faithlife
Sign in
Sign in

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

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

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

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

Community API Types

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

Community Api

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
}