Instasent General API
General API endpoints for authentication and organization information
General API endpoints for authentication and organization information
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/instasent:instasent-general-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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