List objects

get

/api/pvlt/1.0/data/collections/{collection}/objects

Returns a paginated list of objects from a collection with all or a subset of object property values. To encrypt object property values, set export to true. Values are encrypted using the key specified in the PVAULT_KMS_EXPORT_URI or PVAULT_KMS_EXPORT_SEED environment variables.

The role performing this operation must have both of the following:

The CapDataReader capability.
At least one allowing policy and no denying policies for the read operation for each of the properties and the collection requested in the call.

See identity and access management for more information about how capabilities are used to control access to operations and policies are used to control access to data.

Warning: Use of the unsafe option, to include all object property values, may expose more private information than is required, use with caution.

Request

Header parameters

X-Trans-Param - string
Extra parameter to pass on to the transformers.
X-Tenant-Id - array of strings
List of tenant IDs to enforce on the request.

Path parameters

collection - string required*
The name of a collection.
Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 40Example: "customers"

Query parameters

adhoc_reason - string
An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.
reason - string required*
Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.
Allowed values: AppFunctionality, Analytics, Notifications, Marketing, ThirdPartyMarketing, FraudPreventionSecurityAndCompliance, AccountManagement, Maintenance, DataSubjectRequest, Other
reload_cache - boolean
Reloads the cache before the action.
page_size - integer
The maximum number of items to return in this request. If not specified, the default value is used. The default value is specified in the PVAULT_SERVICE_DEFAULT_PAGE_SIZE environment variable. Must not exceed the value specified in the PVAULT_SERVICE_MAX_PAGE_SIZE environment variable.
Greater than: 0
cursor - string
The cursor represents the state of consecutive queries for the same request parameters. In the first call, the cursor may be omitted or specified as an empty string. In consecutive calls, it should be set to the value of the cursor field of the objectFieldsPage returned by the previous call. Note: when the id is specified, paging is not supported. In this case, if the number of id values specified exceeds the maximum page size, the method returns 400 (BAD REQUEST).
export - boolean
Whether to encrypt the property values for export.
ids - array of strings
A comma-separated list of object IDs
Each string:
Format: uuid
options - array of strings
Options for the operation. Options include:
- archived – whether to list only archived objects. If not specified, list only active objects.
- show_builtins – show built-in properties, can only be specified with unsafe.
- unsafe – fetch all the properties, cannot be specified with props.
Each string:
Allowed values: unsafe, show_builtins, archived
props - array of strings
The list of property names and transformations. To include multiple names and transformations, provide a comma-separated list. For example, props=first_name,last_name,email.mask.
Each string:
The name of a property or a transformation in the format <property-name>.<transformer-name>.
Example: "ssn.mask"

Possible responses

The request is successful.

application/json

object required*

Additional properties: falseProperties:

results - array of objects required*

The page objects.

Each object:

A list of maps of object properties and their values.

Additional properties: true

Example
{
  "date_of_birth": "1993-02-22",
  "email": "patfar@example.com",
  "first_name": "Pat",
  "last_name": "Far",
  "phone_number": "+11011010101"
}

paging - object required*
Pagination information.
Additional properties: falseProperties:
- size - integer required*
  Number of results in the current page.
- remaining_count - integer required*
  The remaining number of objects that can be read in ensuing calls to this method.
- cursor - string required*
  An opaque string you should provide to get the next page.

Example
{
  "results": [
    {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
    }
  ],
  "paging": {
    "size": 0,
    "remaining_count": 0,
    "cursor": "string"
  }
}

The request is invalid.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1001",
  "message": "The access reason is missing.",
  "context": {
    "reason": null
  }
}

Authentication credentials are incorrect or missing.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1005",
  "message": "The request is unauthorized.",
  "context": {}
}

The caller doesn't have the required access rights.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1007",
  "message": "The operation is forbidden due to missing capabilities.",
  "context": {
    "username": "WebServer"
  }
}

The collection, properties, or object is not found.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "context": {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  },
  "error_code": "PVxxxx",
  "message": "The object is not found."
}

The operation is not allowed.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1026",
  "message": "The operation is not allowed in in-memory mode.",
  "context": {}
}

A conflict occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV3218",
  "message": "Concurrent conflicting updates to the same object.",
  "context": {}
}

Access to a resource that is no longer available occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1033",
  "message": "The resource is gone.",
  "context": {}
}

An error occurs on the server.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1000",
  "message": "Something went wrong",
  "context": {}
}

The service is unavailable.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."

Example
{
  "error_code": "PV1009",
  "message": "The operation timed out on the server.",
  "context": {}
}

Try the API

Authorization

API key:

Path parameters

Collection*:

Query parameters

Adhoc_reason:

Reason*:

Reload_cache:

Page_size:

Cursor:

Export:

Ids:

Options:

Props:

Headers

X-Trans-Param:

X-Tenant-Id:

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example

List objects

Request​

Header parameters​

Path parameters​

Query parameters​

Possible responses​

Try the API

Authorization

Path parameters

Query parameters

Headers

Code examples

Request

Header parameters

Path parameters

Query parameters

Possible responses