> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # List > Returns a page of persons. Pass `pageToken` from the previous response's `nextPageToken` to fetch the next page. A page can be empty while the results are still being prepared. Keep requesting pages until the response has no `nextPageToken`. Requires the `https://devx.{environment}.oleria.io/read` scope. ## OpenAPI ````yaml /developer-docs/api-reference/oleria-public-api-1.0.0.yaml get /v1/persons openapi: 3.0.3 info: title: Oleria Public API version: 1.0.0 description: >- REST API for Oleria's identity and access data. Each resource is a collection exposing list and get operations; responses return the complete object. Where Oleria can change what it reports, the change is a method on the same resource: disabling an account is `POST /v1/accounts/{id}/disable`, and membership is a sub-resource asserted with `PUT` and removed with `DELETE`. Those changes are applied in the source application asynchronously: each returns a job under `/v1/action-jobs` that reports the outcome for every target it affected, and whether Oleria's own data reflects it yet. Authenticate with OAuth 2.0 client credentials and send the access token as `Authorization: Bearer `. servers: - url: https://devx.{environment}.oleria.io description: Oleria API server. variables: environment: default: prod description: >- Your Oleria deployment, for example `acme` for `https://devx.acme.oleria.io`. Substitute it in the OAuth scope names as well, since OpenAPI applies a server variable to the URL only and the scopes are published with the placeholder still in them. security: [] paths: /v1/persons: get: tags: - Persons summary: List description: >- Returns a page of persons. Pass `pageToken` from the previous response's `nextPageToken` to fetch the next page. A page can be empty while the results are still being prepared. Keep requesting pages until the response has no `nextPageToken`. Requires the `https://devx.{environment}.oleria.io/read` scope. operationId: ListPersons parameters: - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/applicationInstanceId' responses: '200': description: A page of persons. content: application/json: schema: $ref: '#/components/schemas/PersonList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - oauth2: - https://devx.{environment}.oleria.io/read components: parameters: pageSize: name: pageSize in: query description: Maximum items per page. schema: type: integer format: int32 default: 50 minimum: 1 maximum: 200 pageToken: name: pageToken in: query description: >- Opaque page token from the previous response's `nextPageToken`. Omit it for the first page; pass it back exactly as received. Do not parse or construct it. schema: type: string applicationInstanceId: name: applicationInstanceId in: query description: >- Scope the list to a single application instance, identified by its id (UUID). An application instance is one connected integration in your tenant: a specific Okta, Workday, and so on. Omit it to list across all of your instances. schema: type: string format: uuid schemas: PersonList: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Oleria_Person' nextPageToken: type: string description: >- Opaque token for the next page; pass it back as `pageToken`. Present whenever more pages remain, including when this page is empty because the results are still being prepared, and absent only once the collection is fully returned. Do not parse or construct it. Oleria_Person: type: object description: > An Oleria Person object represents a human individual whose identity is managed within an enterprise application, identity provider, or directory service. A Person is the root human entity in the identity graph — distinct from Employee (employment relationship) and Account (digital identity) allOf: - $ref: '#/components/schemas/Person' - $ref: '#/components/schemas/Oleria_PersonGlobalIdentifiers' - $ref: '#/components/schemas/Oleria_PersonEnrichedInformation' - $ref: '#/components/schemas/Oleria_PersonAnalyticsInformation' - $ref: '#/components/schemas/Oleria_PersonSystemOfRecordInformation' - required: - oleriaObjectMetadata type: object properties: oleriaObjectMetadata: $ref: '#/components/schemas/Oleria_ObjectMetadata' ErrorResponse: type: object description: >- Error envelope. `code` is a stable machine-readable identifier; `message` is human-readable. required: - code - message properties: code: type: string description: Stable, machine-readable error code (SCREAMING_SNAKE_CASE). example: NOT_FOUND details: type: object description: Optional free-form context for debugging. additionalProperties: true message: type: string description: Human-readable description of the error. example: No resource with the given id. Person: required: - id - name - objectMetadata type: object properties: createdDate: type: string description: The date the object was created format: date-time example: '2024-05-02T03:17:34.948Z' id: $ref: '#/components/schemas/LocallyUniquePersonId' lastModifiedDate: type: string description: The date the object was last modified format: date-time example: '2024-05-02T03:17:34.948Z' name: type: string description: The name of the person example: Kirt Debique objectDirectoryContainerFederation: $ref: '#/components/schemas/EntityIdentifierFederationInformation' objectDirectoryContainerId: $ref: '#/components/schemas/LocallyUniqueObjectDirectoryId' objectMetadata: $ref: '#/components/schemas/ObjectMetadata' personalEmails: type: array description: > Array of personal emails for the _Person_ (must include the _primaryPersonalEmail_) items: type: string personalLocations: type: array description: > These are the locations assigned as delivery points for this _Person_ items: $ref: '#/components/schemas/LocationSpecification' primaryPersonalEmail: type: string description: | Primary personal email for the _Person_ example: kirt@bricklanerecords.com description: A human Oleria_PersonGlobalIdentifiers: required: - globalId type: object properties: globalId: type: string globalObjectDirectoryContainerId: type: string description: > Global identifiers translated from Person local identifiers to be composed on Oleria Person Oleria_PersonEnrichedInformation: type: object properties: enrichedNormalizedPersonalEmails: type: array description: >- Normalized version of each personal email found in Person.PersonalEmails items: type: string enrichedNormalizedPrimaryPersonalEmail: type: string description: >- Normalized version of the primary personal email found in Person.PrimaryPersonalEmail description: > Enriched information derived from a combination of Person data, additional identity signals Oleria_PersonAnalyticsInformation: type: object description: > Analytics information calculated from identity security graph and added to the person Oleria_PersonSystemOfRecordInformation: type: object properties: sorPrimaryStewardEmail: type: string description: > System of Record information associated with a person and managed in Oleria Oleria_ObjectMetadata: type: object properties: enrichmentVersion: type: string generatedTime: type: string format: date-time description: > object metadata supersets object metadata with platform enrichment provenance — the enrichment version and the time the record was generated LocallyUniquePersonId: type: string description: > An identifier for a [Person](#/components/schemas/Person) object in the Oleria system. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. It is important for this identifier to be based on an underlying persistent and reusable application id so connections to the object are robust to metadata changes and other relevant operations. example: P232435 EntityIdentifierFederationInformation: type: object required: - isFederated properties: authenticationKey: type: string isFederated: type: boolean description: | Federation information used when specifying an _EntityIdentifier_ LocallyUniqueObjectDirectoryId: type: string description: > An identifier (unique to the integrated application) for a [ObjectDirectory](#/components/schemas/ObjectDirectory) object represented in the Oleria system. Oleria converts these identifiers to global ids so they can be unique in the context of the global system graph. It is important for this identifier to be based on an underlying persistent and reusable application or identity provider id so connections to the object are robust to metadata changes and other relevant operations example: >- repo:R_kgDOLL0doQ (GitHub based on repository node identifier), 1BUxdX4M-H7X8GKRgTjprJS8fjY_Ij1giE82lQlny2kc (Google Drive based on file id) ObjectMetadata: required: - ApplicationInstanceId - GeneratedTime type: object properties: ApplicationInstanceId: type: string GeneratedTime: type: string format: date-time Profile: $ref: '#/components/schemas/SchemaProfile' ObjectOrRelationshipType: type: string description: > The _ObjectMetadata_ structure defines metadata that applies to every object and relationship, and is usually managed by the system that receives the data LocationSpecification: type: object properties: type: $ref: '#/components/schemas/LocationSpecificationType' typeSpecificData: oneOf: - $ref: '#/components/schemas/NetworkLocationSpecification' - $ref: '#/components/schemas/PhysicalLocationSpecification' SchemaProfile: type: string enum: - Account - Membership - Governance - Risk - Access - Detection LocationSpecificationType: type: string enum: - Network - Physical NetworkLocationSpecification: type: object properties: ipAddressExclusions: type: array items: type: string ipAddressInclusions: type: array items: type: string name: type: string supplementaryInformation: $ref: '#/components/schemas/SupplementaryLocationInformation' description: > Specify a network location or zone with a name and a list of IP addresses or ranges (including in CIDR notation) PhysicalLocationSpecification: type: object properties: addressedObjectIdentifier: $ref: '#/components/schemas/AddressedObjectIdentifier' countryLevelInformation: $ref: '#/components/schemas/CountryLevelInformation' locality: $ref: '#/components/schemas/Locality' postcode: type: string description: | Postal code or ZIP code example: '98112' supplementaryInformation: $ref: '#/components/schemas/SupplementaryLocationInformation' description: > A subset of the ISO 19160-4:2023 delivery point specification. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 SupplementaryLocationInformation: type: object properties: geoLocation: $ref: '#/components/schemas/GeoLocation' additionalLocationMetadata: type: array items: $ref: '#/components/schemas/MetadataItem' AddressedObjectIdentifier: type: object properties: building: type: string description: > Element identifying the number or name and type of the location edifice or construction example: The Madrona Refuge Building door: type: string description: | Element identifying the apartment, room, or office example: Suite 301 premisesIdentifier: type: string description: > Element designating the area or the object on an area associated with the location example: 1126 34th Avenue description: > Subset of an ISO 19160-4:2023 construct identifying a specific addess within a [Locality](#/components/schemas/Locality). For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 CountryLevelInformation: type: object properties: countryCode: type: string description: > Element designating the ISO 3166-1 A-2 country code for the country, territory or area of geopolitical interest example: US countryName: type: string description: > Element designating the country, dependency, or area of geopolitical interest example: United States multiCountryRegion: type: string description: > Element indicating a region in which the country, territory, or area of geopolitical interest is located and by which it is potentially more effectively recognized example: North America description: > Subset of ISO 19160-4:2023 country level information. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 Locality: type: object properties: district: type: string description: > Element indicating the name of the area within or adjacent to the specified town example: Madrona (neighborhood in Seattle) region: type: string description: > Element specifying the geographic or administrative area of the country in which the town is situated example: Washington town: type: string description: > Element indicating the name of the populated place associated with the [LocationSpecification](#/components/schemas/LocationSpecification) in which this _Locality_ is being referenced example: Seattle description: > Subset of ISO 19160-4:2023 locality information identifying the geographical area. For context, the property examples reference the address - The Madrona Refuge Building, Suite 301, 1126 34th Avenue, Seattle, WA, 98112 GeoLocation: type: object required: - latitude - longtitude properties: latitude: type: number longtitude: type: number description: Latitude and longtitude specification for a location MetadataItem: type: object properties: id: type: string name: type: string namespace: type: string type: $ref: '#/components/schemas/MetadataValueType' value: type: object MetadataValueType: type: string enum: - array_boolean - array_float32 - array_float64 - array_int32 - array_int64 - array_string - boolean - float32 - float64 - int32 - int64 - oleria_global_id - oleria_local_id - pem - property_bag - rfc3339_date - string responses: BadRequest: description: The request was malformed, for example an invalid cursor or page size. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: BAD_REQUEST message: The request was malformed. Unauthorized: description: Missing or invalid authentication token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: UNAUTHORIZED message: Missing or invalid authentication token. Forbidden: description: The token lacks the scope required for this resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: FORBIDDEN message: The token lacks the required scope. TooManyRequests: description: Rate limit exceeded. Retry after the interval in the Retry-After header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: TOO_MANY_REQUESTS message: Rate limit exceeded. Retry after the specified interval. InternalError: description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: INTERNAL_ERROR message: An unexpected error occurred. securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client-credentials flow. Request an access token from the token endpoint and send it as `Authorization: Bearer `. flows: clientCredentials: tokenUrl: https://auth.prod.oleria.io/oauth/token scopes: https://devx.{environment}.oleria.io/delete: Irreversibly destroy an object in the source system. https://devx.{environment}.oleria.io/read: Read identity and access data, and the jobs that change it. https://devx.{environment}.oleria.io/write: >- Make reversible changes: grant, enable, assign, revoke and remove access. ````