User Data Store API

User Data Store provides a RESTful API which is used for interacting with the service.

The generated REST API documentation in deployed User Data Store:

http[s]://[host]:[port]/user-data-store/swagger-ui/index.html

Published RESTful API

Following endpoints are published in User Data Store RESTful API:

Document API

GET /documents - Fetch documents
POST /admin/documents - Create a document
PUT /admin/documents/{documentId} - Update a document
DELETE /admin/documents - Delete documents

Photo API

GET /photos - Fetch photos
POST /admin/photos - Create a photo
PUT /admin/photo/{photoId} - Update a photo
DELETE /admin/photos - Delete photos
POST /admin/photos/import - Import photos synchronously
POST /admin/photos/import/csv - Import photos asynchronously from CSV

Attachment API

GET /attachments - Fetch attachments
POST /admin/attachments - Create an attachment
PUT /admin/attachments/{attachmentId} - Update an attachment
DELETE /admin/attachments - Delete attachments

Claims API

GET /claims - Fetch claims
POST /admin/claims - Create claims
PUT /admin/claims - Update claims
DELETE /admin/claims - Delete claims

User Claims API (Deprecated)

This REST API is deprecated, see Swagger for usage information.

GET /private/user-claims - Fetch user claims
POST /public/user-claims - Create or update user claims
DELETE /public/user-claims - Delete user claims

Error Handling

User Data Store uses following format for error response body, accompanied by an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down), following status codes may be returned:

Status	HTTP Code	Description
OK	200	No issue
ERROR	400	Issue with a request format, or issue of the business logic
ERROR	401	Unauthorized
ERROR	409	Request could not be processed on the server

All error responses that are produced by the User Data Store have the following body:

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "An error message"
  }
}

status - OK, ERROR
code - ERROR_GENERIC
message - Message that describes certain error.

Authentication

Access to the REST API is authenticated. See chapter Setting Up REST Service Credentials for configuring access to the REST API.

Use HTTP Basic authentication to access the REST API, for example:

Authorization: Basic YWRtaW46YWRtaW4=

The username and password is a Base-64 encoded string in the format username:password.

The following paths require a ROLE_WRITE authority:

