Users API documentation version v1
http://github.com/org/folio/mod-users
mod-users API
This documents the API calls that can be made to query and manage users of the system
/users
Collection of user items.
Return a list of users
Create a user
get /users
Return a list of users
Query Parameters
- query: (string)
A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode active=true sortBy username
- orderBy: (string)
Order by field: field A, field B
- order: (one of desc, asc - default: desc)
Order
- offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
0
- limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response
Example:
10
- facets: (array of )
facets to return in the collection result set, can be suffixed by a count of facet values to return, for example, patronGroup:10 default to top 5 facet values
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 200
Returns a list of user items
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Collection of users",
"properties": {
"users": {
"description": "List of userdata items",
"type": "array",
"id": "usersData",
"items": {
"type": "object",
"$ref": "userdata.json"
}
},
"totalRecords": {
"type": "integer"
},
"resultInfo": {
"$ref": "../resultInfo.schema",
"readonly": true
}
},
"required": [
"users",
"totalRecords"
]
}
Example:
{
"users": [
{
"username": "jhandey",
"id": "7261ecaae3a74dc68b468e12a70b1aec",
"active": true,
"patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
"meta": {
"creation_date": "2016-11-05T0723",
"last_login_date": ""
},
"personal": {
"lastName": "Handey",
"firstName": "Jack",
"middleName": "Michael",
"dateOfBirth": "1965-07-08T00:00:01Z",
"phone": "+1 (212) 567-8912",
"mobilePhone": "+1 (212) 678-9123",
"email": "jhandey@biglibrary.org"
},
"tags": {
"tagList": [
"foo-tag",
"fizz-tag"
]
}
}
],
"totalRecords": 1
}
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
unable to list users -- malformed parameter 'query', syntax error at column 6
HTTP status code 401
Not authorized to perform requested action
Body
Media type: text/plain
Type: any
Example:
unable to list users -- unauthorized
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
post /users
Create a user
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "User Schema",
"description": "A user",
"type": "object",
"properties": {
"username": {
"description": "A unique name belonging to a user. Typically used for login",
"type": "string"
},
"id": {
"description" : "A globally unique (UUID) identifier for the user",
"type": "string"
},
"externalSystemId": {
"description": "An ID that corresponds to an external authority",
"type": "string"
},
"barcode": {
"description": "The library barcode for this user",
"type": "string"
},
"active": {
"description": "A flag to determine if a user can log in, take out loans, etc.",
"type": "boolean"
},
"type": {
"description": "The class of user",
"type": "string"
},
"patronGroup": {
"description": "A UUID corresponding to the group the user belongs to",
"type": "string"
},
"meta": {
"description": "Deprecated",
"type": "object"
},
"proxyFor": {
"description" : "Deprecated",
"type": "array",
"items": {
"type": "string"
}
},
"personal": {
"description": "Personal information about the user",
"type": "object",
"properties": {
"lastName": {
"description": "The user's surname",
"type": "string"
},
"firstName": {
"description": "The user's given name",
"type": "string"
},
"middleName": {
"description": "The user's middle name (if any)",
"type": "string"
},
"email": {
"description": "The user's email address",
"type": "string"
},
"phone": {
"description": "The user's primary phone number",
"type": "string"
},
"mobilePhone": {
"description": "The user's mobile phone number",
"type": "string"
},
"dateOfBirth": {
"type": "string",
"description": "The user's birth date",
"format": "date-time"
},
"addresses": {
"description": "Physical addresses associated with the user",
"type": "array",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"id": {
"description": "A unique id for this address",
"type": "string"
},
"countryId": {
"description": "The country code for this address",
"type": "string"
},
"addressLine1": {
"description": "Address, Line 1",
"type": "string"
},
"addressLine2": {
"description": "Address, Line 2",
"type": "string"
},
"city": {
"description": "City name",
"type": "string"
},
"region": {
"description": "Region",
"type": "string"
},
"postalCode": {
"description": "Postal Code",
"type": "string"
},
"addressTypeId": {
"description": "A UUID that corresponds with an address type object",
"type": "string"
},
"primaryAddress": {
"description": "Is this the user's primary address?",
"type": "boolean"
}
},
"additionalProperties": false
}
},
"preferredContactTypeId": {
"description": "Id of user's preferred contact type",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"lastName"
]
},
"enrollmentDate": {
"description": "The date in which the user joined the organization",
"type": "string",
"format": "date-time"
},
"expirationDate": {
"description": "The date for when the user becomes inactive",
"type": "string",
"format": "date-time"
},
"createdDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"updatedDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"metadata" : {
"type" : "object",
"$ref" : "../metadata.schema"
},
"tags": {
"type" : "object",
"$ref" : "../tags.schema"
}
},
"additionalProperties": false,
"required": [
"id"
]
}
Example:
{
"username": "jhandey",
"id": "7261ecaae3a74dc68b468e12a70b1aec",
"active": true,
"type": "patron",
"patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
"meta": {
"creation_date": "2016-11-05T0723",
"last_login_date": ""
},
"personal": {
"lastName": "Handey",
"firstName": "Jack",
"email": "jhandey@biglibrary.org",
"phone": "2125551212"
},
"tags": {
"tagList": [
"foo-tag",
"fizz-tag"
]
}
}
HTTP status code 201
Returns a newly created item, with server-controlled fields like 'id' populated
Headers
- Location: required (string)
URI to the created user item
Body
Media type: application/json
Type: any
Example:
{
"username": "jhandey",
"id": "7261ecaae3a74dc68b468e12a70b1aec",
"active": true,
"type": "patron",
"patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
"meta": {
"creation_date": "2016-11-05T0723",
"last_login_date": ""
},
"personal": {
"lastName": "Handey",
"firstName": "Jack",
"email": "jhandey@biglibrary.org",
"phone": "2125551212"
},
"tags": {
"tagList": [
"foo-tag",
"fizz-tag"
]
}
}
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to add user -- malformed JSON at 13:3"
HTTP status code 401
Not authorized to perform requested action
Body
Media type: text/plain
Type: any
Example:
unable to create users -- unauthorized
HTTP status code 422
Validation errors
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$ref": "error.schema"
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Entity representing a user
Get a single user
Delete user item with given {userId}
Update user item with given {userId}
get /users/{userId}
Get a single user
URI Parameters
- userId: required (string)
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 200
Returns item with a given ID
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "User Schema",
"description": "A user",
"type": "object",
"properties": {
"username": {
"description": "A unique name belonging to a user. Typically used for login",
"type": "string"
},
"id": {
"description" : "A globally unique (UUID) identifier for the user",
"type": "string"
},
"externalSystemId": {
"description": "An ID that corresponds to an external authority",
"type": "string"
},
"barcode": {
"description": "The library barcode for this user",
"type": "string"
},
"active": {
"description": "A flag to determine if a user can log in, take out loans, etc.",
"type": "boolean"
},
"type": {
"description": "The class of user",
"type": "string"
},
"patronGroup": {
"description": "A UUID corresponding to the group the user belongs to",
"type": "string"
},
"meta": {
"description": "Deprecated",
"type": "object"
},
"proxyFor": {
"description" : "Deprecated",
"type": "array",
"items": {
"type": "string"
}
},
"personal": {
"description": "Personal information about the user",
"type": "object",
"properties": {
"lastName": {
"description": "The user's surname",
"type": "string"
},
"firstName": {
"description": "The user's given name",
"type": "string"
},
"middleName": {
"description": "The user's middle name (if any)",
"type": "string"
},
"email": {
"description": "The user's email address",
"type": "string"
},
"phone": {
"description": "The user's primary phone number",
"type": "string"
},
"mobilePhone": {
"description": "The user's mobile phone number",
"type": "string"
},
"dateOfBirth": {
"type": "string",
"description": "The user's birth date",
"format": "date-time"
},
"addresses": {
"description": "Physical addresses associated with the user",
"type": "array",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"id": {
"description": "A unique id for this address",
"type": "string"
},
"countryId": {
"description": "The country code for this address",
"type": "string"
},
"addressLine1": {
"description": "Address, Line 1",
"type": "string"
},
"addressLine2": {
"description": "Address, Line 2",
"type": "string"
},
"city": {
"description": "City name",
"type": "string"
},
"region": {
"description": "Region",
"type": "string"
},
"postalCode": {
"description": "Postal Code",
"type": "string"
},
"addressTypeId": {
"description": "A UUID that corresponds with an address type object",
"type": "string"
},
"primaryAddress": {
"description": "Is this the user's primary address?",
"type": "boolean"
}
},
"additionalProperties": false
}
},
"preferredContactTypeId": {
"description": "Id of user's preferred contact type",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"lastName"
]
},
"enrollmentDate": {
"description": "The date in which the user joined the organization",
"type": "string",
"format": "date-time"
},
"expirationDate": {
"description": "The date for when the user becomes inactive",
"type": "string",
"format": "date-time"
},
"createdDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"updatedDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"metadata" : {
"type" : "object",
"$ref" : "../metadata.schema"
},
"tags": {
"type" : "object",
"$ref" : "../tags.schema"
}
},
"additionalProperties": false,
"required": [
"id"
]
}
Example:
{
"username": "jhandey",
"id": "7261ecaae3a74dc68b468e12a70b1aec",
"active": true,
"type": "patron",
"patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
"meta": {
"creation_date": "2016-11-05T0723",
"last_login_date": ""
},
"personal": {
"lastName": "Handey",
"firstName": "Jack",
"email": "jhandey@biglibrary.org",
"phone": "2125551212"
},
"tags": {
"tagList": [
"foo-tag",
"fizz-tag"
]
}
}
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"user not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
delete /users/{userId}
Delete user item with given {userId}
URI Parameters
- userId: required (string)
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
HTTP status code 204
Item deleted successfully
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to delete user -- constraint violation"
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"user not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
put /users/{userId}
Update user item with given {userId}
URI Parameters
- userId: required (string)
Query Parameters
- lang: (string - default: en - pattern: [a-zA-Z]{2})
Requested language. Optional. [lang=en]
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "User Schema",
"description": "A user",
"type": "object",
"properties": {
"username": {
"description": "A unique name belonging to a user. Typically used for login",
"type": "string"
},
"id": {
"description" : "A globally unique (UUID) identifier for the user",
"type": "string"
},
"externalSystemId": {
"description": "An ID that corresponds to an external authority",
"type": "string"
},
"barcode": {
"description": "The library barcode for this user",
"type": "string"
},
"active": {
"description": "A flag to determine if a user can log in, take out loans, etc.",
"type": "boolean"
},
"type": {
"description": "The class of user",
"type": "string"
},
"patronGroup": {
"description": "A UUID corresponding to the group the user belongs to",
"type": "string"
},
"meta": {
"description": "Deprecated",
"type": "object"
},
"proxyFor": {
"description" : "Deprecated",
"type": "array",
"items": {
"type": "string"
}
},
"personal": {
"description": "Personal information about the user",
"type": "object",
"properties": {
"lastName": {
"description": "The user's surname",
"type": "string"
},
"firstName": {
"description": "The user's given name",
"type": "string"
},
"middleName": {
"description": "The user's middle name (if any)",
"type": "string"
},
"email": {
"description": "The user's email address",
"type": "string"
},
"phone": {
"description": "The user's primary phone number",
"type": "string"
},
"mobilePhone": {
"description": "The user's mobile phone number",
"type": "string"
},
"dateOfBirth": {
"type": "string",
"description": "The user's birth date",
"format": "date-time"
},
"addresses": {
"description": "Physical addresses associated with the user",
"type": "array",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"id": {
"description": "A unique id for this address",
"type": "string"
},
"countryId": {
"description": "The country code for this address",
"type": "string"
},
"addressLine1": {
"description": "Address, Line 1",
"type": "string"
},
"addressLine2": {
"description": "Address, Line 2",
"type": "string"
},
"city": {
"description": "City name",
"type": "string"
},
"region": {
"description": "Region",
"type": "string"
},
"postalCode": {
"description": "Postal Code",
"type": "string"
},
"addressTypeId": {
"description": "A UUID that corresponds with an address type object",
"type": "string"
},
"primaryAddress": {
"description": "Is this the user's primary address?",
"type": "boolean"
}
},
"additionalProperties": false
}
},
"preferredContactTypeId": {
"description": "Id of user's preferred contact type",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"lastName"
]
},
"enrollmentDate": {
"description": "The date in which the user joined the organization",
"type": "string",
"format": "date-time"
},
"expirationDate": {
"description": "The date for when the user becomes inactive",
"type": "string",
"format": "date-time"
},
"createdDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"updatedDate": {
"description": "Deprecated",
"type": "string",
"format": "date-time"
},
"metadata" : {
"type" : "object",
"$ref" : "../metadata.schema"
},
"tags": {
"type" : "object",
"$ref" : "../tags.schema"
}
},
"additionalProperties": false,
"required": [
"id"
]
}
Example:
{
"username": "jhandey",
"id": "7261ecaae3a74dc68b468e12a70b1aec",
"active": true,
"type": "patron",
"patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
"meta": {
"creation_date": "2016-11-05T0723",
"last_login_date": ""
},
"personal": {
"lastName": "Handey",
"firstName": "Jack",
"email": "jhandey@biglibrary.org",
"phone": "2125551212"
},
"tags": {
"tagList": [
"foo-tag",
"fizz-tag"
]
}
}
HTTP status code 204
Item successfully updated
HTTP status code 400
Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.
Body
Media type: text/plain
Type: any
Example:
"unable to update user -- malformed JSON at 13:4"
HTTP status code 404
Item with a given ID not found
Body
Media type: text/plain
Type: any
Example:
"user not found"
HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator