Instasent Third Party API

openapi: 3.2.0
info:
  title: Instasent product Third Party 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: third-party
  description: Other endpoints intendend for external services integration
paths:
  /project/{project}/hybrid-auth:
    get:
      summary: Hybrid auth view
      description: 'Handles hybrid authentication for external services (e.g., Zapier). It is used just to verify authentication.


        **Query Parameters**:

        - `datasourceSecretToken`: Token for datasource access

        - `projectSecretToken`: Token for project access

        - `datasourceId`: ID of the datasource (required if `datasourceSecretToken` is used)


        **Response Details**:

        - `entity`: Project or Datasource entity

        - `metadata`: Connection name, privileges, and scopes


        **Use Case**: Handles hybrid authentication for external services (e.g., Zapier). It is used just to verify authentication.'
      tags:
      - third-party
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      - name: datasourceSecretToken
        in: query
        description: Token for datasource access
        required: false
        schema:
          type: string
      - name: projectSecretToken
        in: query
        description: Token for project access
        required: false
        schema:
          type: string
      - name: datasourceId
        in: query
        description: ID of the datasource (required if datasourceSecretToken is used)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    type: object
                    description: Project or Datasource entity
                    additionalProperties: true
                  metadata:
                    type: object
                    properties:
                      connection:
                        type: string
                        description: Connection name
                      privileges:
                        type: array
                        items:
                          type: string
                        description: Privileges
                      scopes:
                        type: array
                        items:
                          type: string
                        description: 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: fy10felnfwbil
      operationId: getProjectByProjectHybridAuth
      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