/admin/** - supported REST API for User Data Store
/public/** - deprecated REST API for user claims

The remainder of the REST API paths require a ROLE_READ authority.

Documents REST API

get /documents Fetch Documents

Fetch documents for a user.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of fetched documents.
`documentId`	`String`	Optional document identifier to allow fetching a specific document.

Response

{
  "status": "OK",
  "responseObject": {
    "documents": [
      {
        "id": "e6eea62b-274b-4c6a-81a8-5bbc75811863",
        "userId": "user1",
        "documentType": "profile",
        "dataType": "claims",
        "documentDataId": null,
        "externalId": null,
        "documentData": "...",
        "attributes": {},
        "timestampCreated": "2024-06-20T14:45:51.568024",
        "timestampLastUpdated": null
      }
    ]
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: 'e6eea62b-274b-4c6a-81a8-5bbc75811863'"
  }
}

post /admin/documents Create a Document

Create a document with optional photos and attachments.

Request

Headers:
- Authorization: Basic ...

{
  "requestObject": {
    "userId": "user1",
    "documentType": "profile",
    "dataType": "claims",
    "documentDataId": null,
    "externalId": null,
    "documentData": "...",
    "attributes": {
       "attribute1": "value1"
    },
    "photos": [
      {
        "photoType": "person",
        "photoData": "...",
        "externalId": null
      }
    ],
    "attachments": [
      {
        "attachmentType": "binary_base64",
        "attachmentData": "...",
        "externalId": null
      }
    ]
  }
}

Request Params

Parameter	Type	Description
`userId`*	`String`	User identifier of document owner.
`documentType`*	`String`	One of `profile`, `personal_id`, `passport`, `drivers_license`, `payment_card`, `loyalty`, `photo`.
`dataType`*	`String`	One of `claims`, `jwt`, `vc`, `image_base64`, `binary_base64`, `url`.
`documentDataId`	`String`	Optional identifier of the data stored in the document (e.g. ID card number).
`externalId`	`String`	Optional external identifier of the document (e.g. identifier used in the bank system).
`documentData`*	`String`	Document data. Use `{}` for empty data.
`attributes`*	`Map<String, Object>`	Attributes containing metadata for the document. Use `{}` for empty attributes.
`photos`	`List<EmbeddedPhotoCreateRequest>`	Optional list of photos which are created together with the document. See POST /admin/photos.
`attachments`	`List<EmbeddedAttachmentCreateRequest>`	Optional list of attachments which are created together with the document. See POST /admin/attachments

Response

{
  "status": "OK",
  "responseObject": {
    "id": "541d5681-245e-48ab-ad4d-3da8a363c923",
    "documentDataId": null,
    "photos": [
      {
        "id": "e6eea62b-274b-4c6a-81a8-5bbc75811863"
      }
    ],
    "attachments": [
      {
        "id": "fd8dbaf3-af64-43c7-b439-24ca79025b20"
      }
    ]
  }
}

put /admin/documents/{documentId} Update a Document

Update a document.

Request

Headers:
- Authorization: Basic ...

Path Params

Param	Type	Description
`documentId`*	`String`	Document identifier.

{
  "requestObject": {
    "userId": "user1",
    "documentType": "profile",
    "dataType": "claims",
    "documentDataId": null,
    "externalId": null,
    "documentData": "...",
    "attributes": {
       "attribute1": "value1"
    }
  }
}

Request Params

Parameter	Type	Description
`userId`*	`String`	User identifier of document owner.
`documentType`*	`String`	One of `profile`, `personal_id`, `passport`, `drivers_license`, `payment_card`, `loyalty`, `photo`.
`dataType`*	`String`	One of `claims`, `jwt`, `vc`, `image_base64`, `binary_base64`, `url`.
`documentDataId`	`String`	Optional identifier of the data stored in the document (e.g. ID card number).
`externalId`	`String`	Optional external identifier of the document (e.g. identifier used in the bank system).
`documentData`*	`String`	Document data. Use `{}` for empty data.
`attributes`*	`Map<String, Object>`	Attributes containing metadata for the document. Use `{}` for empty attributes.

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: '8ab06a8d-b850-4259-9756-52ed44514b1'"
  }
}

delete /admin/documents Delete Documents

Delete documents.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of documents to be deleted.
`documentId`	`String`	Optional document identifier to allow deleting a specific document.

Response

{
  "status": "OK"
}

Photos REST API

get /photos Fetch photos

Fetch photos for a user.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of fetched photos.
`documentId`*	`String`	Document identifier of document related to the photos.

Response

{
  "status": "OK",
  "responseObject": {
    "photos": [
      {
        "id": "c55b1970-a336-49d4-8067-7aa32d64eebe",
        "userId": null,
        "documentId": "49c6e850-900e-4d90-bdc8-d9bb47e44384",
        "externalId": null,
        "photoType": "person",
        "photoData": "...",
        "timestampCreated": "2024-06-20T16:06:39.313191",
        "timestampLastUpdated": null
      }
    ]
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: '8ab06a8d-b850-4259-9756-52ed44514b1'"
  }
}

post /admin/photos Create a Photo

Create a photo.

Request

Headers:
- Authorization: Basic ...

{
  "requestObject": {
    "userId": "user1",
    "documentId": "c55b1970-a336-49d4-8067-7aa32d64eebe",
    "photoType": "person",
    "photoData": "...",
    "externalId": null
  }
}

Request Params

Parameter	Type	Description
`userId`*	`String`	User identifier of document owner.
`documentId`*	`String`	Identifier of the related document.
`photoType`*	`String`	One of `person`, `document_front_side`, `document_back_side`, `person_with_document`.
`photoData`*	`String`	Base-64 encoded photo data.
`externalId`	`String`	Optional external identifier of the photo (e.g. identifier used in the bank system).

Response

{
  "status": "OK",
  "responseObject": {
    "id": "e42c8432-6971-419d-9a23-1c4042d91e24",
    "documentId": "c55b1970-a336-49d4-8067-7aa32d64eebe"
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "User reference not valid, ID: 'user1'"
  }
}

put /admin/photos/{photoId} Update a Photo

Update a photo.

Request

Headers:
- Authorization: Basic ...

Path Params

Param	Type	Description
`photoId`	`String`	Photo identifier.

{
  "requestObject": {
    "photoType": "person",
    "photoData": "...",
    "externalId": null
  }
}

Request Params

Parameter	Type	Description
`photoType`*	`String`	One of `person`, `document_front_side`, `document_back_side`, `person_with_document`.
`photoData`*	`String`	Base-64 encoded photo data.
`externalId`	`String`	Optional external identifier of the photo (e.g. identifier used in the bank system).

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Photo not found, ID: 'e42c8432-6971-419d-9a23-1c4042d91e24'"
  }
}

delete /admin/photos Delete Photos

Delete photos.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of deleted photos.
`documentId`	`String`	Optional document identifier to allow deleting photos for a specific document.

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: '49c6e850-900e-4d90-bdc8-d9bb47e44384'"
  }
}

post /admin/photos/import Import Photos

Import photos synchronously.

Request

Headers:
- Authorization: Basic ...

{
  "requestObject": {
    "photos": [
      {
        "userId": "user123",
        "photoDataType": "raw",
        "photoType": "person",
        "photoData": "http://myserver.com/photos/photo123.png"
      },
      {
        "userId": "user456",
        "photoDataType": "base64",
        "photoType": "person",
        "photoData": "http://myserver.com/photos/photo456.txt"
      },
      {
        "userId": "user789",
        "photoDataType": "base64_inline",
        "photoType": "person",
        "photoData": "FIwUe..."
      }
    ]
  }
}

Request Params

Parameter	Type	Description
`userId`*	`String`	User identifier of document owner.
`photoDataType`*	`String`	Photo data type: `raw` (base-64 encoding done by service), `base64` (no additional encoding) or `base64_inline` (data received directly in request).
`photoType`*	`String`	One of `person`, `document_front_side`, `document_back_side`, `person_with_document`.
`photoData`*	`String`	Photo file or URL location, or base-64 encoded photo data in case of `base64_inline` data type

Response

{
  "status": "OK",
  "responseObject": {
    "photos": [
      {
        "userId": "user123",
        "photoType": "person",
        "documentId": "b24777a3-4577-4e25-845d-40099800df25",
        "photoId": "c8165989-4683-45a5-b1ba-a6693f001471",
        "imported": true,
        "error": null
      },
      {
        "userId": "user456",
        "photoType": "person",
        "documentId": "bde71b05-c153-47ed-a536-52e961f1d895",
        "photoId": "d9577a5f-58a2-4ee3-87db-6f96c5bc6389",
        "imported": true,
        "error": null
      },
      {
        "userId": "user789",
        "photoType": "person",
        "documentId": "bad12ae6-0321-4a63-84b7-f6a4c7ed7748",
        "photoId": "bc2c9a84-6db4-4de3-b1d7-7f2a730733a1",
        "imported": true,
        "error": null
      }
    ]
  }
}

post /admin/photos/import/csv Import Photos from CSV

Import photos synchronously from CSV.

Request

Headers:
- Authorization: Basic ...

{
  "importPaths": [
    "http://myserver.com/photos/import1.csv",
    "http://myserver.com/photos/import2.csv"
  ]
}

Request Params

Parameter	Type	Description
`importPaths`*	`List<String>`	List of paths to CSV files to import data from (either file paths or HTTP URIs).

The photos can be imported in raw format:

user123,raw,person,http://myserver.com/photos/photo123.png
user456,raw,person,http://myserver.com/photos/photo456.png

The photos can also be imported in base64 format:

user123,base64,person,http://myserver.com/photos/photo123.txt
user456,base64,person,http://myserver.com/photos/photo456.txt

The photos can also be imported as inline data in base64_inline format:

user123,base64_inline,person,FOKHjk...
user456,base64_inline,person,WeqIsA...

Response

{
  "status": "OK",
}

Attachments REST API

get /attachments Fetch attachments

Fetch attachments for a user.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of fetched attachments.
`documentId`*	`String`	Document identifier of document related to the attachments.

Response

{
  "status": "OK",
  "responseObject": {
    "attachments": [
      {
        "id": "c55b1970-a336-49d4-8067-7aa32d64eebe",
        "userId": null,
        "documentId": "49c6e850-900e-4d90-bdc8-d9bb47e44384",
        "externalId": null,
        "attachmentType": "binary_base64",
        "attachmentData": "...",
        "timestampCreated": "2024-06-20T16:06:39.313191",
        "timestampLastUpdated": null
      }
    ]
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: '8ab06a8d-b850-4259-9756-52ed44514b1'"
  }
}

post /admin/attachments Create an Attachment

Create an attachment.

Request

Headers:
- Authorization: Basic ...

{
  "requestObject": {
    "userId": "user1",
    "documentId": "c55b1970-a336-49d4-8067-7aa32d64eebe",
    "attachmentType": "binary_base64",
    "attachmentData": "...",
    "externalId": null
  }
}

Request Params

Parameter	Type	Description
`userId`*	`String`	User identifier of document owner.
`documentId`*	`String`	Identifier of the related document.
`attachmentType`*	`String`	One of `text`, `image_base64`, `binary_base64`.
`attachmentData`*	`String`	Base-64 encoded attachment data.
`externalId`	`String`	Optional external identifier of the attachment (e.g. identifier used in the bank system).

Response

{
  "status": "OK",
  "responseObject": {
    "id": "e42c8432-6971-419d-9a23-1c4042d91e24",
    "documentId": "c55b1970-a336-49d4-8067-7aa32d64eebe"
  }
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "User reference not valid, ID: 'user1'"
  }
}

put /admin/attachments/{attachmentId} Update an Attachment

Update an attachment.

Request

Headers:
- Authorization: Basic ...

Path Params

Param	Type	Description
`attachmentId`	`String`	Attachment identifier.

{
  "requestObject": {
    "attachmentType": "binary_base64",
    "attachmentData": "...",
    "externalId": null
  }
}

Request Params

Parameter	Type	Description
`attachmentType`*	`String`	One of `text`, `image_base64`, `binary_base64`.
`attachmentData`*	`String`	Base-64 encoded attachment data.
`externalId`	`String`	Optional external identifier of the attachment (e.g. identifier used in the bank system).

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Attachment not found, ID: '7ae0eef7-d266-4662-9c20-749e42f69f1b'"
  }
}

delete /admin/attachments Delete Attachments

Delete attachments.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of deleted attachments.
`documentId`	`String`	Optional document identifier to allow deleting attachments for a specific document.

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Document not found, ID: '49c6e850-900e-4d90-bdc8-d9bb47e44384'"
  }
}

Claims REST API

get /claims Fetch Claims

Fetch claims for a user.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of fetched claims.
`claim`	`String`	Optional claim name for fetching individual claim values.

Response

{
  "status": "OK",
  "responseObject": {
    "claim1": "value1"
  }
}

post /admin/claims Create Claims

Create a claim.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of claims.

{
  "claim1": "value1"
}

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "ALREADY_EXISTS",
    "message": "Claims for user 'user1' already exist"
  }
}

put /admin/claims Update Claims

Create a claim.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of claims.

{
  "claim1": "value2"
}

Response

{
  "status": "OK"
}

{
  "status": "ERROR",
  "responseObject": {
    "code": "NOT_FOUND",
    "message": "Claims for user 'user1' do not exist"
  }
}

delete /admin/claims Delete Claims

Delete claims.

Request

Headers:
- Authorization: Basic ...

Query Params

Param	Type	Description
`userId`*	`String`	User identifier of the owner of deleted claims.
`claim`	`String`	Optional claim name for deleting individual claims.

Response

{
  "status": "OK"
}

Last updated on Aug 19, 2024 (16:16) Edit on Github Send Feedback