Instasent General API

openapi: 3.2.0
info:
  title: Instasent product General 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: General
  description: General API endpoints for authentication and organization information
paths:
  /:
    get:
      summary: Get organization info and list projects
      description: 'Retrieves information about the authenticated organization, usually used for authentication validation.

        This endpoint returns the organization token details, the projects that the token has access to,

        and organization summary information.


        **Use Cases**:

        - Validate authentication and token validity

        - Discover which projects your token can access

        - Check granted scopes and permissions


        **Response Details**:

        - `entity`: Contains the organization token and the projects that the token has access to

        - `metadata`: Organization summary. Will include more details if the token has the `ACCOUNT_READ` scope


        **Rate Limit**: [l] large - varies by subscription tier'
      tags:
      - General
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    type: object
                    description: Organization token with accessible projects
                    additionalProperties: true
                  metadata:
                    type: object
                    properties:
                      organization:
                        type: object
                        description: Organization summary
                        additionalProperties: true
                      dataMode:
                        type: string
                        description: 'The strictest data-access mode across every project this

                          credential can reach. `normal` is full access; under

                          `anonymized` personal identifiers come back masked; under

                          `blocked` no contact data is readable at all.

                          '
                        enum:
                        - normal
                        - anonymized
                        - blocked
                        example: normal
                      dataPolicy:
                        type: object
                        description: 'What `dataMode` actually means for this credential, resolved

                          server-side so no client has to interpret the mode itself.

                          Read these two booleans rather than deriving access from the

                          mode name, and treat their absence as no access.

                          '
                        properties:
                          mayReadContactData:
                            type: boolean
                            description: Whether contact records can be read at all.
                            example: true
                          mayReadPii:
                            type: boolean
                            description: 'Whether personal identifiers (phone, email) come back

                              readable rather than masked, and whether they can be

                              searched by.

                              '
                            example: true
                        required:
                        - mayReadContactData
                        - mayReadPii
                      scopes:
                        type: array
                        items:
                          type: string
                        description: Array of granted scopes
                    additionalProperties: true
                required:
                - entity
                - metadata
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-stoplight:
        id: vfqqt49vf5lqx
      operationId: getRoot
      x-operation-id-source: derived
components:
  schemas:
    ResponseErrorDetail:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
      - title
      - status
      - detail
      x-stoplight:
        id: v3njemo17ya0e
    ResponseErrorMessage:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
      required:
      - message
      x-stoplight:
        id: nzjbrnkttcnxo
  responses:
    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'
  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