sitecore Guests API

openapi: 3.2.0
info:
  title: Sitecore CDP REST Guests API
  description: The Sitecore CDP REST API provides synchronous access to retrieve, create, update, and delete data stored in Sitecore Customer Data Platform. It exposes guest profiles, orders, order items, order contacts, order consumers, and data extensions through standard HTTP methods. Developers use this API to build integrations that read or write customer data programmatically, enabling use cases such as audience segmentation, data enrichment, and reporting. Authentication uses HTTP Basic Auth with a client key and API token obtained from the CDP instance settings. Regional server endpoints must be used based on the CDP instance's geographic deployment.
  version: v2.1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://api-engage-eu.sitecorecloud.io
  description: EU Production Server
- url: https://api-engage-us.sitecorecloud.io
  description: US Production Server
- url: https://api-engage-ap.sitecorecloud.io
  description: Asia-Pacific Production Server
- url: https://api-engage-jpe.sitecorecloud.io
  description: Japan Production Server
security:
- basicAuth: []
tags:
- name: Guests
  description: Endpoints for creating, retrieving, updating, and deleting guest profiles in Sitecore CDP. Guests represent the core customer entity storing personal, behavioral, and transactional data.
paths:
  /v2.1/guests:
    get:
      operationId: listGuests
      summary: List guests
      description: Retrieves a paginated list of guest profiles from Sitecore CDP. Returns up to 100 guests per request. Use the offset and limit parameters to paginate through results. Supports filtering by email or other identifiers using query parameters.
      tags:
      - Guests
      parameters:
      - name: email
        in: query
        description: Filter guests by email address
        required: false
        schema:
          type: string
          format: email
      - name: limit
        in: query
        description: Maximum number of guests to return (max 100)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: offset
        in: query
        description: Number of records to skip for pagination
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A list of guest profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGuest
      summary: Create a guest
      description: Creates a new guest profile in Sitecore CDP. The guest record stores identity and behavioral data used for personalization and segmentation. An email address or other identifying attributes should be provided to enable identity resolution.
      tags:
      - Guests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuestRequest'
      responses:
        '201':
          description: Guest created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2.1/guests/{guestRef}:
    get:
      operationId: getGuest
      summary: Get a guest
      description: Retrieves a specific guest profile by its unique reference identifier. Returns the full guest object including all stored personal and behavioral attributes.
      tags:
      - Guests
      parameters:
      - $ref: '#/components/parameters/guestRef'
      responses:
        '200':
          description: Guest profile details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGuest
      summary: Update a guest (full)
      description: Performs a full replacement update of a guest profile. All fields in the guest object are replaced with the values provided in the request body. Fields not included in the request will be cleared.
      tags:
      - Guests
      parameters:
      - $ref: '#/components/parameters/guestRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuestRequest'
      responses:
        '200':
          description: Guest updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchGuest
      summary: Update a guest (partial)
      description: Performs a partial update of a guest profile. Only the fields provided in the request body are updated; all other fields retain their current values. Use this operation when updating a subset of guest attributes.
      tags:
      - Guests
      parameters:
      - $ref: '#/components/parameters/guestRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGuestRequest'
      responses:
        '200':
          description: Guest partially updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Guest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGuest
      summary: Delete a guest
      description: Permanently and irreversibly deletes a guest profile and all associated data from Sitecore CDP. This operation cannot be undone. All orders, sessions, and data extensions linked to the guest are also removed.
      tags:
      - Guests
      parameters:
      - $ref: '#/components/parameters/guestRef'
      responses:
        '204':
          description: Guest deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    guestRef:
      name: guestRef
      in: path
      description: The unique reference identifier for the guest profile
      required: true
      schema:
        type: string
  schemas:
    CreateGuestRequest:
      type: object
      description: Request body for creating or updating a guest profile
      properties:
        email:
          type: string
          description: The email address of the guest
          format: email
        firstName:
          type: string
          description: The guest's first name
        lastName:
          type: string
          description: The guest's last name
        dateOfBirth:
          type: string
          description: The guest's date of birth in ISO 8601 format
          format: date
        gender:
          type: string
          description: The guest's gender
          enum:
          - Male
          - Female
          - Other
          - Unknown
        phoneNumbers:
          type: array
          description: Phone numbers associated with the guest
          items:
            type: string
    GuestListResponse:
      type: object
      description: A paginated response containing a list of guest profiles
      properties:
        items:
          type: array
          description: The list of guests for the current page
          items:
            $ref: '#/components/schemas/Guest'
        totalCount:
          type: integer
          description: The total number of guests matching the query
        limit:
          type: integer
          description: The maximum number of items per page
        offset:
          type: integer
          description: The offset used for this page of results
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        message:
          type: string
          description: A human-readable error message
        statusCode:
          type: integer
          description: The HTTP status code
        errors:
          type: array
          description: List of detailed error messages
          items:
            type: string
    Guest:
      type: object
      description: The core entity of Sitecore CDP representing a customer with personal, behavioral, and transactional data used for personalization and segmentation
      properties:
        guestRef:
          type: string
          description: The unique reference identifier for the guest
        email:
          type: string
          description: The email address of the guest
          format: email
        firstName:
          type: string
          description: The guest's first name
        lastName:
          type: string
          description: The guest's last name
        dateOfBirth:
          type: string
          description: The guest's date of birth in ISO 8601 format
          format: date
        gender:
          type: string
          description: The guest's gender
          enum:
          - Male
          - Female
          - Other
          - Unknown
        phoneNumbers:
          type: array
          description: Phone numbers associated with the guest
          items:
            type: string
        createdAt:
          type: string
          description: The ISO 8601 timestamp when the guest was created
          format: date-time
        modifiedAt:
          type: string
          description: The ISO 8601 timestamp when the guest was last modified
          format: date-time
        identifiers:
          type: array
          description: External identifiers linked to this guest for identity resolution
          items:
            $ref: '#/components/schemas/GuestIdentifier'
    GuestIdentifier:
      type: object
      description: An external identifier that links a guest to an external system
      properties:
        provider:
          type: string
          description: The name of the identity provider or source system
        id:
          type: string
          description: The identifier value from the external system
        expiryDate:
          type: string
          description: The expiry date of this identifier
          format: date-time
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a client key as the username and an API token as the password. Credentials are obtained from Sitecore CDP Settings > API access.
externalDocs:
  description: Sitecore CDP REST API Documentation
  url: https://doc.sitecore.com/cdp/en/developers/api/rest-apis.html