Instasent Sms Sender API

openapi: 3.2.0
info:
  title: Instasent product Sms Sender 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: sms-sender
  description: SMS sender management endpoints
paths:
  /project/{project}/channel/sms/sender:
    get:
      x-see-docs:
      - query-filter
      summary: List SMS senders
      description: 'Lists all SMS senders for a project. Supports Query String Filtering for filtering, sorting, and pagination.


        **Required Scope**: none beyond a product API token with access to the project


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

        - Filtering: Use `field_operator=value` format (e.g., `status_eq=active`, `from_eq=MySender`, `createdAt_gte=2024-01-01T00:00:00+00:00`)

        - Sorting: Use `_sort=field:direction` format (e.g., `_sort=from: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:
      - sms-sender
      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/ResponseSenderItem'
                  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: pfqk8wbz18wt7
      operationId: getProjectByProjectChannelSmsSender
      x-operation-id-source: derived
    post:
      x-see-docs:
      - senders
      summary: Create SMS sender
      description: 'Creates an SMS sender (the alphanumeric name messages are sent from) in the project.

        The sender is created with no registrations: registering it in a country, which asks

        for the legal profile and documents, is done in the dashboard.


        A name already used in the project is refused with `422` on `from`. A name that may

        not be used (a protected brand, or digits that are not a valid international phone

        number) is refused with `451`.


        **Required Scope**: `PROJECT_SENDER_WRITE`


        **Rate Limit**: `[xs]` very restrictive (10 requests per hour per organization), the same on every subscription tier.'
      tags:
      - sms-sender
      parameters:
      - $ref: '#/components/parameters/ProjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: The sender name recipients see. Letters, digits, spaces and `-_.`; a name of digits only must be a valid international phone number.
                  example: MyShop
                messagePrefix:
                  type:
                  - string
                  - 'null'
                  description: Text put before every message sent from this sender.
                unregisteredBypassRouteOptOut:
                  type: boolean
                  default: false
                  description: 'Where a regulator blocks this sender for lack of a registration, the

                    message goes out from a substitute number unless this is true; with

                    true, the message is blocked instead.

                    '
              required:
              - from
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSenderItem'
                required:
                - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Missing scope, or the project already has as many senders as the subscription allows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetail'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '451':
          description: The sender name may not be used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorValidation'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: postProjectByProjectChannelSmsSender
      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'
    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
    ResponseSenderItem:
      type: object
      description: Sender entity
      properties:
        acceptedCountries:
          type: array
          description: 'ISO 3166-1 alpha-2 country codes this sender can deliver to,

            default-allow over the operator catalog: a country is

            reachable unless it requires a registration you do not yet

            have, an enforced regulation gates it, or your register for

            it was rejected/revoked.

            '
          items:
            type: string
          example:
          - ES
          - PT
          - FR
      additionalProperties: true
      x-stoplight:
        id: 3ftgxdbzs3r9j
  parameters:
    ProjectPath:
      name: project
      in: path
      description: Project UID (e.g., 'my-project-123')
      required: true
      schema:
        type: string
  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