> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List person steps

> Returns campaign flow steps for the specified person, sorted by event date in descending order. Steps represent discrete tracked actions (e.g. conversion, share, reward earned) within the person's journey.



## OpenAPI

````yaml /api-reference/integration-server-to-extole.json get /v5/persons/{person_id}/steps
openapi: 3.0.1
info:
  description: >-
    Server-to-Extole integration endpoints: event submission, person lookup,
    zone rendering, token management, and reward retrieval for backend services
    authenticating with client credentials.


    ## Updating a resource


    `PUT` merges. A field you omit from the body is left at its stored value, so
    you do not need to read a resource and send it back whole in order to change
    one field. This is a deliberate departure from the HTTP convention that
    `PUT` replaces, and it holds across this API.


    Two qualifications, both visible on each operation's own request schema:


    - Some operations mark fields `required` in their request schema. Those must
    be sent on every request, whether or not you are changing them.

    - A field that holds a list or a map is replaced, not merged, when you
    supply it. Sending one entry of a collection stores that entry and drops the
    rest, so to change one member of a collection you must send the collection's
    other members alongside it.
  title: Integration API - Server to Extole
  version: '1.0'
servers:
  - description: Production
    url: https://api.extole.io
security:
  - HEADER: []
  - QUERY: []
  - COOKIE: []
tags:
  - name: Authentication
  - name: Content
  - name: Events
  - name: Files
  - name: Persons
  - name: Rewards
paths:
  /v5/persons/{person_id}/steps:
    get:
      tags:
        - Persons
      summary: List person steps
      description: >-
        Returns campaign flow steps for the specified person, sorted by event
        date in descending order. Steps represent discrete tracked actions (e.g.
        conversion, share, reward earned) within the person's journey.
      parameters:
        - description: The Extole unique profile identifier of this user at Extole.
          in: path
          name: person_id
          required: true
          schema:
            type: string
        - description: >-
            Optional step name filter. Will include steps that match at least
            one of the names.
          in: query
          name: names
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional container filter, defaults to all containers. Will include
            steps that match at least one of the containers.
          in: query
          name: containers
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional campaign id filter. Will include steps that match at least
            one of the campaign ids.
          in: query
          name: campaign_ids
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional program label filter. Will include steps that match at
            least one of the programs.
          in: query
          name: programs
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional journey names filter. Will include steps that match at
            least one of the journey names.
          in: query
          name: journey_names
          schema:
            items:
              type: string
            type: array
        - description: Optional filter for primary steps. Defaults to all steps.
          in: query
          name: is_primary
          schema:
            type: boolean
        - description: >-
            Optional filter for existence of a specific data keys with non-empty
            values. Will include steps that have at least one of the data keys.
          in: query
          name: data_keys
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional event IDs filter. Will include steps that match at least
            one of the event IDs.
          in: query
          name: event_ids
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional cause event IDs filter. Will include steps that match at
            least one of the cause event IDs.
          in: query
          name: cause_event_ids
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional root event IDs filter. Will include steps that match at
            least one of the root event IDs.
          in: query
          name: root_event_ids
          schema:
            items:
              type: string
            type: array
        - description: Optional offset filter, defaults to 0.
          in: query
          name: offset
          schema:
            default: 0
            format: int32
            type: integer
        - description: Optional limit filter, defaults to 20.
          in: query
          name: limit
          schema:
            default: 20
            format: int32
            type: integer
        - description: >-
            Optional journey key names filter. Will include steps, whose journey
            key matches one of the journey key names.
          in: query
          name: journey_key_names
          schema:
            items:
              type: string
            type: array
        - description: >-
            Optional journey key values filter. Will include steps that have one
            of the specified journey keys. Valid format is name:value.
          in: query
          name: journey_key_values
          schema:
            items:
              type: string
            type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PersonStepResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_incoming_url:
                  $ref: '#/components/examples/invalid_incoming_url'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_uri_in_json:
                  $ref: '#/components/examples/invalid_uri_in_json'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
                person_step_invalid_flow_query:
                  $ref: '#/components/examples/person_step_invalid_flow_query'
                person_step_invalid_visit_type:
                  $ref: '#/components/examples/person_step_invalid_visit_type'
                value_does_not_follow_pattern:
                  $ref: '#/components/examples/value_does_not_follow_pattern'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
