StagingUsers version v19.4.0
http://github.com/org/folio/mod-users
mod-users stagingUser API
This documents the API calls that can be made to query and manage staging users of the system
/staging-users
Collection of staging-user items.
get
Return a list of staging-users
post
Create a user
get /staging-users
Return a list of staging-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 email=abc@testEmail.com sortBy contactInfo.email - orderBy: (string)
Order by field: field A, field B
- order: (one of desc, asc - default: desc)
Order
- totalRecords: (string - default: auto - pattern: exact|estimated|none|auto)
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none - 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
HTTP status code 200
Returns a list of staging-user items
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Collection of staging users",
"properties": {
"staging_users": {
"description": "List of userdata items",
"type": "array",
"id": "stagingUsersData",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"metadata": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}
},
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records, see https://github.com/folio-org/raml-module-builder#estimated-totalrecords for details"
},
"resultInfo": {
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "resultInfo.schema",
"description": "Faceting of result sets",
"type": "object",
"properties": {
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records"
},
"totalRecordsEstimated": {
"type": "boolean",
"description": "True if totalRecords is an estimation, false if it is the exact number"
},
"totalRecordsRounded": {
"type": "integer",
"description": "The rounded value of totalRecords if totalRecords is an estimation"
},
"responseTime": {
"type": "number",
"description": "Response time"
},
"facets": {
"type": "array",
"description": "Array of facets",
"items": {
"type": "object",
"description": "A facet",
"properties": {
"facetValues": {
"type": "array",
"description": "Array of facet values",
"items": {
"type": "object",
"description": "A facet value",
"properties": {
"count": {
"type": "integer",
"description": "Count of facet values"
},
"value": {
"description": "Value Object"
}
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"description": "Type of facet"
}
},
"additionalProperties": false
}
},
"diagnostics": {
"type": "array",
"description": "Array of diagnostic information",
"items": {
"type": "object",
"description": "Diagnostic information",
"properties": {
"source": {
"type": "string",
"description": "Source reporting the diagnostic information"
},
"code": {
"type": "string",
"description": "Diagnostic Code"
},
"message": {
"type": "string",
"description": "Diagnostic Message"
},
"module": {
"type": "string",
"description": "Module reporting diagnostic information"
},
"recordCount": {
"type": "integer",
"description": "Record Count for diagnostics"
},
"query": {
"type": "string",
"description": "CQL Query associated with results"
}
}
}
}
},
"additionalProperties": false
}
},
"required": [
"users",
"totalRecords"
]
}Example:
{
"staging_users": [
{
"id": "362399c3-dad4-49c5-880a-a65823312065",
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"preferredFirstName": "New Record",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil.1.2@test.com"
},
"preferredEmailCommunication": [
"Support",
"Programs",
"Services"
],
"metadata": {
"createdDate": "2024-10-14T09:40:50.311+00:00",
"createdByUserId": "21457ab5-4635-4e56-906a-908f05e12345",
"updatedDate": "2024-10-14T09:41:50.653+00:00",
"updatedByUserId": "21457ab5-4635-4e56-906a-908f05e12345"
}
}
],
"totalRecords": 1
}
HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP status code 401
Not authorized to perform requested action
Body
Media type: text/plain
Type: any
Example:
unable to list staging-users -- unauthorizedHTTP status code 403
Access denied
Body
Media type: text/plain
Type: any
Example:
Access deniedHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorpost /staging-users
Create a user
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"type": "object",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"metadata": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}Example:
{
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil_new1@test.com"
},
"preferredEmailCommunication": [
"Programs",
"Support",
"Services"
]
}
HTTP status code 201
when new staging user record is created
Headers
- Location: required(string)
URI to the created staging-user item
Body
Media type: application/json
Type: any
Example:
{
"isEmailVerified": false,
"status": "TIER-1",
"externalSystemId": "9eb67301-6f6e-468f-9b1a-6134dc39a684",
"generalInfo": {
"firstName": "test1",
"middleName": "www",
"lastName": "new-record-1"
},
"addressInfo": {
"addressLine0": "123 Main St",
"addressLine1": "Apt 4B",
"city": "Metropolis",
"province": "NY",
"zip": "12345",
"country": "USA"
},
"contactInfo": {
"phone": "555-123456",
"mobilePhone": "555-5678",
"email": "new-record-kapil_new1@test.com"
},
"preferredEmailCommunication": [
"Programs",
"Support",
"Services"
]
}
HTTP status code 400
Bad request
Body
Media type: application/json
Type: any
Media type: text/plain
Type: any
Example:
"unable to add staging-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 staging-users -- unauthorizedHTTP status code 422
Validation error
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"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 administratorput
Update an existing user based on externalSystemId
put /staging-users/{externalSystemId}
Update an existing user based on externalSystemId
URI Parameters
- externalSystemId: required(string)
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Staging User Information Schema",
"description": "A staging user",
"javaName": "StagingUser",
"type": "object",
"properties": {
"id": {
"description": "A globally unique (UUID) identifier for the user",
"type": "string"
},
"isEmailVerified": {
"description": "A flag to determine if a patron is activated.",
"type": "boolean"
},
"minor": {
"description": "An optional flag If true, the user will be assigned to the 'Basic -- Minor (INTERNAL)' patron group upon creation; otherwise if false or null, the 'Remote Non-circulating' group is assigned.",
"type": "boolean"
},
"status": {
"type": "string",
"description": "whether tier-1 or tier-2",
"enum": [
"TIER-1",
"TIER-2"
]
},
"externalSystemId": {
"description": "A unique ID (UUID) that corresponds to an external authority",
"type": "string"
},
"generalInfo": {
"type": "object",
"description": "General info of staging user",
"properties": {
"firstName": {
"type": "string",
"description": "The staging user's given name"
},
"preferredFirstName": {
"type": "string",
"description": "The user's preferred name"
},
"middleName": {
"type": "string",
"description": "The staging user's middle name (if any)"
},
"lastName": {
"type": "string",
"description": "The staging user's surname"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"addressInfo": {
"type": "object",
"description": "Primary address info of staging user",
"properties": {
"addressLine0": {
"type": "string",
"description": "Address, Line 0"
},
"addressLine1": {
"type": "string",
"description": "Address, Line 1"
},
"city": {
"type": "string",
"description": "City name"
},
"province": {
"type": "string",
"description": "Province"
},
"zip": {
"type": "string",
"description": "Zip Code"
},
"country": {
"type": "string",
"description": "Country"
}
},
"additionalProperties": false
},
"contactInfo": {
"type": "object",
"description": "Contact info of staging user",
"properties": {
"phone": {
"type": "string",
"description": "The user's primary phone number"
},
"mobilePhone": {
"type": "string",
"description": "The user's mobile phone number"
},
"email": {
"type": "string",
"description": "The user's email address",
"format": "email"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"preferredEmailCommunication": {
"type": "array",
"description": "Email communication info of staging user",
"items": {
"type": "string",
"enum": [
"Support",
"Programs",
"Services"
]
},
"maxItems": 3,
"uniqueItems": true
},
"metadata": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"type": "string",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"required": [
"generalInfo",
"contactInfo"
],
"additionalProperties": false
}HTTP status code 200
when staging user record is updated
Body
Media type: application/json
Type: any
HTTP status code 400
Bad request
Body
Media type: application/json
Type: any
HTTP status code 404
Staging user with a given externalSystemID not found
Body
Media type: text/plain
Type: any
Example:
Staging user not foundHTTP status code 405
Internal server error, e.g. due to missing externalSystemId in the parameter
Body
Media type: text/plain
Type: any
Example:
the request's HTTP method is not supported by the server or the resourceHTTP status code 422
Validation error
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorput
create a new user or update a existing user with staging user details
put /staging-users/{id}/mergeOrCreateUser
create a new user or update a existing user with staging user details
URI Parameters
- id: required(string)
Query Parameters
- userId: required(string)
User ID
HTTP status code 200
New user merged/created from staging user successfully
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "stagingUser response after merge",
"javaName": "StagingUserMergeResponse",
"type": "object",
"properties": {
"userId": {
"description": "The UUID of the newly merged/created user",
"type": "string"
}
},
"additionalProperties": false
}Example:
{
"userId": "7261ecaae3a74dc68b468e12a70b1aec"
}
HTTP status code 404
Not found
Body
Media type: text/plain
Type: any
HTTP status code 500
Internal error
Body
Media type: text/plain
Type: any