Select release
On this page:

User Data Store API

Edit on Github Send Feedback v1.3.0

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

Photo API

Attachment API

Claims API

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
Search

1.3.x

User Data Store