components:
  schemas:
    PersonStepResponse:
      properties:
        campaign_id:
          description: >-
            Extole campaign id associated with this step. Absent when no
            campaign is linked.
          type: string
        cause_event_id:
          description: Id of the direct cause event for this step.
          type: string
        container:
          description: Campaign container the step belongs to.
          type: string
        created_date:
          $ref: '#/components/schemas/ZonedDateTime'
        data:
          additionalProperties:
            $ref: '#/components/schemas/PersonStepDataResponse'
          description: Named data parameters attached to this step.
          type: object
        event_date:
          $ref: '#/components/schemas/ZonedDateTime'
        event_id:
          description: Extole event id that triggered this step.
          type: string
        id:
          description: Extole-assigned unique identifier for this step.
          readOnly: true
          type: string
        is_primary:
          description: >-
            Whether this is the primary (first qualifying) step for this event
            type in the journey.
          type: boolean
        journey_key:
          $ref: '#/components/schemas/JourneyKey'
        journey_name:
          description: >-
            Journey name associated with this step. Absent for global-scope
            steps.
          type: string
        name:
          description: >-
            Name of the event type that created this step (e.g. `purchase`,
            `signup`).
          type: string
        program:
          description: >-
            Program key associated with this step. Absent when no program
            context exists.
          type: string
        quality:
          description: Quality classification of the step (`HIGH`, `LOW`, or `NONE`).
          enum:
            - HIGH
            - LOW
            - NONE
          type: string
        root_event_id:
          description: Id of the root event that initiated the chain leading to this step.
          type: string
        scope:
          description: Scope of the step (`PUBLIC`, `PRIVATE`, or `CLIENT`).
          enum:
            - CLIENT
            - PRIVATE
            - PUBLIC
          type: string
        updated_date:
          $ref: '#/components/schemas/ZonedDateTime'
      required:
        - campaign_id
        - cause_event_id
        - container
        - created_date
        - data
        - event_date
        - event_id
        - id
        - is_primary
        - journey_key
        - journey_name
        - name
        - program
        - quality
        - root_event_id
        - scope
        - updated_date
      type: object
    RestExceptionResponse:
      description: Represents the API error response
      properties:
        code:
          description: Specific error code for this error type, documented per endpoint
          type: string
        http_status_code:
          description: >-
            HTTP status code that was returned with this error, useful if client
            get response code
          format: int32
          type: integer
        message:
          description: User readable English description of the error
          type: string
        parameters:
          additionalProperties:
            description: >-
              Attributes related to the error, varies be error code, documented
              per endpoint
            type: object
          description: >-
            Attributes related to the error, varies be error code, documented
            per endpoint
          type: object
        unique_id:
          description: >-
            Unique id associated with this error, useful for discussions with
            Extole
          type: string
      required:
        - code
        - http_status_code
        - message
        - parameters
        - unique_id
      type: object
    ZonedDateTime:
      description: >-
        [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) or
        [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557#section-4)
        date-time with a numeric [UTC
        offset](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and
        an optional [IANA
        time-zone](https://datatracker.ietf.org/doc/html/rfc9557#section-4)
        suffix in square brackets. Precision up to milliseconds.
      example: '2025-10-24T02:00:00-07:00'
      pattern: >-
        ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])(\[[^\]]+\])?$
      type: string
    PersonStepDataResponse:
      description: Named data parameters attached to this step.
      properties:
        key_type:
          description: >-
            What the campaign uses this data parameter for. `VALUE` is the
            monetary value of the step, such as a cart value,
            `UNIQUE_PARTNER_EVENT_KEY` is the partner's identifier for the event
            that created the step, `PARTNER_EVENT_KEY` and `PARTNER_PROFILE_KEY`
            are other partner identifiers, and `NONE` is plain data.
          enum:
            - NONE
            - PARTNER_EVENT_KEY
            - PARTNER_PROFILE_KEY
            - UNIQUE_PARTNER_EVENT_KEY
            - VALUE
          type: string
        name:
          description: Name of the data parameter.
          type: string
        scope:
          description: Visibility scope of the data parameter.
          enum:
            - CLIENT
            - PRIVATE
            - PUBLIC
          type: string
        value:
          description: Value stored for the data parameter.
          type: object
      type: object
    JourneyKey:
      properties:
        name:
          type: string
        value:
          type: string
      type: object
  examples:
    binding_error:
      summary: binding_error
      value:
        code: binding_error
        http_status_code: 400
        message: Argument is not of the expected type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_incoming_url:
      summary: invalid_incoming_url
      value:
        code: invalid_incoming_url
        http_status_code: 400
        message: Incoming URL is an invalid URI
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_json:
      summary: invalid_json
      value:
        code: invalid_json
        http_status_code: 400
        message: JSON is invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_parameter:
      summary: invalid_parameter
      value:
        code: invalid_parameter
        http_status_code: 400
        message: Parameter is invalid.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_uri_in_json:
      summary: invalid_uri_in_json
      value:
        code: invalid_uri_in_json
        http_status_code: 400
        message: Invalid URI in JSON
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_request_body:
      summary: missing_request_body
      value:
        code: missing_request_body
        http_status_code: 400
        message: Missing request body
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    person_not_found:
      summary: person_not_found
      value:
        code: person_not_found
        http_status_code: 400
        message: Person not found
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    person_step_invalid_flow_query:
      summary: person_step_invalid_flow_query
      value:
        code: person_step_invalid_flow_query
        http_status_code: 400
        message: Person step flow query is invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    person_step_invalid_visit_type:
      summary: person_step_invalid_visit_type
      value:
        code: person_step_invalid_visit_type
        http_status_code: 400
        message: Person step visit type is invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    value_does_not_follow_pattern:
      summary: value_does_not_follow_pattern
      value:
        code: value_does_not_follow_pattern
        http_status_code: 400
        message: Value does not follow the key:value pattern
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    method_unauthorized:
      summary: method_unauthorized
      value:
        code: method_unauthorized
        http_status_code: 401
        message: Unauthorized access to this endpoint
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    payment_required:
      summary: payment_required
      value:
        code: payment_required
        http_status_code: 402
        message: The access_token provided is associated with an unpaid account.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    access_denied:
      summary: access_denied
      value:
        code: access_denied
        http_status_code: 403
        message: >-
          The access_token provided is not permitted to access the specified
          resource.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_access_token:
      summary: missing_access_token
      value:
        code: missing_access_token
        http_status_code: 403
        message: No access_token was provided with this request.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    unsupported_media_type:
      summary: unsupported_media_type
      value:
        code: unsupported_media_type
        http_status_code: 415
        message: Request had an unsupported or no media type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    too_many_requests:
      summary: too_many_requests
      value:
        code: too_many_requests
        http_status_code: 429
        message: >-
          The server is unable to process your request at the moment, please
          retry later.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
  securitySchemes:
    HEADER:
      in: header
      name: Authorization
      type: apiKey
      x-bearer-format: bearer
    QUERY:
      in: query
      name: access_token
      type: apiKey
    COOKIE:
      in: cookie
      name: extole_token
      type: apiKey

````

## Related topics

- [List person journeys](/api-reference/persons/list-person-journeys.md)
- [List assets for a person](/api-reference/profiles/list-assets-for-a-person.md)
- [List person locations](/api-reference/persons/list-person-locations.md)
- [List person shares](/api-reference/persons/list-person-shares.md)
- [List person relationships](/api-reference/persons/list-person-relationships.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.