Instasent Specifications API
The specifications API from Instasent — 4 operation(s) for specifications.
The specifications API from Instasent — 4 operation(s) for specifications.
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-specifications-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 - Ingest Specifications API
version: 1.0.3
description: '!Ingest API Diagram
### Overview
The Instasent Ingest API is a powerful tool to import **contacts** and **events** into your project. This API allows organizations to consolidate customer data and track interactions, enabling advanced audience segmentation and personalized marketing. #### What is the Ingest API? The Ingest API is a small subset of the Product API that enables you to **add or update contact data and record events** for each contact within your Instasent project. It functions as an independent Data Source within your project''s unified audience, having priority over other data sources when conflicts arise. This setup allows for seamless centralization of customer data, enhancing your understanding of customer behavior and engagement. - **Contacts**: Represent individuals in your audience, such as customers, leads, or other relevant profiles. - **Events**: Document interactions by these contacts, such as purchases, email opens, clicks, or other custom activities (e.g., "viewed product" or "made a reservation"). #### Why use the Ingest API? Using the Ingest API, businesses can:
1. **Unify Customer Data**: Consolidate data from various sources into Instasent, creating a 360º view of each contact. Data from this API takes precedence over other sources in cases of overlapping information. 2. **Automate Data Updates**: Automatically sync new or updated data from external platforms (e.g., CRM, e-commerce). 3. **Enable Targeted Marketing**: Segment audiences based on attributes or recorded events to enable precise targeting in campaigns. 4. **Track Engagements**: Record customer interactions to measure engagement and improve marketing strategies. #### Key Functionalities
1. **Create or Update Contacts**:
- The `/stream/contacts` endpoint allows bulk uploading of contact data, handling up to 100 contacts per request. Existing contacts are updated unless fields are explicitly left blank or set to null. 2. **Delete Contacts**:
- Use the `/stream/contacts/{userId}` endpoint to delete a contact, permanently removing their profile from your audience. 3. **Add Events**:
- The `/stream/events` endpoint records contact interactions like purchases, views, or other actions. Note that events are immutable and cannot be updated once created. 4. **Get Stream Information**:
- The `/stream` endpoint returns information about the stream, including organization, project, and datasource details along with usage statistics. 5. **Get Attributes and Events Specs**:
- The `/stream/specs/attributes` and `/stream/specs/events` endpoints provide detailed information about the attributes and events supported by the Ingest API, including data types, validation rules, and other specifications. 6. **Get Event Parameters Specs**:
- The `/stream/specs/event-parameters/{eventType}` endpoint provides detailed information about the parameters supported for a specific event type. #### Who Should Use This API? - **Marketers and CRM Managers**: Automate segmentation and targeting of contacts based on real-time data. - **Developers and Data Integrators**: Seamlessly connect Instasent with CRM, e-commerce, or other data systems for continuous updates and customer insights. #### Example Use Case
Suppose a customer makes a purchase on your website. Your e-commerce system sends this purchase event to Instasent using the Ingest API. Instasent updates the contact''s profile and triggers any automations you have set up, such as a thank-you SMS. This event is stored in the contact''s timeline, helping your team understand the customer''s journey. #### Technical Notes
- **API Token**: The Ingest API requires a unique token for secure access. Each data source has its own token. - **Rate Limits**: Requests are rate-limited according to your subscription plan. #### Useful Links
1. **Instasent APIs Overview**: Check our diagram
2. **Instasent API Docs**: Visit https://docs.instasent.com to discover all our available APIs
3. **Ingest API Samples**: Check our repo'
contact:
email: dev@instasent.com
url: https://instasent.com
name: Instasent
servers:
- url: https://api.instasent.com/v1/project/{project}/datasource/{datasource}
description: Instasent Webhooks - Ingest API
variables:
project:
default: project
description: Project identifier
datasource:
default: id
description: Datasource identifier
security:
- BearerAuth: []
tags:
- name: specifications
paths:
/stream:
get:
summary: Get stream information
description: Returns information about the stream, including organization, project, and datasource details along with usage statistics. Use this one for auth validation.
tags:
- specifications
responses:
'200':
description: Stream information and statistics
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/OrganizationInfo'
stream:
$ref: '#/components/schemas/StreamInfo'
datasource:
$ref: '#/components/schemas/DatasourceInfo'
project:
$ref: '#/components/schemas/ProjectInfo'
'401':
$ref: '#/components/responses/UnauthorizedError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
operationId: getStream
x-operation-id-source: derived
/stream/specs/attributes:
get:
summary: Get available contact attributes
description: Returns the list of available attributes that contacts can have, including their data types and validation rules.
tags:
- specifications
responses:
'200':
description: List of available attributes
content:
application/json:
schema:
type: object
properties:
specs:
type: array
items:
$ref: '#/components/schemas/AttributeSpec'
'401':
$ref: '#/components/responses/UnauthorizedError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
operationId: getStreamSpecsAttributes
x-operation-id-source: derived
/stream/specs/events:
get:
summary: Get available event types
description: Returns the list of available event types that can be tracked.
tags:
- specifications
responses:
'200':
description: List of available event types
content:
application/json:
schema:
type: object
properties:
specs:
type: array
items:
$ref: '#/components/schemas/EventTypeSpec'
'401':
$ref: '#/components/responses/UnauthorizedError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
operationId: getStreamSpecsEvents
x-operation-id-source: derived
/stream/specs/event-parameters/{eventType}:
get:
summary: Get parameters for event type
description: Returns the list of available parameters for a specific event type.
tags:
- specifications
parameters:
- name: eventType
in: path
description: Event type identifier
required: true
schema:
type: string
responses:
'200':
description: List of available parameters for the event type
content:
application/json:
schema:
type: object
properties:
specs:
type: array
items:
$ref: '#/components/schemas/EventParameterSpec'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
$ref: '#/components/responses/InternalError'
operationId: getStreamSpecsEventParametersByEventType
x-operation-id-source: derived
components:
schemas:
DatasourceInfo:
type: object
properties:
name:
type: string
id:
type: string
uid:
type: string
type:
type: string
integration:
type:
- string
- 'null'
sequence:
type: integer
priority:
type: integer
locale:
type: string
timezone:
type: string
defaultCountry:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
AttributeSpec:
type: object
properties:
requiredInWebhook:
type: boolean
important:
type: boolean
uid:
type: string
adhocUid:
type:
- string
- 'null'
description:
type: string
dataType:
type: string
visualType:
type: string
readonly:
type: boolean
visible:
type: boolean
custom:
type: boolean
unique:
type: boolean
displayLabel:
type: string
multivalue:
type: integer
createdByDatasourceType:
type:
- string
- 'null'
createdByDatasourceUid:
type:
- string
- 'null'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ResponseErrorDetail:
type: object
properties:
title:
type: string
status:
type: integer
detail:
type: string
required:
- title
- status
- detail
EventParameterSpec:
type: object
properties:
parameter:
type: string
title:
type: string
description:
type: string
icon:
type: string
dataType:
type: string
visualType:
type: string
maxLength:
type: integer
required:
type: boolean
multiValue:
type: integer
ProjectInfo:
type: object
properties:
locale:
type: string
timezone:
type: string
name:
type: string
id:
type: string
uid:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ResponseErrorMessage:
type: object
properties:
message:
type: string
code:
type: integer
required:
- message
StreamInfo:
type: object
properties:
exposed:
type: boolean
id:
type: string
type:
type: string
purpose:
type:
- string
- 'null'
callsTotal:
type: integer
callsSuccess:
type: integer
callsFailures:
type: integer
processedEntitiesSuccess:
type: integer
processedEntitiesFailures:
type: integer
lastSuccessTime:
type:
- string
- 'null'
format: date-time
lastFailureTime:
type:
- string
- 'null'
format: date-time
lastCallTime:
type:
- string
- 'null'
format: date-time
EventTypeSpec:
type: object
properties:
uid:
type: string
name:
type: string
description:
type: string
category:
type: string
attribution:
type: boolean
automation:
type: boolean
icon:
type: string
emoji:
type: string
important:
type: boolean
OrganizationInfo:
type: object
properties:
id:
type: string
name:
type: string
plan:
type: string
quality:
type: integer
responses:
RateLimitError:
description: You reached your endpoint rate limit
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseErrorMessage'
NotFound:
description: Resource can't be found
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'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Ingest API token for the datasource. This token is specific for the datasource.
externalDocs:
url: https://docs.instasent.com
description: Access to external documentation