Instasent Segment API

openapi: 3.2.0
info:
  title: Instasent product Segment API
  description: '### Overview

    The Instasent Product API provides a comprehensive set of tools for managing **organizations** and **projects** within the Instasent platform. This API is designed to help businesses organize customer data, manage team permissions, and set up projects for targeted marketing and customer engagement. ### What is the Product API? The Product API is Instasent''s primary management API for high-level entities and operations. It provides comprehensive tools for managing your organization''s customer data platform, from initial setup to ongoing operations. > **NOTE**:

    > - To access the Product API you need a Product Token and your Project UID, you can get them in your project settings. **Core Purpose**: The Product API enables you to:

    - **Manage Organizations & Projects**: View organization information, create and configure projects, and manage project-level settings

    - **Configure Data Sources**: Create and manage API data sources that serve as entry points for customer data

    - **Access Unified Audience Data**: Query, search, and retrieve contacts from your project''s unified audience, where data from multiple sources is automatically merged

    - **Track Customer Events**: Search and analyze customer interaction events to understand behavior patterns

    - **Manage Segments**: View and work with audience segments for targeted marketing

    - **Monitor Campaigns & Automations**: Access campaign and automation details, configurations, and status

    - **Send Direct Messages**: Create and send direct SMS messages to audience contacts, and manage SMS senders

    - **Ingest Data**: Push contacts and events to data sources via the Ingest API (integrated into the Product API)


    **Key Entities**:

    - **Organizations**: Represent companies using Instasent. Each organization has its own settings, billing information, user accounts, and API tokens. Organizations can contain multiple projects. - **Projects**: Isolated environments within an organization where customer data, contacts, events, segments, campaigns, and automations are managed. Projects allow you to organize different brands, customer segments, or marketing initiatives separately. - **Data Sources**: Collections of contacts and events that feed into a project. Multiple data sources can contribute to a single project''s unified audience. - **Contacts**: Individual records representing customers, leads, or audience members. Contacts from different data sources are automatically merged into a unified `Audience Contact` when they share matching unique identifiers. - **Events**: Immutable records of customer interactions, such as purchases, page views, email opens, or any custom activity. Events enrich contact profiles and can trigger automations. ### Key Features and Benefits

    The Product API empowers organizations by providing comprehensive tools for customer data management and marketing automation:


    1. **Data Ingestion & Management**:

    - Create and manage API data sources for ingesting contacts and events

    - Push contacts and events to data sources via the Ingest API

    - View datasource statistics and stream specifications

    - Delete contacts from data sources when needed


    2. **Unified Audience Management**:

    - Access a project''s unified audience where contacts from multiple data sources are automatically merged

    - Search and filter contacts using powerful QueryFilter syntax

    - Scroll through large contact lists with cursor-based pagination

    - Retrieve contacts by ID, user identifier, phone number, or email address

    - View contact events and interaction history


    3. **Event Tracking & Analysis**:

    - Search and filter audience events using the Event Filtering system

    - Scroll through event history with pagination support

    - Access event data to understand customer behavior and interactions


    4. **Segmentation & Targeting**:

    - View and manage audience segments (static and dynamic)

    - Scroll contacts within specific segments

    - Use segments for targeted marketing campaigns


    5.'
  version: 2.0.0
  contact:
    email: dev@instasent.com
    url: https://instasent.com
    name: Instasent
  license:
    name: Instasent
    url: https://www.instasent.com/aviso-legal
servers:
- url: https://api.instasent.com/v1
  description: Instasent product API
security:
- BearerAuth: []
- OAuth2: []
tags:
- name: Segment
  description: Segment management endpoints for creating and managing audience segments
paths:
  /project/{project}/segment:
    get:
      x-see-docs:
      - query-filter
      summary: List segments
      description: 'Lists all segments for a project. Supports Query String Filtering for filtering, sorting, and pagination.


        **Required Scope**: `PROJECT_AUDIENCE_READ`


        **Query Parameters**: Supports Query String Filtering parameters:

        - Filtering: Use `field_operator=value` format (e.g., `name_eq=MySegment`, `type_eq=static`, `createdAt_gte=2024-01-01T00:00:00+00:00`)

        - Sorting: Use `_sort=field:direction` format (e.g., `_sort=name:asc`, `_sort=createdAt:desc`)

        - Pagination: Use `_start=0&_limit=50` format. **Important**: When using `_limit`, you must also provide `_start`

        - JSON QueryFilter: Use `_q` parameter with JSON structure


        **Rate Limit**: [l] large - varies by subscription tier'
      tags:
      - Segment
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseSegmentItem'
                  metadata:
                    $ref: '#/components/schemas/ResponseMetadata'
                required:
                - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-stoplight:
        id: 3m3evqyhnqrwt
      operationId: getProjectByProjectSegment
      x-operation-id-source: derived
    post:
      x-see-docs:
      - audience-query-filter
      summary: Create segment
      description: 'Saves an audience filter as a named segment the project keeps, so it can be targeted by a campaign, reused in another filter and counted later.


        The `queryFilter` takes the same Audience Query Filter grammar the audience count and search endpoints take, and is validated the same way: a root group whose children are attribute conditions, event groups or segment memberships. Compose and verify it against the count endpoint first, so you know how many contacts it selects before you save it.


        Consent and channel reach never go inside the filter. They are decided when something is sent, under the project''s policy for the channel, so a segment stores who the contacts ARE and not who may be messaged.


        An invalid filter is refused with `422` naming the offending node, and nothing is saved.


        **Required Scope**: `PROJECT_SEGMENT_WRITE`


        **Rate Limit**: [s] small - varies by subscription tier'
      tags:
      - Segment
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: What the segment is called in the dashboard. Say who it selects; the detail goes in description.
                  maxLength: 50
                description:
                  type: string
                  description: What the filter selects, and the use case if there is one. Listings show this text and not the filter, so it is what a reader has to judge the segment by.
                  maxLength: 256
                queryFilter:
                  type: object
                  description: The membership filter, in Audience Query Filter form.
              required:
              - name
              - queryFilter
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSegmentItem'
                required:
                - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: postProjectByProjectSegment
      x-operation-id-source: derived
  /project/{project}/segment/dynamic:
    get:
      summary: List dynamic segments
      description: 'Lists dynamic segments that don''t require parameters.


        **Required Scope**: `PROJECT_AUDIENCE_READ`


        **Rate Limit**: [l] large - varies by subscription tier'
      tags:
      - Segment
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseSegmentItem'
                required:
                - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-stoplight:
        id: 88c1uxq8s7jt3
      operationId: getProjectByProjectSegmentDynamic
      x-operation-id-source: derived
  /project/{project}/segment/usage:
    get:
      summary: Segment usage map
      description: 'Where each segment is used: campaigns that have targeted it and automations that

        enroll from it.


        **Only segments with at least one reference are returned.** A segment that

        appears in the segment list but not here is an orphan, and that absence is the

        point of this endpoint: it makes an audit possible in one request instead of one

        per segment. Combined with the cached size on each list row you can find the

        orphaned, the empty and the stale in two calls.


        Flows carry no segment reference and are deliberately not counted here.


        **Required Scope**: `PROJECT_AUDIENCE_READ`


        **Freshness**: aggregated per project and cached ten minutes; `computedAt` says

        when.


        **Rate Limit**: [m] medium - varies by subscription tier'
      tags:
      - Segment
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/SegmentUsage'
                required:
                - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getProjectByProjectSegmentUsage
      x-operation-id-source: derived
  /project/{project}/segment/{uid}:
    get:
      summary: View segment
      description: 'Retrieves details of a specific segment. Supports both static and dynamic segments.


        **Required Scope**: `PROJECT_AUDIENCE_READ`


        **Query Parameters**:

        - `parameter`: (optional) For dynamic segments, the parameter value (e.g., ''val1|val2'')


        **Rate Limit**: [l] large - varies by subscription tier'
      tags:
      - Segment
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      - name: uid
        in: path
        description: Segment UID
        required: true
        schema:
          type: string
      - name: parameter
        in: query
        description: For dynamic segments, the parameter value (e.g., 'val1|val2')
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSegmentItem'
                required:
                - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-stoplight:
        id: n5aazeny2cnif
      operationId: getProjectByProjectSegmentByUid
      x-operation-id-source: derived
