> ## Documentation Index > Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List profiles > Get paginated list of Profiles with optional filtering ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/profiles openapi: 3.0.3 info: title: SegmentFlow.ai API description: Unified SegmentFlow.ai API documentation version: 1.0.0 servers: - url: http://localhost:3001 description: Local development - url: https://api-staging.segmentflow.ai description: Staging - url: https://api.segmentflow.ai description: Production security: - apiKeyAuth: [] tags: - name: Profiles description: Profiles (Contacts) - name: Events description: Server-side business event tracking - name: Assets description: Assets - name: BackgroundJobs description: Background job progress - name: Brand-Kit description: Brand kits - name: Catalog-Products description: Catalog products - name: Templates description: Templates - name: Broadcasts description: Broadcasts - name: Segments description: Segments - name: Journeys description: Journeys - name: Emails description: Email sends paths: /api/v1/profiles: post: tags: - Profiles summary: List profiles description: Get paginated list of Profiles with optional filtering operationId: Profiles_Profiles_List requestBody: content: application/json: schema: $ref: '#/components/schemas/ProfileListRequestInput' responses: '200': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ProfileListResponse' '400': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ProfileListRequestInput: type: object properties: search: description: >- Search Profiles by email, phone, or external ID (case-insensitive partial match) type: string segmentFilter: description: Filter by Segment IDs type: array items: type: string profilePropertyFilter: description: Filter by profile properties type: array items: type: object properties: id: type: string description: The profile property ID to filter by values: type: array items: type: string description: Values to match (OR logic within property) required: - id - values sourceFilter: description: >- Filter by ingestion source. Values are the same as the dashboard's Source column. type: array items: type: string enum: - form_submission - csv_import - api_sync - sdk - manual_edit - computed deliverySuppressionStatus: description: Filter by current Delivery Suppression status. type: string enum: - eligible - suppressed deliverySuppressionReasonFilter: description: >- Filter by current Delivery Suppression reason. Any reason filter implies suppressed Profiles. type: array items: type: string enum: - HardBounced - Complained - SoftBounceSuppressed cursor: description: Pagination cursor from previous response type: string direction: description: Pagination direction (defaults to "after") type: string enum: - before - after limit: description: Number of Profiles to return (defaults to 10) type: integer minimum: 1 maximum: 100 profileIds: description: Filter by specific Profile IDs type: array items: type: string description: >- POST /api/v1/profiles request body. Filter shape shared with bulk-by-filter endpoints. ProfileListResponse: type: object properties: profiles: type: array items: $ref: '#/components/schemas/Profile' previousCursor: description: Cursor for previous page type: string nextCursor: description: Cursor for next page type: string profileCount: type: integer minimum: 0 maximum: 9007199254740991 description: Total count of Profiles matching filters required: - profiles - profileCount additionalProperties: false description: POST /api/v1/profiles response — paginated Profiles ErrorResponse: type: object properties: errorCode: $ref: '#/components/schemas/SegmentflowErrorCode' description: >- Stable machine-readable error code. SDKs map this to typed exception classes. example: TEMPLATE_NAME_EXISTS message: type: string description: >- Human-readable error message. May change between releases; do not parse. example: Template name 'Hello' already exists in this organization. details: description: >- Optional structured detail. `issues` carries per-field validation problems; other keys are reserved. type: object properties: issues: type: array items: $ref: '#/components/schemas/ErrorIssue' additionalProperties: description: Any JSON value. nullable: true x-stainless-any: true required: - errorCode - message additionalProperties: false description: 'Canonical error envelope (ADR-0008): `{ errorCode, message, details? }`.' Profile: type: object properties: id: type: string email: type: string description: Canonical email identifier from Profile.email (always present). phone: type: string description: Optional phone number from Profile.phone. Non-canonical in v1. nullable: true sources: type: array items: type: string description: >- Distinct segment_membership source tags for this Profile (e.g. 'form_submission', 'csv_import', 'shopify'). Used as a fallback when the Profile has no property assignments tagged with a source. properties: type: object additionalProperties: type: object properties: name: type: string value: description: Any JSON value. nullable: true x-stainless-any: true source: type: string enum: - sdk - computed - csv_import - unknown - manual_edit - form_submission - api_sync - shopify - woocommerce - wordpress - salesforce description: Origin of this property value for data lineage tracking platform: type: string description: >- System-of-record platform (shopify | woocommerce | wordpress | salesforce). Null when no platform-of-record applies. nullable: true computedAt: type: string description: ISO timestamp of when this property value was last updated nullable: true required: - name - value - source - platform - computedAt additionalProperties: false segments: type: array items: type: object properties: id: type: string name: type: string type: type: string required: - id - name - type additionalProperties: false deliverySuppression: type: object properties: suppressed: type: boolean reason: type: string enum: - HardBounced - Complained - SoftBounceSuppressed nullable: true email: type: string description: Canonical Profile/email this state applies to. suppressedAt: type: string description: ISO timestamp of when the active suppression started. nullable: true latestBounceReason: type: string description: >- Latest SES bounce reason/diagnostic text explaining the active delivery suppression, when available. nullable: true latestBounceDiagnosticCode: type: string description: >- Latest raw SES recipient diagnostic code for the active delivery suppression, when available. nullable: true required: - suppressed - reason - email - suppressedAt additionalProperties: false createdAt: type: string description: ISO timestamp of when this Profile was created updatedAt: type: string description: ISO timestamp of when this Profile was last updated required: - id - email - phone - sources - properties - segments - deliverySuppression - createdAt - updatedAt additionalProperties: false description: >- Unified API view of a Profile row, with property data-lineage envelope and segment memberships. SegmentflowErrorCode: type: string enum: - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - UNPROCESSABLE_ENTITY - TOO_MANY_REQUESTS - VALIDATION_ERROR - INTERNAL_ERROR - NOT_IMPLEMENTED - SERVICE_UNAVAILABLE - DATABASE_ERROR - IDEMPOTENCY_KEY_TOO_LONG - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_IN_FLIGHT - JOURNEY_NOT_FOUND - JOURNEY_WRONG_ENTRY_NODE - JOURNEY_MISSING_RECIPIENT_EMAIL - JOURNEY_MISSING_REQUIRED_VARIABLES - JOURNEY_RECIPIENT_ERASED - JOURNEY_RUN_NOT_FOUND - BROADCAST_NOT_FOUND - BROADCAST_SCHEDULING_NOT_IMPLEMENTED - BROADCAST_INVALID_STATE - BROADCAST_SEND_NOT_ALLOWED - PREPARED_SEND_NOT_FOUND - PREPARED_SEND_EXPIRED - PREPARED_SEND_CROSS_USER - PREPARED_SEND_CORRUPT - PREPARED_SEND_CONCURRENT_REDEEM - PREPARED_SEND_VALIDATION_FAILED - TEMPLATE_NOT_FOUND - TEMPLATE_NAME_EXISTS - PROFILE_NOT_FOUND - PROFILE_SUBSCRIPTION_GROUP_NOT_FOUND - PROFILE_TRAITS_WRITE_UNSUPPORTED - MISSING_CREDENTIAL - INVALID_API_KEY - INVALID_OAUTH_TOKEN - AMBIGUOUS_CREDENTIAL - INSUFFICIENT_SCOPE - MULTIPLE_CREDENTIALS_PRESENT - BEARER_CREDENTIAL_REMOVED - SESSION_ROLE_INSUFFICIENT - API_KEY_SCOPE_INSUFFICIENT - BILLING_DISABLED - BILLING_NOT_CONFIGURED description: >- Stable machine-readable error code. SDK codegen maps these to typed exception classes. ErrorIssue: type: object properties: path: anyOf: - type: string - type: array items: anyOf: - type: string - type: number description: >- Where in the request the issue occurred. String for simple paths; array for nested paths. example: name code: type: string description: >- Stable, machine-readable kind of issue (e.g. 'required', 'invalid_type'). example: duplicate message: type: string description: Human-readable description of the issue. example: Template name already exists in this organization. required: - path - code - message additionalProperties: false description: A single validation issue inside an error response's `details.issues[]`. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Unified API key for server-side SDK and API integrations ````