# Retrieve guests

Retrieves a maximum of 100 of the most recent guests. We recommend that you retrieve guests by their email address or other identifying information using query parameters before you create a guest. This lets you check if a certain guest already exists in Sitecore CDP. If the guest exists, avoid creating duplicates. Instead, update the existing guest.
### Query parameters
You can use the following query parameters to retrieve guests by exact match, using some of the following identifying information:
- `email`
- `orderReferenceId`
- `orderRef`
- `identifiers.provider` plus `identifiers.id`

Alternatively, you can use the `expand=true` query parameter to retrieve guests with all their key-value pairs listed.
#### Examples
Here's an example of how to use the `email` query parameter to retrieve guests by their email address:
`{baseURL}/v2.1/guests?email=john.doe@gmail.com"`
Here's an example of how to use the `identifiers.provider` and the `identifiers.id` query parameters to retrieve guests by their identifiers:
`{baseURL}/v2.1/guests?identifiers.provider=ProfileSystem&identifiers.id=B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41"`
If any of this returns a guest, avoid creating another guest with the same identifying information. Instead, update the existing guest.
### Guest reference
In the response, in `items.href`, the guest reference is the string that follows the final slash&:
`\"href\": \"{baseURL}/v2.1/guests/{guestRef}" `
Example guest reference: `f7aabbca-1c1b-4fc2-be72-3e16294a4f03`
Use the guest reference to interact with the full guest record, for example, to retrieve or update it.
You can also use the guest reference to find data about the guest in Sitecore CDP. In Sitecore CDP, click **Guests**. In the **Search** field, enter the guest reference, then click the **Guest type: All** filter. Then, Sitecore CDP lists the guest profile for the guest.

Endpoint: GET /v2.1/guests
Version: v2.1
Security: BasicAuth

## Description:

  - `Query parameters` ()
    You can use the following query parameters to retrieve guests by exact match, using some of the following identifying information: emailorderReferenceIdorderRefidentifiers.provider plus identifiers.id Alternatively, you can use the expand=true query parameter to retrieve guests with all their key-value pairs listed.

  - `Examples` ()
    Here's an example of how to use the email query parameter to retrieve guests by their email address: {baseURL}/v2.1/guests?email=john.doe@gmail.com" Here's an example of how to use the identifiers.provider and the identifiers.id query parameters to retrieve guests by their identifiers: {baseURL}/v2.1/guests?identifiers.provider=ProfileSystem&identifiers.id=B7524AE6-CF1C-440F-B1A2-0C9D42F5CB41" If any of this returns a guest, avoid creating another guest with the same identifying information. Instead, update the existing guest.

  - `Guest reference` ()
    In the response, in items.href, the guest reference is the string that follows the final slash&: \"href\": \"{baseURL}/v2.1/guests/{guestRef}" Example guest reference: f7aabbca-1c1b-4fc2-be72-3e16294a4f03 Use the guest reference to interact with the full guest record, for example, to retrieve or update it. You can also use the guest reference to find data about the guest in Sitecore CDP. In Sitecore CDP, click Guests. In the Search field, enter the guest reference, then click the Guest type: All filter. Then, Sitecore CDP lists the guest profile for the guest.

## Security:

  - `BasicAuth` (unknown)
    http basic

## Query parameters:

  - `offset` (object)

  - `limit` (object)

  - `expand` (array)

  - `sort` (string)

## Response 200:

  - `200` (unknown)
    Successful operation

## Response 200 fields (application/json):

  - `First` (object)
    The request's first list of guests URL.

  - `First.href` (string)
    Example: https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10

  - `Next` (object)
    The request's next list of guests URL.

  - `Next.href` (string)
    Example: https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10

  - `href` (string)
    The request's URL.
    Example: https://api-engage-eu.sitecorecloud.io/v2.1/guests?offset=0&limit=10

  - `items` (array)

  - `items.href` (string)
    Example: https://api-engage-eu.sitecorecloud.io/v2.1/guests/c6cf690f-8384-4734-ab2d-6caa53b6308c

  - `limit` (integer)
    The request's limit.
    Example: 10

  - `offset` (integer)
    The request's offset.
    Example: 0

## Response 401:

  - `401` (unknown)
    Unauthorized request

## Response 401 fields (application/json):

  - `code` (integer)
    The HTTP response status code.
    Example: 401

  - `message` (string)
    Error description.
    Example: Authentication credentials are required to access the resource. All requests must be authenticated.

  - `moreInfoUrl` (string)
    URL to get more information about the error.
    Example: https://support.sitecore.com

  - `status` (string)
    The HTTP request status.
    Example: UNAUTHORIZED