1. Overview

For a limited set of API clients, the Bookshare API v2 for Membership provides endpoints for Membership Assistant users to manage the membership records of users who are part of their Site. The same conventions and general rules for API use apply here as they do to the public API for Bookshare users.

Membership Assistants are responsible for helping users and organizations get as much content, as easily as possible, from the collection of titles to which they are entitled. This can involve reviewing or updating properties of users or organizations, or reviewing their activity to help them resolve any problems they are having. Many of the endpoints mirror operations that a user might otherwise perform for themselves, such as adding a subscription or updating a user’s preferences.

2. Endpoints

2.1. Membership Assistant - Organizations

Membership Assistant users are able to view, create and update organization accounts.

2.1.1. Create an organization

POST /v2/organizations
Description

Create a new organization, with the properties provided.

Parameters
Form Parameters
Name Description Required Schema Default

organizationName

The name of the organization.

X

String

null

address1

The organization’s street address.

X

String

null

address2

Any extra street address information for the organization.

-

String

null

city

The organization’s city.

X

String

null

state

The organization’s state or province. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada.

-

String

null

country

The organization’s country. The values should be a two-character ISO 3166 alpha-2 country code.

X

String

null

postalCode

The organization’s postal code.

X

String

null

phoneNumber

The organization’s phone number.

-

String

null

website

The organization’s website.

-

String

null

organizationType

Type of organization. List of possible values exists at /v2/organizationTypes.

X

String

null

subscriptionType

Type of organization subscription. List of possible values exists at /v2/subscriptiontypes. If nothing is specified, then the default subscription type for the organization type and site will be used.

-

String

null

site

The site with which the user should be associated. The person submitting the request must be a full administrator. By default, the created user will be associated with the same site as the user submitting the request.

-

String

null

contactFirstName

The primary contact’s first name.

X

String

null

contactLastName

The primary contact’s last name.

X

String

null

contactPhoneNumber

The primary contact’s phone number.

-

String

null

contactTitle

The title of the primary contact.

X

String

null

contactEmailAddress

The primary contact’s email address.

X

String

null
Responses
HTTP Code Message Datatype

201

Organization

Organization

0

Unexpected error

Error
Example HTTP request
POST /v2/organizations HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 399

organizationName=Example+organization&address1=123+Main+Street&address2=&city=SmallTown&state=CA&country=US&postalCode=98765&phoneNumber=123-456-7890&website=exampleorg.com&organizationType=usPublicK12&subscriptionType=organizationPaying&contactFirstName=John&contactLastName=Doe&contactTitle=Manager&contactPhoneNumber=789-123-456&contactEmailAddress=primarycontact%40exampleorg.com&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 1258

{
  "allows" : null,
  "organizationName" : "Example organization",
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "SmallTown",
    "state" : "CA",
    "country" : "US",
    "postalCode" : "98765"
  },
  "phoneNumber" : "123-456-7890",
  "webSite" : "exampleorg.com",
  "organizationType" : "usPublicK12",
  "organizationId" : 12345,
  "subscriptionType" : "organizationPaying",
  "site" : "bookshare",
  "primaryContact" : {
    "allows" : null,
    "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
    "name" : {
      "firstName" : "John",
      "lastName" : "Doe",
      "middle" : null,
      "prefix" : null,
      "suffix" : null,
      "links" : [ ]
    },
    "emailAddress" : "primarycontact@exampleorg.com",
    "allowAdultContent" : false,
    "phoneNumber" : "789-123-456",
    "language" : "eng",
    "roles" : [ "primaryContact", "sponsor" ],
    "site" : "bookshare",
    "hasAgreement" : false,
    "locked" : false,
    "deleted" : false,
    "canDownload" : false,
    "title" : "Manager",
    "links" : [ ]
  },
  "hasOrgAgreement" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/organizations/12345"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations' -i -X POST \
    -d 'organizationName=Example+organization&address1=123+Main+Street&address2=&city=SmallTown&state=CA&country=US&postalCode=98765&phoneNumber=123-456-7890&website=exampleorg.com&organizationType=usPublicK12&subscriptionType=organizationPaying&contactFirstName=John&contactLastName=Doe&contactTitle=Manager&contactPhoneNumber=789-123-456&contactEmailAddress=primarycontact%40exampleorg.com&api_key=abcdefg'

2.1.2. Create a member for an organization

POST /v2/organizations/{organizationId}/members
Description

Create a new user account for an organization member, with the properties provided.

Parameters
Path Parameters
Name Description Required Schema Default

organizationId

ID of the organization.

X

String

null
Form Parameters
Name Description Required Schema Default

firstName

The user’s first name.

X

String

null

lastName

The user’s last name.

X

String

null

dateOfBirth

The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'.

X

String

null

grade

User’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades

X

String

null

username

Username for the user.

-

String

null

password

The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number.

-

String

null

disabilityType

The types of disabilities involved. Enter each disability type as a separate instance of this parameter.

-

enum [visual, learning, physical, nonspecific]

null

proofSource

The organization who has verified the given disability. Only applies if disabilityType is submitted.

-

enum [schoolVerified, faxed, nls, learningAlly, partner, hadley, marrakeshPartner]

[schoolVerified]

disabilityPlan

The disability plan for the user. Enter each disability plan as a separate instance of this parameter.

-

enum [iep, section504]

null
Responses
HTTP Code Message Datatype

201

User Account response

User Account

0

Unexpected error

Error
Example HTTP request
POST /v2/organizations/12345/members HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 174

firstName=Jane&lastName=Doe&dateOfBirth=2009-06-28&grade=5&username=testuser&disabilityType=learning&proofSource=partner&disabilityPlan=iep&password=testuser1&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD
Content-Type: application/json
Content-Length: 1234