components:
  responses:
    NoFundsError:
      description: You're out of money
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    ValidationError:
      description: Some field of your request body is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorValidation'
    NotFound:
      description: Resource can't be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    UnauthorizedError:
      description: You are missing or using bad credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    RateLimitError:
      description: You reached your endpoint rate limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    WrongRequestError:
      description: You request body is malformed or something went wrong with your request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
  schemas:
    ResponseErrorDetail:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
      - title
      - status
      - detail
      x-stoplight:
        id: v3njemo17ya0e
    ResponseErrorValidation:
      type: object
      description: 'A 422 always names the field that is wrong under `errors.fields`, keyed by field

        name, with one or more human-readable reasons. Read the reasons: they say what to

        change. `queryFilter` is the key used when an audience query is malformed (an

        unknown operator, an attribute that does not exist, a node nested too deep).

        '
      properties:
        errors:
          type: object
          properties:
            fields:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
              properties:
                to:
                  type: array
                  items:
                    type: string
                queryFilter:
                  type: array
                  description: Why the audience query was rejected, one entry per reason.
                  items:
                    type: string
                  example:
                  - Unknown attribute "purchase_totl" in condition 2.
          required:
          - fields
      required:
      - errors
      x-stoplight:
        id: 9sf9ijkeqwxhk
    ResponseMetadata:
      type: object
      properties:
        count:
          type: integer
        start:
          type: integer
        limit:
          type: integer
      x-stoplight:
        id: 2uyqyhidqntar
    ResponseErrorMessage:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
      required:
      - message
      x-stoplight:
        id: nzjbrnkttcnxo
    SegmentContacts:
      type: object
      description: 'A segment''s size as served from the segment-size cache, with its age. Never a

        live count: the number is computed when someone looks at the segment and then

        cached, with a TTL that grows with the segment''s size, so always narrate it with

        its age rather than as a current total.

        '
      properties:
        count:
          type: integer
          description: Number of contacts in the segment when it was computed.
          example: 4180
        computedAt:
          type: string
          format: date-time
          description: When the number was computed, ISO 8601.
          example: '2026-08-24T09:12:44+00:00'
        computedAgo:
          type: string
          description: The same instant in words, ready to show or say.
          example: 12 minutes ago
        approximate:
          type: boolean
          description: 'True when the count was sampled instead of counted exactly (very large

            or event-heavy segments), in which case it is rounded to three

            significant figures and `sampleFraction` and `marginPct` are present.

            '
          example: false
        sampleFraction:
          type: number
          format: float
          description: Fraction of the segment actually counted. Only when `approximate` is true.
          example: 0.1
        marginPct:
          type: number
          format: float
          description: Margin of error of the sampled count, in per cent. Only when `approximate` is true.
          example: 1.5
      required:
      - count
      - computedAt
      - computedAgo
      - approximate
    SegmentUsage:
      type: object
      description: 'Where each segment of the project is actually used. **Only segments with at least

        one reference appear**: a segment that is listed but missing here is an orphan,

        which is what this endpoint exists to make visible. Flows carry no segment

        reference and are deliberately not counted.

        '
      properties:
        segments:
          type: object
          description: Keyed by segment uid.
          additionalProperties:
            type: object
            properties:
              campaigns:
                type: integer
                description: Campaigns that have targeted this segment.
                example: 3
              lastTargetedAt:
                type:
                - string
                - 'null'
                format: date-time
                description: When a campaign last targeted it, ISO 8601.
                example: '2026-07-30T10:00:00+00:00'
              automations:
                type: integer
                description: Automations that enroll from this segment.
                example: 2
              activeAutomations:
                type: integer
                description: 'How many of those automations are active. A segment alive only

                  through inactive automations is effectively unused.

                  '
                example: 1
        computedAt:
          type: string
          format: date-time
          description: When the map was aggregated, ISO 8601. Cached ten minutes.
          example: '2026-08-24T09:12:44+00:00'
      required:
      - segments
      - computedAt
    ResponseSegmentItem:
      type: object
      description: Segment entity
      properties:
        contacts:
          allOf:
          - $ref: '#/components/schemas/SegmentContacts'
          description: 'The segment''s cached size. Present on every segment view and on the list

            endpoints, which serve what the cache already holds and never compute.

            **Null means the size is not known yet**, not that the segment is empty:

            a listing returns null for any segment whose size has never been

            computed or has expired, and the single-segment view computes it. Always

            null for parameterized dynamic segments.

            '
        totalContacts:
          type:
          - integer
          - 'null'
          description: 'The same number as `contacts.count`, kept for existing clients. Prefer

            `contacts`, which carries the age of the figure; a bare total invites

            reading a cached number as a live one.

            '
          example: 1247
      additionalProperties: true
      x-stoplight:
        id: 1td95mbeye75x
  securitySchemes:
    BearerAuth:
      description: Token with permissions to access the endpoint
      type: http
      scheme: bearer
    OAuth2:
      description: 'OAuth 2.1 Authorization Code flow with PKCE, for applications that act in a

        user''s name instead of using a token the user pasted. The resulting access

        token is an ordinary Product API bearer token (`isoa_` prefix) with a

        24-hour lifetime, refreshed through `POST /oauth/token`.


        Register the client first with `POST /oauth/register`, or use a `client_id`

        issued by Instasent. PKCE is mandatory and only `S256` is accepted; there is

        no client secret. Discover these URLs at runtime from

        `/.well-known/oauth-authorization-server` rather than hard-coding them. All

        three are on this API host; the authorization URL is a browser redirect that

        hands the user to the dashboard''s consent screen.


        The scopes below are the same product permissions the API returns in

        `GET /` and the dashboard shows when creating a token. Which of them a

        client may be granted depends on its lane: MCP clients are limited to a

        curated, agent-safe subset, while API clients may be offered the full set.

        The final grant is always intersected with the authorizing user''s roles and

        the organization''s plan.

        '
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.instasent.com/oauth/authorize
          tokenUrl: https://api.instasent.com/oauth/token
          refreshUrl: https://api.instasent.com/oauth/token
          scopes:
            ACCOUNT_READ: Read access to organization account details and funds
            PROJECT_DATASOURCE_READ: Read-only access to datasources
            PROJECT_DATASOURCE_WRITE: Create and modify datasources
            PROJECT_AUDIENCE_READ: Read access to audience contacts
            PROJECT_AUDIENCE_WRITE: Write access to audience contacts
            PROJECT_AUDIENCE_LIST: List and scroll audience contacts
            PROJECT_AUDIENCE_DATA_BASIC: Access to basic contact data
            PROJECT_AUDIENCE_DATA_FULL: Access to full contact data
            PROJECT_AUDIENCE_DATA_EVENTS: Access to audience events
            PROJECT_AGGREGATIONS: Access to audience and event aggregations
            PROJECT_SEGMENT_WRITE: Save an audience filter as a segment
            PROJECT_CAMPAIGN_READ: Read access to campaigns
            PROJECT_CAMPAIGN_WRITE: Create a campaign draft
            PROJECT_AUTOMATION_READ: Read access to automations
            PROJECT_DIRECT_READ: Messaging read access
            PROJECT_DIRECT_WRITE: Messaging write access
x-stoplight:
  id: xl7ao4m61duhz