Instasent Datasource API

openapi: 3.2.0
info:
  title: Instasent product Datasource 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: datasource
  description: Data source management endpoints for creating and managing data sources
paths:
  /project/{project}/datasource:
    get:
      x-see-docs:
      - query-filter
      summary: List datasources
      description: 'Lists all `dsapi` type datasources for a project. Supports Query String Filtering for filtering, sorting, and pagination.


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

        - Filtering: Use `field_operator=value` format (e.g., `name_eq=MyDatasource`, `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'
      tags:
      - datasource
      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/ResponseDatasourceItem'
                  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: g90er8mmsklo3
      operationId: getProjectByProjectDatasource
      x-operation-id-source: derived
    post:
      summary: Create data source
      description: 'This endpoint allows you to create data sources for your project.


        Currently, only API data sources can be created using this endpoint. Other types of data sources must be manually created using the management dashboard.


        API data sources allow you to input contacts and events through our Ingest API. First, you create the contact, then send its past, present, or future events.


        As a response, you will receive the data source token. This token is specific to the data source and can only be used for sending contacts and events to it.'
      tags:
      - datasource
      parameters:
      - name: project
        in: path
        description: Project identifier
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/DatasourceItemBody'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseDatasourceItem'
                required:
                - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-stoplight:
        id: sapv4z60yco0a
      operationId: postProjectByProjectDatasource
      x-operation-id-source: derived
  /project/{project}/datasource/{id}:
    get:
      summary: View datasource
      description: 'Retrieves details of a specific datasource.


        **Datasource Parameter**: `{id}` can be the id of a dsapi datasource or just `dsapi`.

        It will be automatically resolved to the first found `type === ''dsapi'' + integration === null` of the project.'
      tags:
      - datasource
      parameters:
      - name: project
        in: path
        description: Project UID (e.g., 'my-project-123')
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Datasource ID or 'dsapi' to use the first dsapi datasource
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseDatasourceItem'
                  metadata:
                    type: object
                    properties:
                      capabilities:
                        type:
                        - object
                        - 'null'
                        description: What a native integration can deliver. Null for API, DSAPI and CSV sources, whose events are the ones the project sends (see the event specs).
                        properties:
                          events:
                            type: array
                            description: Instasent event types this integration emits.
                            items:
                              type: string
                          delivery:
                            type:
                            - string
                            - 'null'
                            enum:
                            - realtime
                            - periodic
                            - null
                            description: realtime when the provider pushes events, periodic when they are fetched on a schedule.
                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: q1z5ysvpfm95z
      operationId: getProjectByProjectDatasourceById
      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'
    RequestTooLarge:
      description: You are sending a large body in your request
      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'
  requestBodies:
    DatasourceItemBody:
      description: A single Datasource item
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestDatasourceItem'
          examples:
            basic:
              summary: Standard API data source
              value:
                name: My API data source
                description: This is a test data source
                audienceTags:
                - auto-tag-for-all-imported-contacts
                defaultCountry: ES
                locale: en_US
                timezone: America/Los_Angeles
            ecommerce:
              summary: API data source with support for E-commerce events
              value:
                name: My API data source
                description: This is a test data source
                audienceTags:
                - auto-tag-for-all-imported-contacts
                tags:
                - ecommerce
                defaultCountry: ES
                locale: en_US
                timezone: America/Los_Angeles
  schemas:
    ResponseDatasourceItem:
      type: object
      properties:
        id:
          type: string
        uid:
          type: string
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        token:
          type: object
          properties:
            id:
              type: string
            token:
              type: string
            title:
              type: string
            createdAt:
              type: string
        type:
          type: string
        integration:
          type:
          - string
          - 'null'
        deleted:
          type: boolean
        priority:
          type: string
        locale:
          type: string
        timezone:
          type: string
        defaultCountry:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
        uniqueDsfield:
          type:
          - string
          - 'null'
          description: The unique identifier field for this datasource (e.g., `_user_id`).
        sequenceDate:
          type:
          - string
          - 'null'
          format: date-time
          description: When the current data sequence started (used for CSV batch imports).
        audienceTags:
          type:
          - array
          - 'null'
          items:
            type: string
        projectAttributeMappings:
          type:
          - array
          - 'null'
          description: List of field mappings that define how datasource fields map to project attributes.
          items:
            $ref: '#/components/schemas/ProjectAttributeMapping'
      required:
      - id
      - uid
      - name
      - type
      - integration
      - locale
      - timezone
      - defaultCountry
      - createdAt
      - audienceTags
      x-stoplight:
        id: 6u3xd6qilofef
    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
    RequestDatasourceItem:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        audienceTags:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        defaultCountry:
          type: string
        locale:
          type: string
        timezone:
          type: string
      required:
      - name
      - audienceTags
      x-stoplight:
        id: se7aijsen5gaf
    ProjectAttributeMapping:
      type: object
      description: Defines how a datasource field maps to a project attribute.
      properties:
        dsfield:
          type: string
          description: The datasource field name (e.g., `email`, `first_name`, `_user_id`).
        projectAttributeUid:
          type: string
          description: UID of the project attribute this field maps to.
        label:
          type: string
          description: Human-readable label for the mapping.
        priority:
          type:
          - integer
          - 'null'
          description: Optional custom priority for this field's value during merging. When null, the datasource default priority is used.
        autoSystemMapping:
          type: boolean
          description: Whether this mapping was auto-generated by the system.
      required:
      - dsfield
      - projectAttributeUid
      - label
      - autoSystemMapping
  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