{
  "allows" : null,
  "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
  "name" : {
    "firstName" : "Jane",
    "lastName" : "Doe",
    "middle" : null,
    "prefix" : null,
    "suffix" : null,
    "links" : [ ]
  },
  "emailAddress" : null,
  "allowAdultContent" : false,
  "phoneNumber" : null,
  "language" : "eng",
  "roles" : [ "organizationMember", "organizationMember" ],
  "site" : "bookshare",
  "hasAgreement" : false,
  "locked" : false,
  "deleted" : false,
  "canDownload" : true,
  "address" : null,
  "guardian" : null,
  "dateOfBirth" : "2009-06-28",
  "grade" : "6",
  "proofOfDisabilityStatus" : "active",
  "subscriptionStatus" : "active",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
  }, {
    "rel" : "subscriptions",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
  }, {
    "rel" : "disabilities",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations/12345/members' -i -X POST \
    -d 'firstName=Jane&lastName=Doe&dateOfBirth=2009-06-28&grade=5&username=testuser&disabilityType=learning&proofSource=partner&disabilityPlan=iep&password=testuser1&api_key=abcdefg'

2.1.3. Get organization information

GET /v2/organizations/{organizationId}
Description

Ask for an organization’s information. This includes name, address, type and other properties.

Parameters
Path Parameters
Name Description Required Schema Default

organizationId

ID of the organization.

X

String

null
Responses
HTTP Code Message Datatype

200

Organization

Organization

0

Unexpected error

Error
Example HTTP request
GET /v2/organizations/12345?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1259

{
  "allows" : null,
  "organizationName" : "Example organization",
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "SmallTown",
    "state" : "CA",
    "country" : "US",
    "postalCode" : "98765"
  },
  "phoneNumber" : "123-456-7890",
  "webSite" : "exampleorg.com",
  "organizationType" : "libraryPublic",
  "organizationId" : 12345,
  "subscriptionType" : "organizationPaying",
  "site" : "bookshare",
  "primaryContact" : {
    "allows" : null,
    "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
    "name" : {
      "firstName" : "John",
      "lastName" : "Doe",
      "middle" : null,
      "prefix" : null,
      "suffix" : null,
      "links" : [ ]
    },
    "emailAddress" : "primarycontact@exampleorg.com",
    "allowAdultContent" : false,
    "phoneNumber" : "789-123-456",
    "language" : "eng",
    "roles" : [ "primaryContact", "sponsor" ],
    "site" : "bookshare",
    "hasAgreement" : false,
    "locked" : false,
    "deleted" : false,
    "canDownload" : true,
    "title" : "Manager",
    "links" : [ ]
  },
  "hasOrgAgreement" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/organizations/12345"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations/12345?api_key=abcdefg' -i -X GET

2.1.4. Get a list of members in an organization

GET /v2/organizations/{organizationId}/members
Description

As a membership assistant, get a list of members in an organization.

Parameters
Path Parameters
Name Description Required Schema Default

organizationId

ID of the organization.

X

String

null
Query Parameters
Name Description Required Schema Default

start

If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request.

-

String

null

limit

Maximum number of results to include. The maximum allowed is 100.

-

Integer

10

sortOrder

Primary sorting field.

-

enum [lastName, firstName, district, school, grade, birthDate]

[lastName]

direction

Direction for sorting.

-

enum [asc, desc]

[asc]

grade

The grade of users to limit results to. Values should be from ONIX codelist 77 for US grades, BIC for UK grades.

-

String

null

sponsorList

Filter options for limiting results to a specific subset of members.

-

enum [allMembers, individualMembers, orgMembers]

null
Responses
HTTP Code Message Datatype

201

User Account List response

List of User Accounts

0

Unexpected error

Error
Example HTTP request
GET /v2/organizations/1001/members?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1519

{
  "limit" : 10,
  "next" : null,
  "totalResults" : 1,
  "allows" : null,
  "userAccounts" : [ {
    "allows" : null,
    "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
    "name" : {
      "firstName" : "Jane",
      "lastName" : "Doe",
      "middle" : null,
      "prefix" : null,
      "suffix" : null,
      "links" : [ ]
    },
    "emailAddress" : null,
    "allowAdultContent" : false,
    "phoneNumber" : null,
    "language" : "eng",
    "roles" : [ "organizationMember" ],
    "site" : "bookshare",
    "hasAgreement" : false,
    "locked" : false,
    "deleted" : false,
    "canDownload" : false,
    "address" : null,
    "guardian" : null,
    "dateOfBirth" : "2009-06-28",
    "grade" : "6",
    "proofOfDisabilityStatus" : "active",
    "subscriptionStatus" : "active",
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
    }, {
      "rel" : "subscriptions",
      "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
    }, {
      "rel" : "disabilities",
      "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
    } ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/organizations/12345/members?api_key=abcdefg"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations/1001/members?api_key=abcdefg' -i -X GET

2.1.5. Update organization information

PUT /v2/organizations/{organizationId}
Description

Update an organization’s information. This includes name, address, and other properties.

Parameters
Path Parameters
Name Description Required Schema Default

organizationId

ID of the organization.

X

String

null
Form Parameters
Name Description Required Schema Default

organizationName

The name of the organization.

-

String

null

address1

The organization’s street address.

-

String

null

address2

Any extra street address information for the organization.

-

String

null

city

The organization’s city.

-

String

null

state

The organization’s state or province. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada.

-

String

null

country

The organization’s country of residence. The values should be a two-character ISO 3166 alpha-2 country code.

-

String

null

postalCode

The organization’s postal code of residence.

-

String

null

phoneNumber

The organization’s phone number.

-

String

null

website

The organization’s website.

-

String

null

riderSigned

True if the organization has signed the confidentiality rider.

-

Boolean

null

agreementSigned

True if the organization has signed the organizational membership agreement.

-

Boolean

null

canDownloadNIMAC

True if the organization can download NIMAC-sourced books, which has special meaning to US school members.

-

Boolean

null

canCreateUsers

True if the organization is authorized to add members and verify proof of disability.

-

Boolean

null

suspended

True if the organization is suspended.

-

Boolean

null

unreported

True if the organization is ignored in reports.

-

Boolean

null

numBooksAllowed

Number of books allowed per month.

-

enum [100, 200, 300, unlimited]

null

notes

Notes about the organization for other administrators to see.

-

String

null
Responses
HTTP Code Message Datatype

200

Organization

Organization

0

Unexpected error

Error
Example HTTP request
PUT /v2/organizations/12345 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 74

organizationName=New+Organization+Name&numBooksAllowed=300&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1258

{
  "allows" : null,
  "organizationName" : "New Organization Name",
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "SmallTown",
    "state" : "CA",
    "country" : "US",
    "postalCode" : "98765"
  },
  "phoneNumber" : "123-456-7890",
  "webSite" : "exampleorg.com",
  "organizationType" : "usPublicK12",
  "organizationId" : 12345,
  "subscriptionType" : "organizationPaying",
  "site" : "bookshare",
  "primaryContact" : {
    "allows" : null,
    "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
    "name" : {
      "firstName" : "John",
      "lastName" : "Doe",
      "middle" : null,
      "prefix" : null,
      "suffix" : null,
      "links" : [ ]
    },
    "emailAddress" : "primarycontact@exampleorg.com",
    "allowAdultContent" : false,
    "phoneNumber" : "789-123-456",
    "language" : "eng",
    "roles" : [ "primaryContact", "sponsor" ],
    "site" : "bookshare",
    "hasAgreement" : false,
    "locked" : false,
    "deleted" : false,
    "canDownload" : true,
    "title" : "Manager",
    "links" : [ ]
  },
  "hasOrgAgreement" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/organizations/12345"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations/12345' -i -X PUT \
    -d 'organizationName=New+Organization+Name&numBooksAllowed=300&api_key=abcdefg'

2.1.6. Update primary contact for an organization

PUT /v2/organizations/{organizationId}/primaryContact
Description

Update an organization’s primary contact.

Parameters
Path Parameters
Name Description Required Schema Default

organizationId

ID of the organization.

X

String

null
Form Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the new primary contact.

X

String

null
Responses
HTTP Code Message Datatype

200

Sponsor response

Organization Sponsor

0

Unexpected error

Error
Example HTTP request
PUT /v2/organizations/12345/primaryContact HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 51

userIdentifier=sponsor%40school.org&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 763

{
  "allows" : null,
  "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
  "name" : {
    "firstName" : "Org",
    "lastName" : "Sponsor",
    "middle" : null,
    "prefix" : null,
    "suffix" : null,
    "links" : [ ]
  },
  "emailAddress" : "sponsor@school.org",
  "allowAdultContent" : false,
  "phoneNumber" : "123-456-7890",
  "language" : "eng",
  "roles" : [ "sponsor", "primaryContact" ],
  "site" : "bookshare",
  "hasAgreement" : false,
  "locked" : false,
  "deleted" : false,
  "canDownload" : false,
  "title" : "SponsorTitle",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/organizations/12345/primaryContact' -i -X PUT \
    -d 'userIdentifier=sponsor%40school.org&api_key=abcdefg'

2.2. Membership Assistant - User Accounts

Membership Assistant users are able to view and update the user accounts for those individual members who are associated with the Assistant's site.

2.2.1. Create a proof of disability

POST /v2/accounts/{userIdentifier}/pod
Description

Create a new record of a disability for an existing user, with its proof source.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

disabilityType

The type of disability involved.

X

enum [visual, learning, physical, nonspecific]

null

proofSource

The organization who has verified the given disability.

X

enum [schoolVerified, faxed, nls, learningAlly, partner, hadley, marrakeshPartner]

null
Responses
HTTP Code Message Datatype

201

User disabilities list response

List of User Proofs of Disability

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 53

disabilityType=visual&proofSource=nls&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod
Content-Type: application/json
Content-Length: 268

{
  "disabilities" : [ {
    "disabilityType" : "visual",
    "proofSource" : "nls"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod' -i -X POST \
    -d 'disabilityType=visual&proofSource=nls&api_key=abcdefg'

2.2.2. Create a subscription

POST /v2/accounts/{userIdentifier}/subscriptions
Description

Create a new membership subscription for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

startDate

Date that the user subscription starts. The value should be formatted as 'YYYY-MM-DD'.

X

date

null

endDate

Date that the user subscription ends. The value should be formatted as 'YYYY-MM-DD'.

-

date

null

userSubscriptionType

Type of user subscription. List of possible values exists at /v2/subscriptiontypes.

X

String

null

numBooksAllowed

Number of books allowed.

-

Integer

null

downloadTimeframe

The timeframe for download limits on a user subscription

-

enum [monthly, entireSubscription]

null

notes

Notes about the user subscription.

-

String

null
Responses
HTTP Code Message Datatype

201

User subscription response

User Subscription

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 158

startDate=2025-07-14&endDate=2026-07-15&userSubscriptionType=individualPaying&notes=Sample+Notes&numBooksAllowed=100&downloadTimeframe=monthly&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1
Content-Type: application/json
Content-Length: 509

{
  "subscriptionId" : 1,
  "startDate" : "2025-07-14T00:00:00Z",
  "endDate" : "2026-07-15T00:00:00Z",
  "userSubscriptionType" : {
    "name" : "individualPaying",
    "description" : "Paying Individual"
  },
  "downloadTimeframe" : {
    "name" : "monthly"
  },
  "numBooksAllowed" : 150,
  "notes" : "Sample Notes",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions' -i -X POST \
    -d 'startDate=2025-07-14&endDate=2026-07-15&userSubscriptionType=individualPaying&notes=Sample+Notes&numBooksAllowed=100&downloadTimeframe=monthly&api_key=abcdefg'

2.2.3. Create a new signed agreement

POST /v2/accounts/{userIdentifier}/agreements
Description

Create a new signed agreement record for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

agreementType

The type of agreement.

X

enum [individual, volunteer, sponsor]

null

dateSigned

The date of agreement signing.

X

String

null

printName

The print name of the signing user signing the agreement.

X

String

null

signedByLegalGuardian

True if the was signed by legal guardian.

-

String

null
Responses
HTTP Code Message Datatype

201

User Agreements response

User Signed Agreement

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 112

agreementType=individual&dateSigned=2018-05-01&printName=Sally+Smith&signedByLegalGuardian=false&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements
Content-Type: application/json
Content-Length: 452

{
  "agreementId" : "2342342",
  "agreementType" : "individual",
  "dateSigned" : "2018-05-01T00:00:00Z",
  "dateExpired" : null,
  "printName" : "Sally Smith",
  "username" : "sally@smith.org",
  "recordingUser" : "john@smith.com",
  "signedByLegalGuardian" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements' -i -X POST \
    -d 'agreementType=individual&dateSigned=2018-05-01&printName=Sally+Smith&signedByLegalGuardian=false&api_key=abcdefg'

2.2.4. Create a user account

POST /v2/accounts
Description

Create a new user account, with the properties provided.

Parameters
Form Parameters
Name Description Required Schema Default

firstName

The user’s first name.

X

String

null

lastName

The user’s last name.

X

String

null

phoneNumber

The user’s phone number.

-

String

null

emailAddress

The user’s email address. This value will also be used as the username.

X

String

null

address1

The user’s street address of residence.

X

String

null

address2

Any extra street address information for the user.

-

String

null

city

The user’s city of residence.

X

String

null

state

The user’s state or province of residence. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada.

-

String

null

country

The user’s country of residence. The values should be a two-character ISO 3166 alpha-2 country code.

X

String

null

postalCode

The user’s postal code of residence.

X

String

null

guardianFirstName

The user’s guardian’s first name (if user is a minor).

-

String

null

guardianLastName

The user’s guardian’s last name (if user is a minor).

-

String

null

dateOfBirth

The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'.

-

String

null

language

The user’s preferred language. The value should be a three-character ISO 639-2 alpha-3 language code

-

String

null

allowAdultContent

True if the user should be allowed to find and download titles marked with adult content. If a birth date is provided, this defaults to true; if no birth date is provided, this defaults to false.

-

Boolean

null

site

The site with which the user should be associated. The person submitting the request must be a full administrator. By default, the created user will be associated with the same site as the user submitting the request.

-

String

null

role

The user’s primary role. If not provided, the user will be given the individual member role.

-

enum [individual, volunteer, trustedVolunteer, collectionAssistant, membershipAssistant]

null

password

The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number.

-

String

null
Responses
HTTP Code Message Datatype

201

User Account response

User Account

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 264

firstName=Sally&lastName=Smith&address1=123+Main+Street&address2=&city=Smalltown&state=MN&country=US&postalCode=54321&emailAddress=sally%40smith.org&role=individual&phoneNumber=123-456-7890&language=eng&allowAdultContent=true&dateOfBirth=1990-01-02&api_key=abcdefg
Example HTTP response
HTTP/1.1 201 Created
Location: https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD
Content-Type: application/json
Content-Length: 1391

{
  "allows" : [ "PUT" ],
  "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
  "name" : {
    "firstName" : "Sally",
    "lastName" : "Smith",
    "middle" : null,
    "prefix" : null,
    "suffix" : null,
    "links" : [ ]
  },
  "emailAddress" : "sally@smith.org",
  "allowAdultContent" : true,
  "phoneNumber" : "123-456-7890",
  "language" : "eng",
  "roles" : [ "individual" ],
  "site" : "bookshare",
  "hasAgreement" : false,
  "locked" : false,
  "deleted" : false,
  "canDownload" : false,
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "Smalltown",
    "state" : "MN",
    "country" : "US",
    "postalCode" : "54321"
  },
  "guardian" : null,
  "dateOfBirth" : "1990-01-02",
  "grade" : "",
  "proofOfDisabilityStatus" : "missing",
  "subscriptionStatus" : "missing",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
  }, {
    "rel" : "subscriptions",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
  }, {
    "rel" : "disabilities",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts' -i -X POST \
    -d 'firstName=Sally&lastName=Smith&address1=123+Main+Street&address2=&city=Smalltown&state=MN&country=US&postalCode=54321&emailAddress=sally%40smith.org&role=individual&phoneNumber=123-456-7890&language=eng&allowAdultContent=true&dateOfBirth=1990-01-02&api_key=abcdefg'

2.2.5. Remove a proof of disability

DELETE /v2/accounts/{userIdentifier}/pod/{disabilityType}
Description

Remove a proof of disability for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null

disabilityType

The type of disability involved.

X

enum [visual, learning, physical, nonspecific]

null
Responses
HTTP Code Message Datatype

200

User disabilities list response

List of User Proofs of Disability

0

Unexpected error

Error
Example HTTP request
DELETE /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod/visual HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15

api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 272

{
  "disabilities" : [ {
    "disabilityType" : "physical",
    "proofSource" : "faxed"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod/visual' -i -X DELETE \
    -d 'api_key=abcdefg'

2.2.6. Expire a signed agreement

POST /v2/accounts/{userIdentifier}/agreements/{id}/expired
Description

Expire a signed agreement.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the agreement owner.

X

String

null

id

The ID of the agreement to expire.

X

String

null
Responses
HTTP Code Message Datatype

201

User Agreements response

User Signed Agreement

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements/2342342/expired HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 15

api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 470

{
  "agreementId" : "2342342",
  "agreementType" : "individual",
  "dateSigned" : "2018-05-01T00:00:00Z",
  "dateExpired" : "2019-05-01T00:00:00Z",
  "printName" : "Sally Smith",
  "username" : "sally@smith.org",
  "recordingUser" : "john@smith.com",
  "signedByLegalGuardian" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements/2342342/expired' -i -X POST \
    -d 'api_key=abcdefg'

2.2.7. Get reading lists for a given user

GET /v2/accounts/{userIdentifier}/lists
Description

Request the list of reading lists that a given user is able to see. These could be private lists, shared lists, or organization lists that the user is subscribed to.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user who the reading lists are being retrieved for.

X

String

null
Query Parameters
Name Description Required Schema Default

start

If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of 'next' that was returned from the previous request.

-

String

null

limit

Maximum number of results to include. The maximum allowed is 100.

-

Integer

10

sortOrder

Primary sorting field.

-

enum [name, owner, dateUpdated]

[name]

direction

Direction for sorting.

-

enum [asc, desc]

[asc]
Responses
HTTP Code Message Datatype

200

Reading List collection response

List of My Reading Lists

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/lists?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 807

{
  "limit" : 10,
  "next" : null,
  "totalResults" : 1,
  "allows" : [ "POST" ],
  "lists" : [ {
    "allows" : null,
    "readingListId" : 1004,
    "name" : "A Reading List",
    "description" : "A list of favorite books",
    "access" : "private",
    "owner" : "John Smith",
    "titleCount" : 5,
    "memberCount" : 0,
    "assignedBy" : null,
    "subscription" : null,
    "dateUpdated" : null,
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.bookshare.org/v2/lists/1004"
    }, {
      "rel" : "titles",
      "href" : "https://api.bookshare.org/v2/lists/1004/titles"
    } ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/lists?api_key=abcdefg"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/lists?api_key=abcdefg' -i -X GET

2.2.8. Get proof of disability

GET /v2/accounts/{userIdentifier}/pod
Description

Get the list of disabilities for an existing user, with their proof source.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Responses
HTTP Code Message Datatype

200

User disabilities list response

List of User Proofs of Disability

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 340

{
  "disabilities" : [ {
    "disabilityType" : "visual",
    "proofSource" : "faxed"
  }, {
    "disabilityType" : "physical",
    "proofSource" : "faxed"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod?api_key=abcdefg' -i -X GET

2.2.9. Get subscription types

GET /v2/subscriptiontypes
Description

Get the list of subscription types available to users of the Membership Assistant’s site.

Parameters
Responses
HTTP Code Message Datatype

200

User Subscription Type list response

List of User Subscription Types

0

Unexpected error

Error
Example HTTP request
GET /v2/subscriptiontypes?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 486

{
  "userSubscriptionTypes" : [ {
    "name" : "individualPaying",
    "description" : "Paying Individual"
  }, {
    "name" : "individualComplimentary",
    "description" : "Complimentary Subscription"
  }, {
    "name" : "individualNda",
    "description" : "Bookshare.org NDA year-long"
  }, {
    "name" : "organizationPaying",
    "description" : "Paying Organization"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/subscriptiontypes"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/subscriptiontypes?api_key=abcdefg' -i -X GET

2.2.10. Get subscriptions

GET /v2/accounts/{userIdentifier}/subscriptions
Description

Get the list of existing membership subscriptions for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Responses
HTTP Code Message Datatype

200

User subscription list response

List of User Subscriptions

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 584

{
  "userSubscriptions" : [ {
    "subscriptionId" : 1,
    "startDate" : "2025-07-14T00:00:00Z",
    "endDate" : "2026-07-15T00:00:00Z",
    "userSubscriptionType" : {
      "name" : "individualPaying",
      "description" : "Paying Individual"
    },
    "downloadTimeframe" : {
      "name" : "monthly"
    },
    "numBooksAllowed" : 150,
    "notes" : "Sample Notes",
    "links" : [ ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions?api_key=abcdefg' -i -X GET

2.2.11. Get recommendation profile

GET /v2/accounts/{userIdentifier}/recommendationProfile
Description

Get a particular user’s choices of properties that guide title recommendations.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Responses
HTTP Code Message Datatype

200

Recommendation Profile

Recommendation Profile

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 666

{
  "allows" : [ "PUT" ],
  "includeGlobalCollection" : false,
  "includedAuthors" : [ "Mark Twain" ],
  "excludedAuthors" : [ ],
  "includedContentWarnings" : null,
  "excludedContentWarnings" : [ ],
  "includedCategories" : [ {
    "name" : "Humor",
    "description" : "Humor",
    "categoryType" : "Bookshare",
    "code" : null,
    "links" : [ ]
  } ],
  "excludedCategories" : [ ],
  "narratorGender" : "female",
  "narratorType" : "human",
  "readingAge" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile?api_key=abcdefg' -i -X GET

2.2.12. Get a list of signed agreements

GET /v2/accounts/{userIdentifier}/agreements
Description

Get the list of signed agreements for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Responses
HTTP Code Message Datatype

200

User Agreements List response

List of User Signed Agreements

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements?api_key=abcdefg HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 557

{
  "allows" : null,
  "signedAgreements" : [ {
    "agreementId" : "2342342",
    "agreementType" : "individual",
    "dateSigned" : "2018-05-01T00:00:00Z",
    "dateExpired" : "2019-05-01T00:00:00Z",
    "printName" : "Sally Smith",
    "username" : "sally@smith.org",
    "recordingUser" : "john@smith.com",
    "signedByLegalGuardian" : false,
    "links" : [ ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/agreements?api_key=abcdefg' -i -X GET \
    -H 'Content-Type: application/x-www-form-urlencoded'

2.2.13. Get single subscription

GET /v2/accounts/{userIdentifier}/subscriptions/{subscriptionId}
Description

Get an existing membership subscriptions for an existing user by unique id.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null

subscriptionId

The unique identifier of a user membership subscription.

X

String

null
Responses
HTTP Code Message Datatype

200

User subscription response

User Subscription

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 509

{
  "subscriptionId" : 1,
  "startDate" : "2025-07-14T00:00:00Z",
  "endDate" : "2026-07-15T00:00:00Z",
  "userSubscriptionType" : {
    "name" : "individualPaying",
    "description" : "Paying Individual"
  },
  "downloadTimeframe" : {
    "name" : "monthly"
  },
  "numBooksAllowed" : 150,
  "notes" : "Sample Notes",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1?api_key=abcdefg' -i -X GET

2.2.14. Get user account preferences

GET /v2/accounts/{userIdentifier}/preferences
Description

Request the set of account preferences associated with a specific user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Responses
HTTP Code Message Datatype

200

User Account preferences response

My Account Preferences

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 507

{
  "allows" : [ "PUT" ],
  "allowAdultContent" : false,
  "showAllBooks" : false,
  "showRecommendations" : true,
  "language" : "eng",
  "format" : {
    "formatId" : "DAISY",
    "name" : "DAISY"
  },
  "brailleGrade" : "contracted",
  "useUeb" : true,
  "brailleFormat" : "refreshable",
  "brailleCellLineWidth" : 40,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences?api_key=abcdefg' -i -X GET

2.2.15. Look up user account

GET /v2/accounts/{userIdentifier}
Description

Search for a user by their unique user identifier. Membership Assistants are only allowed to search for users associated with the same Site as them.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user to search for.

X

String

null
Responses
HTTP Code Message Datatype

200

User Account response

User Account

0

Unexpected error

Error
Example HTTP request
GET /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg HTTP/1.1
Host: api.bookshare.org
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1388

{
  "allows" : [ "PUT" ],
  "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
  "name" : {
    "firstName" : "Sally",
    "lastName" : "Smith",
    "middle" : null,
    "prefix" : null,
    "suffix" : null,
    "links" : [ ]
  },
  "emailAddress" : "sally@smith.org",
  "allowAdultContent" : false,
  "phoneNumber" : "123-456-7890",
  "language" : "eng",
  "roles" : [ "individual" ],
  "site" : "bookshare",
  "hasAgreement" : true,
  "locked" : false,
  "deleted" : false,
  "canDownload" : true,
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "Smalltown",
    "state" : "MN",
    "country" : "US",
    "postalCode" : "54321"
  },
  "guardian" : null,
  "dateOfBirth" : "1990-01-02",
  "grade" : "",
  "proofOfDisabilityStatus" : "active",
  "subscriptionStatus" : "active",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
  }, {
    "rel" : "subscriptions",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
  }, {
    "rel" : "disabilities",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD?api_key=abcdefg' -i -X GET

2.2.16. Create a reading list for a given user

POST /v2/accounts/{userIdentifier}/lists
Description

Create an empty reading list that will be owned by the given user, with the properties provided.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user who the reading lists are being retrieved for.

X

String

null
Form Parameters
Name Description Required Schema Default

name

The name of the reading list

X

String

null

access

Visibility of the list

X

enum [private, shared, org]

null

description

The description of the reading list

-

String

null
Responses
HTTP Code Message Datatype

200

Reading List Response

Reading List

0

Unexpected error

Error
Example HTTP request
POST /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/lists HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 87

name=A+Reading+List&description=A+list+of+favorite+books&access=private&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 474

{
  "allows" : null,
  "readingListId" : 1004,
  "name" : "A Reading List",
  "description" : "A list of favorite books",
  "access" : "private",
  "owner" : "John Smith",
  "titleCount" : 5,
  "memberCount" : 0,
  "assignedBy" : null,
  "subscription" : null,
  "dateUpdated" : null,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/lists/1004"
  }, {
    "rel" : "titles",
    "href" : "https://api.bookshare.org/v2/lists/1004/titles"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/lists' -i -X POST \
    -d 'name=A+Reading+List&description=A+list+of+favorite+books&access=private&api_key=abcdefg'

2.2.17. Update recommendation profile

PUT /v2/accounts/{userIdentifier}/recommendationProfile
Description

Update a particular user’s choices of properties that guide how title recommendations.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

includeGlobalCollection

If true, the recommendation system should include titles from the Bookshare Global Collection. This defaults to false for members of private label sites.

-

Boolean

false

narratorType

Limit results to those with audio artifacts that are voiced by the given narrator type. If format is not also specified, it will default to search for DAISY_AUDIO or DAISY_2_AUDIO.

-

enum [human, tts]

null

narratorGender

Limit results to those with audio artifacts that are voiced by the given narrator type. If format is not also specified, it will default to search for DAISY_AUDIO or DAISY_2_AUDIO.

-

enum [female, male, otherNonBinary]

null

readingAge

Limit results to those with a specific reading age.

-

Integer

null

excludedContentWarnings

Limit recommendations to titles that do not match any of the given content warning flags.

-

enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated]

null

includedContentWarnings

Deprecated - Limit recommendations to titles that match at least one of the given content warning flags.

-

enum [contentWarning, sex, violence, drugs, language, intolerance, adult, unrated]

null

excludedCategories

Limit recommendations to titles that do not match any of the given Bookshare categories.

-

String

null

includedCategories

Limit recommendations to titles that match at least one of these Bookshare categories.

-

String

null

excludedAuthors

Limit recommendations to titles that do not match any of the given authors.

-

String

null

includedAuthors

Limit recommendations to titles that match at least one of these authors.

-

String

null
Responses
HTTP Code Message Datatype

200

Recommendation Profile

Recommendation Profile

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 248

includeGlobalCollection=true&includedAuthors=Isaac+Asimov&includedAuthors=Arthur+Clarke&excludedAuthors=Orson+Scott+Card&excludedContentWarnings=intolerance&excludedCategories=Humor&narratorGender=male&narratorType=tts&readingAge=12&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 711

{
  "allows" : [ "PUT" ],
  "includeGlobalCollection" : true,
  "includedAuthors" : [ "Isaac Asimov", "Arthur Clarke" ],
  "excludedAuthors" : [ "Orson Scott Card" ],
  "includedContentWarnings" : null,
  "excludedContentWarnings" : [ "intolerance" ],
  "includedCategories" : [ ],
  "excludedCategories" : [ {
    "name" : "Humor",
    "description" : "Humor",
    "categoryType" : "Bookshare",
    "code" : null,
    "links" : [ ]
  } ],
  "narratorGender" : "male",
  "narratorType" : "tts",
  "readingAge" : 12,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/recommendationProfile' -i -X PUT \
    -d 'includeGlobalCollection=true&includedAuthors=Isaac+Asimov&includedAuthors=Arthur+Clarke&excludedAuthors=Orson+Scott+Card&excludedContentWarnings=intolerance&excludedCategories=Humor&narratorGender=male&narratorType=tts&readingAge=12&api_key=abcdefg'

2.2.18. Update user account preferences

PUT /v2/accounts/{userIdentifier}/preferences
Description

Update the preference settings for a specific user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

allowAdultContent

True if the user is allowed to find and download titles marked with adult content. This defaults to false for members who are minors.

-

Boolean

null

showAllBooks

True if books marked as low quality should be included in search results. The default is false.

-

Boolean

false

showRecommendations

True if the user would like to opt-in to receiving personalized recommendations. The default is true.

-

Boolean

true

language

Language preference of the user. The value should be a three-character ISO 639-2 alpha-3 language code.

-

String

null

format

Preferred format when downloading a title. Can be used by clients to suggest a title’s format when that format is available.

-

enum [DAISY, DAISY_AUDIO, BRF, EPUB3, PDF, DOCX]

null

brailleGrade

The preferred Braille grade (uncontracted or contracted) when downloading generated BRF.

-

enum [uncontracted, contracted]

null

brailleFormat

The format of the Braille (refreshable or embossable) that will be created when downloading generated BRF. An updated Braille format must be submitted with an updated compatible Braille cell line width in order to be accepted.

-

enum [refreshable, embossable]

null

brailleCellLineWidth

The maximum number of cells to create per line when generating BRF. For refreshable Braille, the allowed values are 18, 20, 32, 40, 70, or 80. For embossable Braille, the allowed values are 28 and 40. An updated Braille cell line width must be submitted with an updated compatible Braille format in order to be accepted.

-

Integer

null

useUeb

True if English-language books should use UEB, rather than EBAE when downloading generated BRF. The default is false.

-

Boolean

false
Responses
HTTP Code Message Datatype

200

User Account preferences response

My Account Preferences

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 189

brailleGrade=grade_2&brailleFormat=refreshable&useUeb=true&brailleCellLineWidth=40&allowAdultContent=true&showAllBooks=true&format=BRF&language=spa&showRecommendations=false&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 502

{
  "allows" : [ "PUT" ],
  "allowAdultContent" : true,
  "showAllBooks" : true,
  "showRecommendations" : false,
  "language" : "spa",
  "format" : {
    "formatId" : "BRF",
    "name" : "BRF"
  },
  "brailleGrade" : "contracted",
  "useUeb" : true,
  "brailleFormat" : "refreshable",
  "brailleCellLineWidth" : 40,
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/preferences' -i -X PUT \
    -d 'brailleGrade=grade_2&brailleFormat=refreshable&useUeb=true&brailleCellLineWidth=40&allowAdultContent=true&showAllBooks=true&format=BRF&language=spa&showRecommendations=false&api_key=abcdefg'

2.2.19. Update user password

PUT /v2/accounts/{userIdentifier}/password
Description

Update the password for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null
Form Parameters
Name Description Required Schema Default

password

The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number.

X

String

null
Responses
HTTP Code Message Datatype

200

Status messages

Status

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/password HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 34

password=Password1&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 63

{
  "key" : "SUCCESS",
  "messages" : [ "Password Changed." ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/password' -i -X PUT \
    -d 'password=Password1&api_key=abcdefg'

2.2.20. Update a proof of disability

PUT /v2/accounts/{userIdentifier}/pod/{disabilityType}
Description

Update the proof source for a disability for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null

disabilityType

The type of disability involved.

X

enum [visual, learning, physical, nonspecific]

null
Form Parameters
Name Description Required Schema Default

proofSource

The organization who has verified the given disability.

X

enum [schoolVerified, faxed, nls, learningAlly, partner, hadley, marrakeshPartner]

null
Responses
HTTP Code Message Datatype

201

User disabilities list response

List of User Proofs of Disability

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod/visual HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 35

proofSource=partner&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 272

{
  "disabilities" : [ {
    "disabilityType" : "visual",
    "proofSource" : "partner"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod/visual' -i -X PUT \
    -d 'proofSource=partner&api_key=abcdefg'

2.2.21. Update a subscription

PUT /v2/accounts/{userIdentifier}/subscriptions/{subscriptionId}
Description

Update an existing membership subscription for an existing user.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user.

X

String

null

subscriptionId

The unique identifier of a user membership subscription

X

String

null
Form Parameters
Name Description Required Schema Default

startDate

Date that the user subscription starts. The value should be formatted as 'YYYY-MM-DD'.

X

date

null

endDate

Date that the user subscription ends. The value should be formatted as 'YYYY-MM-DD'.

-

date

null

userSubscriptionType

Type of user subscription. List of possible values exists at /v2/subscriptiontypes.

X

String

null

numBooksAllowed

Number of books allowed.

-

Integer

null

downloadTimeframe

The timeframe for download limits on a user subscription.

-

enum [monthly, entireSubscription]

null

notes

Notes about the user subscription.

-

String

null
Responses
HTTP Code Message Datatype

200

User subscription response

User Subscription

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 158

startDate=2025-07-14&endDate=2026-07-15&userSubscriptionType=individualPaying&notes=Sample+Notes&numBooksAllowed=100&downloadTimeframe=monthly&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 509

{
  "subscriptionId" : 1,
  "startDate" : "2025-07-14T00:00:00Z",
  "endDate" : "2026-07-15T00:00:00Z",
  "userSubscriptionType" : {
    "name" : "individualPaying",
    "description" : "Paying Individual"
  },
  "downloadTimeframe" : {
    "name" : "monthly"
  },
  "numBooksAllowed" : 150,
  "notes" : "Sample Notes",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions/1' -i -X PUT \
    -d 'startDate=2025-07-14&endDate=2026-07-15&userSubscriptionType=individualPaying&notes=Sample+Notes&numBooksAllowed=100&downloadTimeframe=monthly&api_key=abcdefg'

2.2.22. Update a user account

PUT /v2/accounts/{userIdentifier}
Description

Update a new user account, with the properties provided.

Parameters
Path Parameters
Name Description Required Schema Default

userIdentifier

The unique identifying username or userAccountId of the user to update.

X

String

null
Form Parameters
Name Description Required Schema Default

firstName

The user’s first name.

-

String

null

lastName

The user’s last name.

-

String

null

phoneNumber

The user’s phone number.

-

String

null

emailAddress

The user’s email address. This value will also be used as the username.

-

String

null

address1

The user’s street address of residence.

-

String

null

address2

Any extra street address information for the user.

-

String

null

city

The user’s city of residence.

-

String

null

state

The user’s state or province of residence. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the user’s country. This field is only relevant for subdivisions of the US and Canada.

-

String

null

country

The user’s country of residence. The values should be a two-character ISO 3166 alpha-2 country code.

-

String

null

postalCode

The user’s postal code of residence.

-

String

null

guardianFirstName

The user’s guardian’s first name (if user is a minor).

-

String

null

guardianLastName

The user’s guardian’s last name (if user is a minor).

-

String

null

dateOfBirth

The user’s date of birth. The value should be formatted as 'YYYY-MM-DD'.

-

String

null

language

The user’s preferred language. The value should be a three-character ISO 639-2 alpha-3 language code

-

String

null

allowAdultContent

True if the user should be allowed to find and download titles marked with adult content. If a birth date is provided, this defaults to true; if no birth date is provided, this defaults to false.

-

Boolean

null

site

The site with which the user should be associated. The person submitting the request must be a full administrator. By default, the created user will be associated with the same site as the user submitting the request.

-

String

null

role

The user’s primary role. If not provided, the user will be given the individual member role.

-

enum [individual, volunteer, trustedVolunteer, collectionAssistant, membershipAssistant]

null

password

The user’s password. It must be from 8-32 characters long, and contain at least one letter and one number.

-

String

null
Responses
HTTP Code Message Datatype

201

User Account response

User Account

0

Unexpected error

Error
Example HTTP request
PUT /v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.bookshare.org
Content-Length: 52

lastName=Test&dateOfBirth=1990-01-02&api_key=abcdefg
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1387

{
  "allows" : [ "PUT" ],
  "userAccountId" : "AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD",
  "name" : {
    "firstName" : "Unit",
    "lastName" : "Test",
    "middle" : null,
    "prefix" : null,
    "suffix" : null,
    "links" : [ ]
  },
  "emailAddress" : "unit@test.org",
  "allowAdultContent" : true,
  "phoneNumber" : "123-456-7890",
  "language" : "spa",
  "roles" : [ "individual" ],
  "site" : "bookshare",
  "hasAgreement" : false,
  "locked" : false,
  "deleted" : false,
  "canDownload" : true,
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "SmallTown",
    "state" : "CA",
    "country" : "US",
    "postalCode" : "98765"
  },
  "guardian" : null,
  "dateOfBirth" : "1990-01-02",
  "grade" : "5",
  "proofOfDisabilityStatus" : "missing",
  "subscriptionStatus" : "missing",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD"
  }, {
    "rel" : "subscriptions",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/subscriptions"
  }, {
    "rel" : "disabilities",
    "href" : "https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD/pod"
  } ]
}
Example Curl request
$ curl 'https://api.bookshare.org/v2/accounts/AP5xvS9bztz6ybiqkSIXp7VQQZPihRGp1Y1pVYTTaVXg2dpVrzDsNm5Q3uRxGS7Pl929nBh58YBD' -i -X PUT \
    -d 'lastName=Test&dateOfBirth=1990-01-02&api_key=abcdefg'

3. Models

3.1. Address

Field Name Description Type Format Nullable

address1

The primary street address.

String

address2

Extra street address information, if any.

String

city

A city name.

String

state

The state or province or other subdivision of the country. The value will be an ISO-3166-2 subdivision code for the associated country.

String

country

The country code. The value will be an ISO 3166 alpha-2 country code.

String

postalCode

The postal code, if any, for the given address.

String

3.2. Category

Field Name Description Type Format Nullable

name

Identifier of the subject category

String

description

Descriptive name of the subject category, localized when possible to the user’s locale.

String

categoryType

Category type, Bookshare or BISAC

String

enum [Bookshare, BISAC]

code

Code that represents the category, may be null.

String

links

List of Link

3.3. Content Warning Values

Enum Values

contentWarning

sex

violence

drugs

language

intolerance

adult

unrated

3.4. Download Timeframe

Field Name Description Type Format Nullable

name

Descriptive name of the timeframe for download limits.

String

enum [monthly, entireSubscription]

3.5. Error

Field Name Description Type Format Nullable

key

String

messages

List of String

3.6. Format

Field Name Description Type Format Nullable

formatId

Unique identifier of the format.

String

name

Descriptive name of the format, suitable for display.

String
Field Name Description Type Format Nullable

rel

A relationship name

String

href

An absolute or relative URI for a resource request

String

3.8. My Account Preferences

Field Name Description Type Format Nullable

allowAdultContent

True if the user is allowed to find and download titles marked with adult content. This defaults to false for members who are minors.

Boolean

showAllBooks

True if books marked as low quality should be included in search results. The default is false.

Boolean

showRecommendations

True if the user would like to opt-in to receiving personalized recommendations. The default is true.

Boolean

language

Language preference of the user. The value will be a three-character ISO 639-2 alpha-3 language code.

String

format

Format

brailleGrade

The preferred Braille grade (uncontracted or contracted) when downloading generated BRF.

String

enum [uncontracted, contracted]

useUeb

True if English-language books should use UEB, rather than EBAE when downloading generated BRF. The default is false.

Boolean

brailleFormat

The format of the Braille (refreshable or embossable) that will be created when downloading generated BRF.

String

enum [refreshable, embossable]

brailleCellLineWidth

The maximum number of cells to create per line when generating BRF. For refreshable Braille, the allowed values are 18, 20, 32, 40, 70, or 80. For embossable Braille, the allowed values are 28 and 40.

Integer

links

List of Link

allows

Operations allowed: PUT

List of String

enum [PUT]

3.9. Name

Field Name Description Type Format Nullable

firstName

First name of the individual or entity

String

lastName

Last name of the individual or entity

String

middle

Middle name, or initial, if any

String

prefix

Prefix, if any, such as Mr., Mrs., Dr.

String

suffix

Suffix, if any, such as Jr., Sr., III

String

links

List of Link

3.10. Organization

Field Name Description Type Format Nullable

organizationName

The name of the organization

String

organizationId

Unique identifier of the organization

String

address

Address

phoneNumber

The organization’s phone number.

String

webSite

The organization’s website.

String

organizationType

The type of organization.

String

subscriptionType

The organization’s subscription type.

String

site

The organization’s site.

String

primaryContact

Organization Sponsor

hasOrgAgreement

True if current signed organizational membership agreement is on file.

Boolean

links

List of Link

allows

Operations allowed: PUT

List of String

enum [PUT]

3.11. Reading List

Field Name Description Type Format Nullable

readingListId

Unique identifier of the reading list

String

name

Name given by the owner

String

description

Description of the list given by the owner

String

owner

Display name of the owner

String

titleCount

Number of titles contained in this reading list

Integer

access

Visibility of the list

String

enum [private, shared, org]

memberCount

Number of organization members assigned to this reading list

Integer

assignedBy

If the current user is a member of the the list, the display name of the user who assigned them

String

subscriberCount

Number of users subscribed in this reading list

Integer

dateUpdated

Date that the reading list was last updated

Date

date-time

allows

Operations allowed: PUT = edit metadata

List of String

enum [PUT]

links

List of Link

3.12. List of My Reading Lists

Field Name Description Type Format Nullable

totalResults

The number of results found that match the search criteria

Integer

next

Token that can be used as the 'start' value to retrieve another group of results

String

limit

Maximum number of results included in this set

Integer

lists

List of Reading List User View

allows

Operations allowed: POST = create a new list

List of String

enum [POST]

links

List of Link

3.13. Reading List Subscription

Field Name Description Type Format Nullable

enabled

User is subscribed to this reading list

Boolean

allows

Operations allowed: PUT = subscribe or unsubscribe

List of String

enum [PUT]

links

List of Link

3.14. Reading List User View

Field Name Description Type Format Nullable

readingListId

Unique identifier of the reading list

String

name

Name given by the owner

String

description

Description of the list given by the owner

String

owner

Display name of the owner

String

titleCount

Number of titles contained in this reading list

Integer

access

Visibility of the list

String

enum [private, shared, org, public]

memberCount

Number of organization members assigned to this reading list

Integer

assignedBy

If the current user is a member of the the list, the display name of the user who assigned them

String

subscription

Reading List Subscription

dateUpdated

Date that the reading list was last updated

Date

date-time

allows

Operations allowed: PUT = edit metadata

List of String

enum [PUT]

links

List of Link

3.15. Recommendation Profile

Field Name Description Type Format Nullable

includeGlobalCollection

True if the recommendation system should suggest titles from the Bookshare Global Collection. This defaults to false for members of private label sites.

Boolean

includedAuthors

Limit results to titles that match at least one of the given authors.

List of String

excludedAuthors

Limit results to titles that match none of the given authors.

List of String

includedCategories

Limit results to titles that match at least one of the given Bookshare categories.

List of Category

excludedCategories

Limit results to titles that match none of the given Bookshare categories.

List of Category

includedContentWarnings

Deprecated - Limit results to titles that match at least one of the given content warnings.

List of content_warning_values

excludedContentWarnings

Limit results to titles that match none of the given content warnings.

List of content_warning_values

narratorGender

Limit results to the given narrator’s gender.

String

enum [male, female, otherNonBinary]

X

narratorType

Limit results to the given source of speech.

String

enum [tts, human]

X

readingAge

Limit results to titles that include the given reading age.

Integer

allows

Operations allowed: PUT

List of String

enum [PUT]

links

List of Link
Field Name Description Type Format Nullable

name

Name

userAccountId

Unique identifier of the user account

String

title

The sponsor’s title.

String

emailAddress

The sponsor’s email address.

String

phoneNumber

The sponsor’s preferred phone number.

String

language

Language preference of the sponsor. The value will be a three-character ISO 639-2 alpha-3 language code

String

allowAdultContent

True if the sponsor is allowed to find and download titles marked with adult content.

Boolean

roles

The roles assigned to the user. These define some of the boundaries on features available to the user.

List of String

site

The site with which the user is associated. This will be used to define what titles are available to the user, since titles are also designated with an associated site.

String

hasAgreement

True if current signed agreement is on file.

Boolean

locked

True if sponsor account is locked.

Boolean

deleted

True if sponsor account is deleted.

Boolean

canDownload

True if sponsor account can download titles.

Boolean

links

List of Link

allows

Operations allowed: PUT

List of String

enum [PUT]

3.17. Status

Field Name Description Type Format Nullable

key

String

messages

List of String

X

3.18. User Account

Field Name Description Type Format Nullable

name

Name

userAccountId

Unique identifier of the user account

String

emailAddress

The user’s email address. This also serves as the username.

String

address

Address

guardian

Name

dateOfBirth

The user’s date of birth. The value will be formatted as 'YYYY-MM-DD'.

String

grade

The user’s current grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades.

String

phoneNumber

The user’s preferred phone number.

String

language

Language preference of the user. The value will be a three-character ISO 639-2 alpha-3 language code

String

allowAdultContent

True if the user is allowed to find and download titles marked with adult content.

Boolean

roles

The roles assigned to the user. These define some of the boundaries on features available to the user.

List of String

site

The site with which the user is associated. This will be used to define what titles are available to the user, since titles are also designated with an associated site.

String

proofOfDisabilityStatus

Status of proof of disability.

String

enum [active, missing]

subscriptionStatus

Status of subscription.

String

enum [active, expired, missing]

hasAgreement

True if current signed agreement is on file.

Boolean

locked

True if user account is locked.

Boolean

deleted

True if user account is deleted.

Boolean

canDownload

True if user account can download titles.

Boolean

links

List of Link

allows

Operations allowed: PUT

List of String

enum [PUT]

3.19. List of User Accounts

Field Name Description Type Format Nullable

totalResults

The number of results found that match the search criteria

Integer

next

Token that can be used as the 'start' value to retrieve another group of results

String

userAccounts

List of User Account

allows

Operations allowed: POST = create new organization member

List of String

enum [POST]

links

List of Link

3.20. User Proof of Disability

Field Name Description Type Format Nullable

disabilityType

The type of disability.

String

proofSource

The organization who has verified the given disability.

String

3.21. List of User Proofs of Disability

Field Name Description Type Format Nullable

disabilities

List of user proofs of disability

List of User Proof of Disability

allows

Operations allowed: POST = add new disability proof, DELETE = remove a disability proof, PUT = update a disability proof

List of String

links

List of Link

3.22. User Signed Agreement

Field Name Description Type Format Nullable

agreementId

The ID of the agreement.

String

agreementType

The type of signed agreement.

String

enum [individual, volunteer, sponsor]

dateSigned

The date of agreement signing.

String

dateExpired

The date of agreement expiration.

String

printName

The print name of the signing user signing the agreement.

String

username

The username of the signed agreement owner.

String

recordingUser

The username of the recording user.

String

signedByLegalGuardian

True if the agreement was signed by legal guardian.

Boolean

3.23. List of User Signed Agreements

Field Name Description Type Format Nullable

signedAgreements

List of user signed agreements

List of User Signed Agreement

allows

Operations allowed: None

List of String

links

List of Link

3.24. User Subscription

Field Name Description Type Format Nullable

subscriptionId

Unique identifier of the user subscription

String

startDate

Date that the user subscription starts

Date

date-time

endDate

Date that the user subscription ends

Date

date-time

userSubscriptionType

User Subscription Type

numBooksAllowed

Number of books allowed

Integer

downloadTimeframe

Download Timeframe

notes

Notes about the user subscription

String

links

List of Link

3.25. List of User Subscriptions

Field Name Description Type Format Nullable

totalResults

The number of user subscriptions found that match the search criteria

Integer

next

Token that can be used as the 'start' value to retrieve another group of results

String

limit

Maximum number of results included in this set

Integer

userSubscriptions

List of user subscriptions

List of User Subscription

allows

Operations allowed: None

List of String

links

List of Link

3.26. User Subscription Type

Possible values at /v2/subscriptiontypes

Field Name Description Type Format Nullable

name

Unique descriptive name of the user subscription type

String

description

Description of the user subscription type

String

3.27. List of User Subscription Types

Field Name Description Type Format Nullable

userSubscriptionTypes

List of subscription types

List of User Subscription Type

links

List of Link