openapi: 3.0.0 x-stoplight: id: xl7ao4m61duhz info: title: Instasent product 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. **Campaign & Automation Insights**: - View campaign details and status - Access automation configurations and settings - Track campaign and automation performance 6. **Direct Messaging**: - Send direct SMS messages to audience contacts - Manage SMS senders for projects - Retrieve SMS message history by contact, campaign, automation, or send entity - Subscribe/unsubscribe contacts from SMS and email communications 7. **Multi-Project Architecture**: - Set up multiple isolated projects within an organization - Each project maintains its own data sources, audience, and configurations - Ideal for managing different brands, customer segments, or marketing initiatives 8. **Secure & Granular Access Control**: - Generate API tokens with specific scopes and permissions - Use datasource-specific tokens for write-only access - Control data visibility based on subscription plans and token scopes - Implement role-based access for different team members ### Components of an Organization - **Organization**: Represents a company and contains settings, billing, and permissions. Each organization has: - **Projects**: Independent areas where customer data and campaigns are managed. - **User Accounts**: Multiple users with varying permission levels can be set up to manage the organization. - **API Tokens**: Unique tokens for secure API access, specific to each organization and managed by privilege level. ### Components of a Project - **Data Sources**: Collections of contacts, events, and customer data. Multiple data sources, such as CSV files, third-party integrations, and APIs, can feed into a project. Each data source maintains its own collection of contacts, but these contacts are automatically merged into the project's unified audience based on matching unique identifiers. - **Contacts**: Individual records representing customers, leads, or other audience members. Contacts exist in two forms: - **Datasource Contacts**: Original contact records stored within each data source - **Audience Contacts / Project Audience**: Unified contact records created by merging datasource contacts that share matching merging attributes (e.g., `_user_id`, `_email`, `_phone_mobile`). Also known as "Audience". The consolidated collection of all audience contacts in a project. This is where contacts from multiple data sources are automatically merged based on their unique identifiers. The unified audience provides a single, comprehensive view of each customer across all data sources. - **Events**: Immutable records of customer interactions, such as purchases, views, or any other tracked activity. Events are associated with datasource contacts and are automatically aggregated into the unified audience contact when contacts are merged. - **Audience Segments**: Customizable groups of contacts based on attributes or behaviors, used for targeted marketing. Segments operate on the unified audience, allowing you to target customers regardless of which data source their data originated from. - **Campaigns and Automations**: Tools for sending messages to specific segments or triggering messages automatically based on events. Campaigns and automations work with the unified audience, ensuring consistent messaging across all customer touchpoints. ### Technical Details - **API Tokens**: Access to the Product API requires secure API tokens specific to each organization or project. - **Rate Limits**: To ensure performance, requests to the Product API are rate-limited based on the subscription plan [s, m, l, xl] ### Scopes (Permissions) Tokens can have specific scopes assigned to control access levels. The available scopes for the Product API are: * **Datasource Management**: * `PROJECT_DATASOURCE_READ`: Read-only access to datasources. * `PROJECT_DATASOURCE_WRITE`: Create and modify datasources. * **Organization Management**: * `ACCOUNT_READ`: Read access to organization account details + funds. * **Audience Management**: * `PROJECT_AUDIENCE_READ`: Read access to audience contacts. * `PROJECT_AUDIENCE_WRITE`: Write access to audience contacts. * `PROJECT_AUDIENCE_LIST`: List audience contacts (*Requires specific subscription plan*). * `PROJECT_AUDIENCE_DATA_BASIC`: Access to basic contact data (*Requires specific subscription plan*). * `PROJECT_AUDIENCE_DATA_FULL`: Access to full contact data (*Requires to be manually granted by Instasent*). * `PROJECT_AUDIENCE_DATA_EVENTS`: Access to audience events (*Requires specific subscription plan*). * `PROJECT_AGGREGATIONS`: Access to audience and event aggregations (*Requires to be manually granted by Instasent*). * **Campaign Management**: * `PROJECT_CAMPAIGN_READ`: Read access to campaigns. * **Automation Management**: * `PROJECT_AUTOMATION_READ`: Read access to automations. * **Messaging Access**: * `PROJECT_DIRECT_READ`: Messaging read access * `PROJECT_DIRECT_WRITE`: Messaging write access (required for creating direct SMS messages) ### Data Privacy & Scopes The amount of contact data returned by the API depends on the scopes assigned to the token and the organization's subscription plan. | Privilege Level | Required Scope | Data Returned | | :--- | :--- | :--- | | **Default** | `PROJECT_AUDIENCE_READ` | Full Name and User ID only. | | **Basic** | `PROJECT_AUDIENCE_DATA_BASIC` | Phone, Email, Country, Name and all boolean fields. | | **Full** | `PROJECT_AUDIENCE_DATA_FULL` | Full contact data (PII). | > **NOTE**: > - `PROJECT_AUDIENCE_LIST` is required for any endpoint that returns a list of contacts (scroll/search). > - `PROJECT_AUDIENCE_DATA_EVENTS` is required to access any event-related data. > - `PROJECT_AGGREGATIONS` is required for aggregation endpoints. It is manually granted by Instasent and is not generally available. It is reserved for trusted partners and requires approval. > - `PROJECT_AUDIENCE_DATA_FULL` is not generally available, it is reserved for trusted partners and requires approval by Instasent. It is not usually granted to customers. ### How Contacts Merge into the Project Unified Audience The unified audience is created by automatically combining contacts from all data sources within a project. When contacts from different data sources share matching values in their **merging attributes**, they are merged into a single audience contact: - **Primary Merging Attribute**: `_user_id` - If two contacts from different data sources have the same `_user_id`, they are automatically merged into one audience contact. - **Additional Merging Attributes**: Projects can configure additional attributes as merging attributes (e.g., `_email`, `_phone_mobile`). Contacts matching on any of these attributes will also be merged. - **Data Consolidation**: When contacts are merged, their attributes are combined. If multiple data sources provide values for the same attribute, the system uses priority rules to determine which value to keep. - **Event Aggregation**: All events from merged contacts are associated with the unified audience contact, providing a complete view of customer interactions across all data sources. - **Source Tracking**: The unified audience contact maintains references to all original data source contacts (`_datasources` and `_ds_contact_ids` attributes), allowing you to trace data back to its source. **Example**: If a contact with `_user_id: "12345"` exists in both your CRM data source and your e-commerce data source, they will be merged into a single audience contact. The resulting contact will contain attributes from both sources, and all events from both sources will be associated with this unified contact. ### Useful Links - **Instasent API Documentation**: [Full documentation](https://docs.instasent.com) - **Instasent APIs Overview Diagram**: [API diagram](https://lucid.app/publicSegments/view/e2941f34-b88e-4b96-a7f8-af65e1bf9dc8/image.png) 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: [] tags: - name: general description: General API endpoints for authentication and organization information - name: project description: Project management and configuration endpoints - name: datasource description: Data source management endpoints for creating and managing data sources - name: audience description: Audience contact management, search, and filtering endpoints - name: stream description: Stream endpoints for ingesting contacts and events into data sources - name: segment description: Segment management endpoints for creating and managing audience segments - name: campaign description: Campaign management endpoints for viewing campaign details - name: automation description: Automation management endpoints for viewing automation details - name: sms description: SMS message endpoints for sending and retrieving SMS messages - name: sms-sender description: SMS sender management endpoints - name: third-party description: Other endpoints intendend for external services integration 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 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 '/project/{project}': get: summary: Get project info description: | Retrieves information about a specific project within your organization. **Required Scope**: Token must have access to the specified project **Response Details**: - `entity`: The project entity with project details. Important properties include: - `id`: Project internal ID - `uid`: Project UID (used in API paths) - `name`: Project name - `description`: Project description - `projectType`: Type of project (e.g., `standard`) - `projectStatus`: Project status (e.g., `active`) - `locale`: Project locale (e.g., `es_ES`) - `timezone`: Project timezone (e.g., `Europe/Madrid`) - `defaultSmsSender`: ID of the default SMS sender - `generalConfig`: General project configuration (auto-create settings, opt-in/out keywords) - `attributionConfig`: Attribution tracking configuration (time windows for attribution) - `createdAt`: When the project was created - `updatedAt`: When the project was last updated - `metadata`: Contains: - `uniqueAttributes`: Array of attribute UIDs that are marked as unique (used for contact merging) - `organization`: Organization summary (includes plan, API tier, account funds/credits) - `scopes`: Array of granted scopes for the current token **Rate Limit**: [l] large - varies by subscription tier tags: - project 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: entity: $ref: '#/components/schemas/ResponseProjectItem' metadata: type: object properties: uniqueAttributes: type: array items: type: string description: Array of attribute UIDs that are marked as unique (used for contact merging) organization: type: object description: Organization summary (includes plan, API tier, account funds/credits) additionalProperties: true scopes: type: array items: type: string description: Array of granted scopes required: - uniqueAttributes additionalProperties: true required: - entity - metadata examples: standard: summary: Standard project response value: entity: id: '67bdfa983114d0062d732655' uid: 'my-empty-project' name: 'My empty project' description: null projectType: 'standard' projectStatus: 'active' locale: 'es_ES' timezone: 'Europe/Madrid' defaultSmsSender: '68ad7ad14b8e760c1541f542' shortTrackingDomain: null unsubscribeTrackingDomain: null businessType: null businessContactsSize: 1013 businessUrl: 'https://www.marin.org/ex-maxime-culpa-omnis-repudiandae-tempora-quasi' lockedUntil: null lockedReason: null testSmsNumbers: [] conversionConfig: null attributionConfig: hoursSmsCampaignSent: 24 hoursOtherCampaignSent: 24 hoursCampaignCta: 120 hoursCampaignOpen: 120 hoursFindOutboundSms: 168 generalConfig: channelDefaults: optInKeywords: null optOutKeywords: null autoCreateContactsOnInbounds: true autoCreateContactsOnOutbounds: true marketingOptOutScope: per_channel marketingOptInScope: per_channel channelSms: null channelEmail: null brand: null createdAt: '2025-02-25T18:13:46+01:00' updatedAt: '2025-09-09T17:27:23+02:00' metadata: uniqueAttributes: - '_user_id' organization: id: '60141bb26dccbf21a04a01d2' name: 'Instasent Frontend' plan: key: 'premium_profile' quality: 3 status: 'active' api: tier: 5 extendedSupport: - 'ROLE_ORGANIZATION_PROJECT_AUDIENCE_DATA_BASIC' - 'ROLE_ORGANIZATION_PROJECT_AUDIENCE_DATA_EVENTS' - 'ROLE_ORGANIZATION_PROJECT_AUDIENCE_LIST' - 'ROLE_ORGANIZATION_PROJECT_AGGREGATIONS' account: funds: currency: 'EUR' value: 2000.288 credit: currency: 'EUR' value: 28.527 resetAt: '2025-03-28T08:00:55+01:00' resetTo: 30.99 scopes: - 'PROJECT_DATASOURCE_READ' - 'PROJECT_AUDIENCE_READ' - 'PROJECT_AUDIENCE_DATA_BASIC' - 'PROJECT_DIRECT_WRITE' - 'PROJECT_AUDIENCE_LIST' - 'ACCOUNT_READ' - 'PROJECT_DIRECT_READ' - 'PROJECT_DATASOURCE_WRITE' - 'PROJECT_AUDIENCE_WRITE' - 'PROJECT_AUDIENCE_DATA_EVENTS' - 'PROJECT_CAMPAIGN_READ' - 'PROJECT_AUTOMATION_READ' - 'PROJECT_AGGREGATIONS' '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: 1lk93ptjalqxr '/project/{project}/specs/attributes': get: summary: Get project attributes specs description: | Retrieves the list of enabled project attributes (attribute specifications) for a project. These are the available fields that can be used for contacts in the project. **Use Cases**: - Discover which attributes are available for contacts in this project - Understand attribute types and constraints before creating contacts - Validate attribute names before sending data to the stream API - Identify unique attributes used for contact merging - Check which attributes are readonly, custom, or internal **Response Details**: - `entities`: Array of enabled project attribute specifications. Each attribute includes: - `uid`: The attribute identifier (e.g., `_full_name`, `_user_id`) - `displayLabel`: Human-readable label for the attribute - `dataType`: The data type (e.g., `string`, `number`, `boolean`, `date`) - `visualType`: The visual representation type - `enabled`: Whether the attribute is enabled for use - `readonly`: Whether the attribute is read-only - `unique`: Whether the attribute is unique (used for merging contacts) - `custom`: Whether the attribute is custom (user-created) - `internal`: Whether the attribute is internal-only - `multivalue`: Maximum number of values allowed (1 = single value) - `mappeable`: Whether the attribute can be mapped from datasources - `eventBased`: Whether the attribute is derived from events - `description`: Localized description of the attribute - `metadata`: Contains: - `uniqueAttributes`: Array of attribute UIDs that are marked as unique (used for contact merging) - `organization`: Organization summary - `scopes`: Array of granted scopes **Rate Limit**: [s] restrictive - varies by subscription tier tags: - project 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/AttributeSpec' description: Array of enabled project attribute specifications metadata: type: object properties: uniqueAttributes: type: array items: type: string description: Array of attribute UIDs that are marked as unique (used for contact merging) organization: type: object description: Organization summary additionalProperties: true scopes: type: array items: type: string description: Array of granted scopes required: - uniqueAttributes required: - entities - metadata '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: wt1q2uuyc2ni2 '/project/{project}/specs/events': get: summary: Get project events specs description: | Retrieves the list of available event types and their specifications for a project. This endpoint uses a mock datasource to determine the available event types. **Use Cases**: - Discover which event types are available for this project - Understand event structure and properties before creating events - Validate event types before sending data to the stream API - Identify which events support attribution or automation triggers **Response Details**: - `entities`: Array of event type specifications. Each event includes: - `uid`: The event type identifier (e.g., `appointment`, `ecommerce_order_create`) - `name`: Human-readable name for the event type - `description`: Description of what the event represents - `category`: Event category (e.g., `contact_behaviour`, `ecommerce`) - `attribution`: Whether the event supports attribution tracking - `automation`: Whether the event can trigger automations - `important`: Whether the event is marked as important - `icon`: Icon identifier for the event type - `emoji`: Emoji representation of the event type **Rate Limit**: [s] restrictive - varies by subscription tier tags: - project 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/EventSpec' description: Array of available event type specifications required: - entities '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: vmuk4icujmbyr '/project/{project}/specs/events/{eventType}': get: summary: Get event parameters specs description: | Retrieves the parameter specifications for a specific event type. This allows you to understand what parameters are available when creating events of this type. **Use Cases**: - Discover required and optional parameters for a specific event type - Understand parameter types, constraints, and validation rules - Validate event data before sending to the stream API - Check maximum length constraints for string parameters - Identify which parameters support multiple values **Response Details**: - `entities`: Array of parameter specifications for the event type. Each parameter includes: - `parameter`: The parameter identifier (e.g., `order-id`, `order-currency`) - `title`: Human-readable title for the parameter - `description`: Description of the parameter and its purpose - `dataType`: The data type (e.g., `keyword`, `number`, `date`) - `visualType`: The visual representation type - `required`: Whether the parameter is required - `multiValue`: Maximum number of values allowed (1 = single value) - `maxLength`: Maximum length for string parameters (if applicable) - `icon`: Icon identifier for the parameter type - `metadata`: Contains: - `event`: The event type specification object (if found), matching the structure returned by `/specs/events` **Note**: Each event type has its own set of parameters. Use `/specs/events` to discover available event types first. **Rate Limit**: [s] restrictive - varies by subscription tier tags: - project parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: eventType in: path description: 'Event type UID (e.g., ''ecommerce_order_create'', ''appointment'')' required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/EventParameterSpec' description: Array of parameter specifications for the event type metadata: type: object properties: event: $ref: '#/components/schemas/EventSpec' description: Event type specification (if found) additionalProperties: true required: - entities - metadata '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: bpwrh8qd8z8q6 '/project/{project}/datasource': get: 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 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 '/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' 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 '/project/{project}/audience/user/{userId}': get: summary: Get audience contact by user_id description: | Retrieves contact information for a specific user within a project's audience. The system will search for the user in any of the unique attributes configured in the project (e.g., email, phone, _user_id). **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [m] moderate - varies by subscription tier **Search Behavior**: - If the userId matches an audience contact ID format, it retrieves directly by ID - If it matches a datasource contact ID format, it searches for it - Otherwise, it searches across all unique attributes configured in the project **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. Remember, an audience contact may contain data from multiple data sources if the contact is present in more than one. The **_datasources** attribute indicates which data sources are providing data to the contact. To update an audience contact you must feed the corresponding data source with the updated data. It will automatically update the data source contact and after a few seconds, the audience contact will be refreshed. **Search ID Resolution**: - In case it's an id with an audience id format it will retrieve directly by id - In case it's a datasource contact id format, it will retrieve by searching for it - Otherwise, it searches across all unique attributes configured in the project Only 1 user will be returned, the first that matches. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: userId in: path description: 'User identifier to search for in any of the unique attributes (e.g., email, phone, _user_id)' required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseAudienceItem' 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: zk1yrato9qcsx '/project/{project}/audience/search/phone/{userPhone}': get: summary: Search audience contacts by phone description: | Searches for up to 10 audience contacts matching a specific phone number. The phone number is normalized automatically (non-numeric characters are removed and a `+` prefix is added). **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [m] moderate - varies by subscription tier **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: userPhone in: path description: Phone number to search for (will be normalized automatically) required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseAudienceItem' maxItems: 10 description: Array of up to 10 audience contact entities 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: 1kegihud8mka5 '/project/{project}/audience/search/email/{userEmail}': get: summary: Search audience contacts by email description: | Searches for up to 10 audience contacts matching a specific email address. **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [m] moderate - varies by subscription tier **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: userEmail in: path description: Email address to search for required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseAudienceItem' maxItems: 10 description: Array of up to 10 audience contact entities 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: ioztdykh6ykee '/project/{project}/audience/{audienceId}': get: summary: Get audience contact by ID description: | Retrieves contact information for a specific audience contact by its internal ID. **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [m] moderate - varies by subscription tier **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: audienceId in: path description: Internal audience contact ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseAudienceItem' 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: qoqbrhmorojew '/project/{project}/audience/{audienceId}/events': get: summary: Get audience contact events description: | Retrieves latest 5 events of each type associated with a specific audience contact. **Required Scope**: `PROJECT_AUDIENCE_READ` AND `PROJECT_AUDIENCE_DATA_EVENTS` **Rate Limit**: [m] moderate - varies by subscription tier **Note**: Extended API scopes required in subscription for event access. Returns latest 5 events of each type associated with the audience contact. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: audienceId in: path description: Internal audience contact ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: events: type: array items: type: object description: Event entity additionalProperties: true description: List of events (latest 5 of each type) required: - events '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: 199wrm1n5c8pd '/project/{project}/audience/search': post: summary: Search audience contacts description: | Searches audience contacts using the powerful Audience Contact Filtering system. Supports offset/limit pagination for simple searches with restrictive rate limits. **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - This endpoint uses offset/limit pagination, not cursor-based pagination like `/scroll` - Offset is always enforced to 0 - this endpoint is designed for simple searches starting from the beginning - Maximum limit is 50 contacts per request (lower than the scroll endpoint's 100 limit) - For large result sets or pagination beyond the first page, use the `/scroll` endpoint instead **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/AudienceSearchRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseAudienceItem' description: List of audience contacts (obfuscated based on token permissions) metadata: type: object properties: totalHits: type: integer description: Total number of matching contacts limit: type: integer description: Contacts per page offset: type: integer description: Always 0 (offset is enforced to 0 for this endpoint) required: - totalHits - limit - offset required: - entities - metadata '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: 0kfbgomot9k3c '/project/{project}/audience/aggregations': post: summary: Aggregate audience contacts description: | Performs aggregations on audience contacts using the powerful Audience Contact Filtering system. Returns only aggregation results without individual contact data. **Required Scope**: `PROJECT_AGGREGATIONS` (Manually granted by Instasent - not generally available) **Rate Limit**: [xs] very restrictive - varies by subscription tier **Important Notes**: - This endpoint requires `PROJECT_AGGREGATIONS` scope which is manually granted by Instasent - No contact entities are returned - limit is enforced to 0 - This endpoint is designed for analytics and reporting use cases - Aggregations are the primary purpose of this endpoint **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/AudienceAggregationsRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: object description: Object containing aggregation results additionalProperties: true metadata: type: object properties: totalHits: type: integer description: Total number of matching contacts required: - totalHits additionalProperties: true required: - entities - metadata '400': $ref: '#/components/responses/WrongRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/NoFundsError' '403': description: Missing PROJECT_AGGREGATIONS scope or subscription support content: application/json: schema: $ref: '#/components/schemas/ResponseErrorDetail' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' x-stoplight: id: audience-aggregations-endpoint '/project/{project}/audience/scroll': post: summary: Scroll audience contacts description: | Lists audience contacts using the powerful Audience Contact Filtering system. Supports cursor-based pagination for iterating through large result sets. **Required Scope**: `PROJECT_AUDIENCE_LIST` (Extended API scope required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - The cursor is a base64 string representing the internal query state, and it expires after 1 minute of inactivity - Maximum limit is 100 contacts per request - Use the cursor from the previous response's metadata to get the next page **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/AudienceScrollRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseAudienceItem' description: List of audience contacts (obfuscated based on token permissions) metadata: type: object properties: totalHits: type: integer nullable: true description: Total number of matching contacts. Only returned on the first page (when no cursor is provided). Subsequent pages return null since the client already has the total from the first response. limit: type: integer description: Contacts per page cursor: type: string nullable: true description: Cursor for the next page. Pass this back in the request body to get the next page. null if no more results required: - totalHits - limit - cursor required: - entities - metadata '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: cmtqy1sy4vrra '/project/{project}/audience/segment/{uid}/scroll': post: summary: Scroll audience contacts by segment description: | Lists audience contacts belonging to a specific segment using the Audience Contact Filtering system. The segment queryFilter is merged into the provided one (you can filter within the segment by providing a root node as body). **Required Scope**: `PROJECT_AUDIENCE_LIST` (Extended API scope required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier. **Important Notes**: - The cursor is a base64 string representing the internal query state, and it expires after 1 minute of inactivity - Maximum limit is 100 contacts per request - For dynamic segments, use the `parameter` query parameter **Data Privacy**: The amount of contact data returned depends on your token's scopes and subscription plan. See [Data Privacy & Scopes](#data-privacy--scopes) for details. The segment queryFilter is merged into the provided one (you can filter within the segment by providing a root node as body). tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: uid in: path description: Segment UID required: true schema: type: string - name: parameter in: query description: 'For dynamic segments, the parameter value (e.g., ''val1|val2'')' required: false schema: type: string requestBody: $ref: '#/components/requestBodies/AudienceScrollRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseAudienceItem' description: List of audience contacts (obfuscated based on token permissions) metadata: type: object properties: totalHits: type: integer nullable: true description: Total number of matching contacts. Only returned on the first page (when no cursor is provided). Subsequent pages return null since the client already has the total from the first response. limit: type: integer description: Contacts per page cursor: type: string nullable: true description: Cursor for the next page. Pass this back in the request body to get the next page. null if no more results required: - totalHits - limit - cursor required: - entities - metadata '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: 4ulttnljvgklc '/project/{project}/event/search': post: summary: Search audience events description: | Searches audience events using the powerful Event Filtering system. Supports offset/limit pagination for simple searches with restrictive rate limits. **Required Scope**: `PROJECT_AUDIENCE_READ` AND `PROJECT_AUDIENCE_DATA_EVENTS` (Extended API scopes required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - This endpoint uses offset/limit pagination, not cursor-based pagination like `/scroll` - Offset is always enforced to 0 - this endpoint is designed for simple searches starting from the beginning - Maximum limit is 50 events per request (lower than the scroll endpoint's 100 limit) - Events are automatically filtered to the last 180 days in paid plans. 30 days in free plans. - For large result sets or pagination beyond the first page, use the `/scroll` endpoint instead For complete documentation on Event Filtering, see [Event QueryFilter documentation](docs/dev/project-audience-event-query-filter.es.md). tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/EventSearchRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseEventItem' description: List of audience events metadata: type: object properties: totalHits: type: integer description: Total number of matching events limit: type: integer description: Events per page offset: type: integer description: Always 0 (offset is enforced to 0 for this endpoint) required: - totalHits - limit - offset required: - entities - metadata '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: 61cbdz34hnyrv '/project/{project}/event/aggregations': post: summary: Aggregate audience events description: | Performs aggregations on audience events using the powerful Event Filtering system. Returns only aggregation results without individual event data. **Required Scope**: `PROJECT_AGGREGATIONS` AND `PROJECT_AUDIENCE_DATA_EVENTS` (Both scopes manually granted by Instasent - not generally available) **Rate Limit**: [xs] very restrictive - varies by subscription tier **Important Notes**: - This endpoint requires `PROJECT_AGGREGATIONS` and `PROJECT_AUDIENCE_DATA_EVENTS` scopes which are manually granted by Instasent - No event entities are returned - limit is enforced to 0 - Events are automatically filtered to the last 180 days in paid plans. 30 days in free plans. - This endpoint is designed for analytics and reporting use cases - Aggregations are the primary purpose of this endpoint For complete documentation on Event Filtering, see [Event QueryFilter documentation](docs/dev/project-audience-event-query-filter.es.md). tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/EventAggregationsRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: object description: Object containing aggregation results additionalProperties: true metadata: type: object properties: totalHits: type: integer description: Total number of matching events required: - totalHits additionalProperties: true required: - entities - metadata '400': $ref: '#/components/responses/WrongRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/NoFundsError' '403': description: Missing PROJECT_AGGREGATIONS or PROJECT_AUDIENCE_DATA_EVENTS scope or subscription support content: application/json: schema: $ref: '#/components/schemas/ResponseErrorDetail' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' x-stoplight: id: event-aggregations-endpoint '/project/{project}/event/scroll': post: summary: Scroll audience events description: | Lists audience events using the powerful Event Filtering system. Supports cursor-based pagination for iterating through large result sets. **Required Scope**: `PROJECT_AUDIENCE_LIST` AND `PROJECT_AUDIENCE_DATA_EVENTS` (Extended API scopes required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - Events are automatically filtered to the last 180 days in paid plans. 30 days in free plans. - The cursor is a base64 string representing the internal query state, and it expires after 1 minute of inactivity - Maximum limit is 100 events per request - Use the cursor from the previous response's metadata to get the next page tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/EventScrollRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseEventItem' description: List of audience events metadata: type: object properties: totalHits: type: integer nullable: true description: Total number of matching events. Only returned on the first page (when no cursor is provided). Subsequent pages return null since the client already has the total from the first response. limit: type: integer description: Events per page cursor: type: string nullable: true description: Cursor for the next page. Pass this back in the request body to get the next page. null if no more results required: - totalHits - limit - cursor required: - entities - metadata '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: uf75ylj41isrq '/project/{project}/event/scroll/{utmType}/{utmId}': post: summary: Scroll audience events by campaign attribution description: | Lists audience events attributed to a specific campaign, automation, or direct message using the powerful Event Filtering system. Supports cursor-based pagination for iterating through large result sets. **Required Scope**: `PROJECT_AUDIENCE_LIST` AND `PROJECT_AUDIENCE_DATA_EVENTS` (Extended API scopes required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - Events are automatically filtered to the last 180 days in paid plans. 30 days in free plans. - The cursor is a base64 string representing the internal query state, and it expires after 1 minute of inactivity - Maximum limit is 100 events per request - Use the cursor from the previous response's metadata to get the next page - For `utmType = 'direct'`, the `utmId` must be the channel type (email, sms...) - The endpoint automatically filters events by `utm-type` and `utm-id` matching the provided parameters - To filter by a specific event type, use the `/scroll/{utmType}/{utmId}/{eventType}` variant endpoint **UTM Attribution Parameters**: - `utmType`: The type of attribution (`campaign`, `automation`, or `direct`) - `utmId`: The ID of the campaign or automation. For `direct` type, it must be the channel type (`sms`, `email`, ...) **Use Cases**: - Retrieve all events attributed to a specific marketing campaign - Track events triggered by a specific automation - Analyze events from direct messaging campaigns For complete documentation on Event Filtering, see [Event QueryFilter documentation](docs/dev/project-audience-event-query-filter.es.md). tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: utmType in: path description: 'The type of attribution (campaign, automation, or direct)' required: true schema: type: string enum: - campaign - automation - direct - name: utmId in: path description: 'The ID of the campaign or automation. For `direct` type, it must be the channel type (`sms`, `email`, ...)' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/EventScrollRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseEventItem' description: List of audience events matching the attribution criteria metadata: type: object properties: totalHits: type: integer nullable: true description: Total number of matching events. Only returned on the first page (when no cursor is provided). Subsequent pages return null since the client already has the total from the first response. limit: type: integer description: Events per page cursor: type: string nullable: true description: Cursor for the next page. Pass this back in the request body to get the next page. null if no more results required: - totalHits - limit - cursor required: - entities - metadata '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: event-scroll-by-attribution '/project/{project}/event/scroll/{utmType}/{utmId}/{eventType}': post: summary: Scroll audience events by campaign attribution and event type description: | Lists audience events attributed to a specific campaign, automation, or direct message, filtered by a specific event type. This is a variant of the attribution scroll endpoint that additionally filters events by event type. **Required Scope**: `PROJECT_AUDIENCE_LIST` AND `PROJECT_AUDIENCE_DATA_EVENTS` (Extended API scopes required in subscription) **Rate Limit**: [s] restrictive - varies by subscription tier **Important Notes**: - Events are automatically filtered to the last 180 days in paid plans. 30 days in free plans. - The cursor is a base64 string representing the internal query state, and it expires after 1 minute of inactivity - Maximum limit is 100 events per request - Use the cursor from the previous response's metadata to get the next page - For `utmType = 'direct'`, the `utmId` must be the channel type (email, sms...) - The endpoint automatically filters events by `utm-type`, `utm-id`, and `event-type` matching the provided parameters **UTM Attribution Parameters**: - `utmType`: The type of attribution (`campaign`, `automation`, or `direct`) - `utmId`: The ID of the campaign or automation. For `direct` type, it must be the channel type (`sms`, `email`, ...) - `eventType`: A specific event type to filter by (e.g., `ecommerce_order_create`, `campaign_cta`, `campaign_send`) **Use Cases**: - Retrieve only `campaign_send` events for a specific campaign - Track only `campaign_cta` (click-through) events for an automation - Analyze specific event types from direct messaging campaigns For complete documentation on Event Filtering, see [Event QueryFilter documentation](docs/dev/project-audience-event-query-filter.es.md). tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: utmType in: path description: 'The type of attribution (campaign, automation, or direct)' required: true schema: type: string enum: - campaign - automation - direct - name: utmId in: path description: 'The ID of the campaign or automation. For `direct` type, it must be the channel type (`sms`, `email`, ...)' required: true schema: type: string - name: eventType in: path description: 'A specific event type to filter by (e.g., ecommerce_order_create, campaign_cta, campaign_send)' required: true schema: type: string requestBody: $ref: '#/components/requestBodies/EventScrollRequest' responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseEventItem' description: List of audience events matching the attribution criteria and event type metadata: type: object properties: totalHits: type: integer nullable: true description: Total number of matching events. Only returned on the first page (when no cursor is provided). Subsequent pages return null since the client already has the total from the first response. limit: type: integer description: Events per page cursor: type: string nullable: true description: Cursor for the next page. Pass this back in the request body to get the next page. null if no more results required: - totalHits - limit - cursor required: - entities - metadata '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: event-scroll-by-attribution-event-type '/project/{project}/datasource/{datasource}/stream': get: summary: View stream description: | Retrieves the active stream for a datasource. **Required Scope**: `PROJECT_DATASOURCE_READ` (for reading datasource related data) **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found in the project. tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: stream: type: object description: Stream details additionalProperties: true datasource: $ref: '#/components/schemas/ResponseDatasourceItem' project: type: object description: Project summary additionalProperties: true organization: type: object description: Organization summary additionalProperties: true required: - stream '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: dtofz12d96tbw '/project/{project}/datasource/{datasource}/stream/specs/{spec}': get: summary: View stream specs description: | Retrieves specifications for the stream (attributes, events, etc.). **Required Scope**: `PROJECT_DATASOURCE_READ` **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first one found. **Spec Types**: `attributes`, `events`, `event-parameters` tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string - name: spec in: path description: 'Specification type (attributes, events, event-parameters)' required: true schema: type: string enum: - attributes - events - event-parameters responses: '200': description: Success content: application/json: schema: type: object properties: specs: type: object description: The requested specifications additionalProperties: true required: - specs '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: mkvgigwq0j08v '/project/{project}/datasource/{datasource}/stream/specs/{spec}/{type}': get: summary: View stream specs with type filter description: | Retrieves specifications for the stream filtered by a specific type. **Required Scope**: `PROJECT_DATASOURCE_READ` **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found. **Spec Types**: `attributes`, `events`, `event-parameters` tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string - name: spec in: path description: 'Specification type (attributes, events, event-parameters)' required: true schema: type: string enum: - attributes - events - event-parameters - name: type in: path description: Optional type filter required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: specs: type: object description: The requested specifications filtered by type additionalProperties: true required: - specs '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: o5bq08dp2jlwg '/project/{project}/datasource/{datasource}/stats': get: summary: View datasource stats description: | Retrieves statistics for a datasource stream. **Required Scope**: `PROJECT_DATASOURCE_READ` **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found. **Response Details**: - `contacts`: Total and errored contact count tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: contacts: type: object properties: total: type: integer description: Total contact count errored: type: integer description: Errored contact count additionalProperties: true datasource: $ref: '#/components/schemas/ResponseDatasourceItem' required: - contacts - datasource '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: 53hcv8togdvv8 '/project/{project}/datasource/{datasource}/stream/contacts/{userId}': get: summary: Get stream contact description: | Retrieves a specific contact from the datasource stream. **Required Scope**: `PROJECT_DATASOURCE_READ` **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found. tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string - name: userId in: path description: User ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: contact: type: object description: The contact entity additionalProperties: true required: - contact '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: rgd0dkrkw8bkm '/project/{project}/datasource/{datasource}/stream/{action}': post: summary: Push data to stream description: | Sends data to the datasource stream. This is the primary endpoint for ingesting contacts and events. **Required Scope**: `PROJECT_DATASOURCE_READ` AND `PROJECT_AUDIENCE_WRITE` (for writing contacts/events) **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found. **Actions**: `contacts`, `events`, etc. - `_sync`: If present, performs synchronous processing (recommended for testing) **Audience Override Feature** (for `contacts` action): When pushing contacts to the stream, you can update an existing audience contact's data by using the audience contact ID as the `_user_id` parameter. This feature allows you to bypass automatic merging and directly target a specific audience contact. **How it works**: - When you provide an audience contact ID (format: `[a-zA-Z0-9]{28}-[0-9]{3}`) as the `_user_id` value, the system will automatically detect it, force merge to that specific audience contact, mark the `_user_id` field as untrusted, and add the `instasent-api-override` tag. **Response**: Processing results with success/failure counts, errors, and accepted items. **Authentication**: You can use the DATASOURCE WEBHOOK TOKEN or the PROJECT TOKEN given it has: - `PROJECT_DATASOURCE_READ`: For reading datasource related data - `PROJECT_AUDIENCE_WRITE`: For writing contacts/Events **Use Cases**: - Update audience contact data directly without relying on automatic merging - Merge data from external systems to specific audience contacts - Override contact attributes for existing audience contacts **Important Notes**: - The audience contact ID must exist in the project - The contact must be new (not already exist in the datasource) for the override to take effect - The `_user_id` field will be marked as untrusted to prevent it from overriding other `_user_id` values during merging tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string - name: action in: path description: 'The action to perform (contacts, events, etc.)' required: true schema: type: string - name: _sync in: query description: 'If present, performs synchronous processing' required: false schema: type: boolean requestBody: $ref: '#/components/requestBodies/StreamPushRequest' responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful status: type: integer description: HTTP status code errors: type: array items: type: object properties: position: type: integer error: type: string item: type: object additionalProperties: true additionalProperties: true description: Array of error objects (if any) accepted: type: array items: type: object properties: position: type: integer item: type: object additionalProperties: true additionalProperties: true description: Array of accepted items required: - success - status - errors - accepted '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: y0hbwo1fycurq '/project/{project}/datasource/{datasource}/stream/{action}/{userId}': delete: summary: Delete from stream description: | Deletes a user from the stream. **Required Scope**: `PROJECT_DATASOURCE_READ` AND `PROJECT_AUDIENCE_WRITE` **Datasource Parameter**: `{datasource}` can be the id of a dsapi datasource or just `dsapi`. It will be automatically resolved to the first found. **Actions**: `contacts`, `events`, etc. - `PROJECT_DATASOURCE_READ`: For reading datasource related data - `PROJECT_AUDIENCE_WRITE`: For writing contacts/Events tags: - stream parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: datasource in: path description: Datasource UID or 'dsapi' to use the first dsapi datasource required: true schema: type: string - name: action in: path description: 'The action (contacts, events, etc.)' required: true schema: type: string - name: userId in: path description: User ID to delete required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object additionalProperties: true '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: 4ebhtawh9nnq2 '/project/{project}/audience/stream/{action}': post: summary: Audience Contact stream actions description: | Performs direct actions on the Audience Contact. Its sole purpose is to allow the API to manage subscription state and delete contacts. These operations cannot be done through an Instasent API Data Source since these fields are stored within a special Data Source `instasent` that is protected and isolated from other Data Sources. **Important**: These subscription attributes are also modified automatically by the platform through unsubscription links, inbound keyword replies (STOP/START), delivery blocks, and admin actions. Use this endpoint only if you manage subscription statuses externally and need direct control. Otherwise, the platform handles consent automatically based on the `compliancePolicy` of each message (`opt-in`, `opt-out`, `basic`, `none`) which determines how contacts can opt-out and what compliance gates are enforced. **Required Scope**: `PROJECT_AUDIENCE_WRITE` **Rate Limit**: [xl] permissive - varies by subscription tier **Actions**: Must be one of: - `subscription-manage`: Direct, atomic subscription management at the audience contact level. Provides independent control over both marketing consent and suppression without implicit escalation. Instasent uses a **two-tier subscription model** per channel: - **Suppression** (`_is_subscribed_{channel}`): hard gate that blocks ALL messages except `none`. - **Marketing consent** (`_accepts_marketing_{channel}`): controls whether marketing messages are allowed. **Body parameters**: - `audienceId` (required): The audience contact ID. - `channel` (required): `sms` or `email`. - `operation` (required): One of the following: | Operation | Attribute changed | Value | Effect | |-----------|-------------------|-------|--------| | `suppress` | `_is_subscribed_{channel}` | `false` | Hard block all messages except none | | `reactivate` | `_is_subscribed_{channel}` | `true` | Remove hard block | | `opt-out` | `_accepts_marketing_{channel}` | `false` | Block marketing messages | | `opt-in` | `_accepts_marketing_{channel}` | `true` | Allow marketing messages | - `reason` (optional): Free-text reason for the operation. - `createdAt` (optional): ISO 8601 datetime. Each operation sets exactly one attribute — no implicit escalation or side effects. Operations are always per-channel — they never affect other channels. - `delete-contact`: Delete a contact from the stream **Query Parameters**: - `_sync`: (optional) If present, performs synchronous processing **Request Body**: JSON object with action-specific fields: - For `subscription-manage`: `audienceId` (required), `channel` (required: sms/email), `operation` (required: suppress/reactivate/opt-out/opt-in), `reason` (optional), `createdAt` (optional) - For `delete-contact`: `audienceId` (required) **Note**: This endpoint automatically resolves to the Instasent datasource for the project. The endpoint uses the same processing logic as the standard stream endpoint but provides a simplified interface for common operations. All actions require the `PROJECT_AUDIENCE_WRITE` scope (or admin privileges) and a product token. tags: - audience parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: action in: path description: The action to perform required: true schema: type: string enum: - subscription-manage - delete-contact - name: _sync in: query description: 'If present, performs synchronous processing' required: false schema: type: boolean requestBody: $ref: '#/components/requestBodies/AudienceStreamActionRequest' responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean description: Boolean indicating if the operation was successful status: type: integer description: 'HTTP status code (202 for success, 422 for failures)' errors: type: array items: type: object properties: position: type: integer description: Index of the item that failed error: type: string description: Error message item: type: object description: The item data that failed additionalProperties: true additionalProperties: true description: Array of error objects (if any) accepted: type: array items: type: object properties: position: type: integer description: Index of the accepted item item: type: object description: The accepted item data additionalProperties: true additionalProperties: true description: Array of accepted items required: - success - status - errors - accepted '400': $ref: '#/components/responses/WrongRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/NoFundsError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' x-stoplight: id: iq8ixzbswbaf6 '/project/{project}/segment': get: summary: List segments description: | Lists all segments for a project. Supports Query String Filtering for filtering, sorting, and pagination. **Required Scope**: `PROJECT_AUDIENCE_READ` **Query Parameters**: Supports Query String Filtering parameters: - Filtering: Use `field_operator=value` format (e.g., `name_eq=MySegment`, `type_eq=static`, `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 **Rate Limit**: [l] large - varies by subscription tier tags: - segment 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/ResponseSegmentItem' 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: 3m3evqyhnqrwt '/project/{project}/segment/dynamic': get: summary: List dynamic segments description: | Lists dynamic segments that don't require parameters. **Required Scope**: `PROJECT_AUDIENCE_READ` **Rate Limit**: [l] large - varies by subscription tier tags: - segment 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/ResponseSegmentItem' 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: 88c1uxq8s7jt3 '/project/{project}/segment/{uid}': get: summary: View segment description: | Retrieves details of a specific segment. Supports both static and dynamic segments. **Required Scope**: `PROJECT_AUDIENCE_READ` **Query Parameters**: - `parameter`: (optional) For dynamic segments, the parameter value (e.g., 'val1|val2') **Rate Limit**: [l] large - varies by subscription tier tags: - segment parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: uid in: path description: Segment UID required: true schema: type: string - name: parameter in: query description: 'For dynamic segments, the parameter value (e.g., ''val1|val2'')' required: false schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseSegmentItem' 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: n5aazeny2cnif '/project/{project}/campaign': get: summary: List campaigns description: | Lists all campaigns for a project. Supports Query String Filtering for filtering, sorting, and pagination. **Required Scope**: `PROJECT_CAMPAIGN_READ` **Query Parameters**: Supports Query String Filtering parameters: - Filtering: Use `field_operator=value` format (e.g., `status_eq=sent`, `purpose_eq=standard`, `campaignAt_gte=2024-01-01T00:00:00+00:00`) - Sorting: Use `_sort=field:direction` format (e.g., `_sort=campaignAt:asc`, `_sort=createdAt:desc`). Defaults to `campaignAt:desc` if no sort is specified - Pagination: Use `_start=0&_limit=50` format. **Important**: When using `_limit`, you must also provide `_start` - JSON QueryFilter: Use `_q` parameter with JSON structure **Rate Limit**: [l] large - varies by subscription tier tags: - campaign 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/ResponseCampaignItem' 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: risxqws304594 '/project/{project}/campaign/{id}': get: summary: View campaign description: | Retrieves details of a specific campaign. **Required Scope**: `PROJECT_CAMPAIGN_READ` **Rate Limit**: [l] large - varies by subscription tier tags: - campaign parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: id in: path description: Campaign ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseCampaignItem' 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: nfat2pokc846n '/project/{project}/automation': get: summary: List automations description: | Lists all automations for a project. Supports Query String Filtering for filtering, sorting, and pagination. **Required Scope**: `PROJECT_AUTOMATION_READ` **Query Parameters**: Supports Query String Filtering parameters: - Filtering: Use `field_operator=value` format (e.g., `status_eq=active`, `purpose_eq=automation`, `createdAt_gte=2024-01-01T00:00:00+00:00`) - Sorting: Use `_sort=field:direction` format (e.g., `_sort=createdAt:asc`, `_sort=updatedAt:desc`). Defaults to `createdAt:desc` if no sort is specified - Pagination: Use `_start=0&_limit=50` format. **Important**: When using `_limit`, you must also provide `_start` - JSON QueryFilter: Use `_q` parameter with JSON structure **Rate Limit**: [l] large - varies by subscription tier tags: - automation 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/ResponseAutomationItem' 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: acnm1byjrfsig '/project/{project}/automation/{id}': get: summary: View automation description: | Retrieves details of a specific automation. **Required Scope**: `PROJECT_AUTOMATION_READ` **Rate Limit**: [l] large - varies by subscription tier tags: - automation parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: id in: path description: Automation ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseAutomationItem' 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: zolmcc1cgpf6x '/project/{project}/channel/sms/sender': get: summary: List SMS senders description: | Lists all SMS senders for a project. Supports Query String Filtering for filtering, sorting, and pagination. **Required Scope**: `PROJECT_READ` **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 '/project/{project}/channel/sms/sms/{id}': get: summary: Get SMS by ID description: | Retrieves a specific SMS message by its ID. **Required Scope**: `PROJECT_DIRECT_READ` **Rate Limit**: [l] large - varies by subscription tier tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: id in: path description: SMS message ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: audienceId: type: string description: The audience contact ID associated with the SMS additionalProperties: true 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: p7pafu3ft5d51 '/project/{project}/channel/sms/sms/audience/{audienceId}': get: summary: List SMS messages by audience contact description: | Lists SMS messages for a specific audience contact. Supports using a phone number as audienceID. In that case, the audience contact will be searched. **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Note**: Results are automatically restricted to the last 12 months in paid plans (1 month in free plan). Supports using a phone number as audienceID. In that case, the audience contact will be searched. tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: audienceId in: path description: Audience contact ID or phone number (will be normalized) required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: audienceId: type: string description: The audience contact ID additionalProperties: true 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: dyywbm1jyb7v5 '/project/{project}/channel/sms/sms/send/{send}': get: summary: List SMS messages by send description: | Lists SMS messages belonging to a specific Send entity. **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Note**: For automations or direct messages, results are automatically restricted to the last 3 months in paid plans (7 days in free plan). Draft SMS messages are excluded from results. tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: send in: path description: Send entity ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity additionalProperties: true additionalProperties: true 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: wdgdl8g4y8bgk '/project/{project}/channel/sms/sms/campaign/{campaign}': get: summary: List SMS messages by campaign description: | Lists SMS messages sent as part of a campaign. Supports filtering by campaign option (for A/B testing campaigns). This endpoint defaults to optionIdx=0 (first option). **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Important Notes**: - Draft SMS messages are excluded from results - Options are deprecated (legacy A/B testing feature) **URL Variants**: This endpoint also supports `/project/{project}/channel/sms/sms/campaign/{campaign}` (without optionIdx), which defaults to optionIdx=0. tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: campaign in: path description: Campaign ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity for the campaign option additionalProperties: true campaign: type: object description: The campaign entity additionalProperties: true additionalProperties: true 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: gg5ds1up2kzqt '/project/{project}/channel/sms/sms/campaign/{campaign}/{optionIdx}': get: summary: List SMS messages by campaign option description: | Lists SMS messages sent as part of a campaign for a specific campaign option (for A/B testing campaigns which are now deprecated). **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Important Notes**: - Draft SMS messages are excluded from results tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: campaign in: path description: Campaign ID required: true schema: type: string - name: optionIdx in: path description: Campaign option index (0-indexed). Defaults to 0 (first option) required: true schema: type: integer responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity for the campaign option additionalProperties: true campaign: type: object description: The campaign entity additionalProperties: true additionalProperties: true 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: 8vnzncxrocgb1 '/project/{project}/channel/sms/sms/automation/{automation}': get: summary: List SMS messages by automation description: | Lists SMS messages sent as part of an automation. Each message in an automation has its own Send entity. This endpoint defaults to messageIdx=0 (first message). **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Important Notes**: - Each message in an automation has its own Send entity - Each message has only 1 option (no optionIdx needed per message) - Results are automatically restricted to the last 3 months in paid plans. 7 days in free plan. - Draft SMS messages are excluded from results **URL Variants**: This endpoint also supports `/project/{project}/channel/sms/sms/automation/{automation}` (without messageIdx), which defaults to messageIdx=0. tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: automation in: path description: Automation ID required: true schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity for the automation message additionalProperties: true automation: type: object description: The automation entity additionalProperties: true additionalProperties: true 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: nu02qqvcjvvqo '/project/{project}/channel/sms/sms/automation/{automation}/{messageIdx}': get: summary: List SMS messages by automation message description: | Lists SMS messages sent as part of an automation for a specific message. Each message in an automation has its own Send entity. **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Important Notes**: - Each message in an automation has its own Send entity - Each message has only 1 option (no optionIdx needed per message) - Results are automatically restricted to the last 3 months in paid plans. 7 days in free plan. - Draft SMS messages are excluded from results tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: automation in: path description: Automation ID required: true schema: type: string - name: messageIdx in: path description: Automation message index (0-indexed). Defaults to 0 (first message) required: true schema: type: integer responses: '200': description: Success content: application/json: schema: type: object properties: entities: type: array items: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity for the automation message additionalProperties: true automation: type: object description: The automation entity additionalProperties: true messageIdx: type: integer description: The message index used additionalProperties: true 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: wzs9ow2f4y6p8 '/project/{project}/channel/sms/sms/direct': get: summary: List direct SMS messages description: | Lists SMS messages sent as direct messages (not part of campaigns or automations). **Required Scope**: `PROJECT_DIRECT_READ` **Query Parameters**: Supports Query String Filtering parameters. **Rate Limit**: [l] large - varies by subscription tier **Note**: Results are automatically restricted to the last 3 months in paid plans. 7 days in free plan. **Restrict to custom Tracking Term / Utm Term**: You can add an optional utm term to the path to only retrieve messages sent with the tracking term provided. Use the endpoint `/project/{project}/channel/sms/sms/direct/{utmTerm}` tags: - sms 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/ResponseSmsItem' metadata: type: object properties: send: type: object description: The Send entity for direct messages additionalProperties: true additionalProperties: true 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: cjlj58sgxaio4 '/project/{project}/channel/sms/sms/direct/{senderId}/{audienceId}': post: summary: Send SMS message (Direct message) description: | Creates and sends a direct SMS message immediatelly to an audience contact. The audience contact will be automatically created from the phone number if it doesn't exist and auto-creation is enabled for the project. **Required Scope**: `PROJECT_DIRECT_WRITE` **Rate Limit**: [m] moderate - varies by subscription tier **Sender ID**: The sender ID or `"default"` to use the project's default sender. If empty string is provided, it will be treated as `"default"`. The default sender ID is cached for 1 minute to reduce database queries. **Audience Contact Resolution**: - If `audienceId` is an audience contact ID format, it will be retrieved directly by ID - If `audienceId` is a phone number: - The phone number will be normalized and validated as a mobile phone number - If valid, the system will search for an existing contact with that phone number - If not found and auto-creation is enabled, a new contact will be created with the normalized phone number and tags: `auto-created`, `auto-created-outbound` - If the phone number is not a valid mobile number, the request will fail with a descriptive error **Auto-creation**: Requires the project to have `auto creation` enabled for outbound messages. It will fail if it's not enabled and the phone does not exist. **Tracking Term / Utm Term** (Optional): You can set an additional tracking term (up to 40 chars). It will be added into all events related with this message: Delivery, Clicks, Unsubscribes, Sales... That way, you could easily differentiate the events origin / source. Imagine you send repurchase reminders, you can provide `repurchase` as utm-term to tag all events. Use the endpoint `/project/{project}/channel/sms/sms/direct/{senderId}/{audienceId}/{utmTerm}` to set a custom tracking term. **Error Handling**: - `404 Not Found`: Audience contact not found and auto-creation is disabled or phone number is invalid - `400 Bad Request`: Validation errors (missing phone number, invalid sender, etc.) - `402 Payment Required`: Organization has insufficient funds - `403 Forbidden`: Project does not allow direct messages or organization service is disabled **Note**: This endpoint is rate-limited to prevent abuse. It's intended for individual message sending, not bulk campaigns. **Request Body Fields**: - `text`: (required) The SMS message text. Supports template variables like `{{short:url}}` for link shortening and `{{unsubscribe}}` for unsubscribe links - `allowUnicode`: (optional) Whether to allow Unicode characters (e.g., emojis). Defaults to false **Response Details**: - `entity`: The SMS message entity. Important properties include: - `id`: SMS message ID - `status`: Message status (e.g., `enqueued`, `sent`, `delivered`) - `from`: Sender ID or phone number - `to`: Recipient phone number - `normalizedTo`: Normalized recipient phone number - `text`: Original message text (with template variables) - `deliveredText`: Final delivered text (with template variables resolved) - `charsCount`: Character count of the message - `messagesCount`: Number of SMS parts (1 for single SMS, 2+ for concatenated) - `encoding`: Message encoding (e.g., `GSM_7BIT`, `UCS2`) - `unicode`: Whether the message contains Unicode characters - `charged`: Whether the message was charged - `pricePerSms`: Price per SMS part - `priceUser`: Total price charged to user - `sentAt`: When the message was sent (null if not yet sent) - `deliveredAt`: When the message was delivered (null if not yet delivered) - `audienceContact`: Audience contact information - `metadata`: Additional metadata about the message (organization, token, send entity) - `metadata`: Contains: - `audienceId`: The audience contact ID associated with the SMS - `autoCreated`: Boolean indicating if the audience contact was auto-created during this request tags: - sms parameters: - name: project in: path description: 'Project UID (e.g., ''my-project-123'')' required: true schema: type: string - name: senderId in: path description: Sender ID or 'default' to use the project's default sender. Empty string is treated as 'default' required: true schema: type: string - name: audienceId in: path description: Audience contact ID or phone number (will be normalized and searched) required: true schema: type: string requestBody: $ref: '#/components/requestBodies/DirectSmsRequest' responses: '201': description: Success content: application/json: schema: type: object properties: entity: $ref: '#/components/schemas/ResponseSmsItem' metadata: type: object properties: audienceId: type: string description: The audience contact ID associated with the SMS autoCreated: type: boolean description: Boolean indicating if the audience contact was auto-created during this request required: - audienceId - autoCreated required: - entity - metadata examples: standard: summary: Standard SMS response value: entity: id: '6954234341ef67caa32a14c2' inbound: false clientId: null status: 'enqueued' statusCode: null from: 'info' country: 'ES' to: '+34670215553' normalizedTo: '+34670215553' charsCount: 77 text: 'This is a test message: {{short:http://google.com}} {{unsubscribe}}' deliveredText: 'This is a test message: 0003 https://inst.dev/6xQ6nMq STOP nosms.dev/2qrgdG2' messagesCount: 1 encoding: 'GSM_7BIT' unicode: false allowUnicode: false charged: true pricePerSms: 0.04 priceUser: 0.04 scheduledAt: null sentAt: null deliveredAt: null audienceContact: id: 'uQTuHNBKLdwTxzGldW5pocUNqzyz-066' project: '67bdfa983114d0062d73262f' relatedSms: null metadata: organizationName: 'Instasent Frontend' organizationId: '60141bb26dccbf21a04a01d2' tokenName: 'frontend product token Token Token Token' tokenType: 'product' tokenId: '67bdfa983114d0062d734497' sendName: 'Direct SMS' sendId: '67bdfa9e3114d0062d7344b3' metadata: audienceId: 'uQTuHNBKLdwTxzGldW5pocUNqzyz-066' autoCreated: false '400': $ref: '#/components/responses/WrongRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/NoFundsError' '403': description: Project does not allow direct messages or organization service is disabled content: application/json: schema: $ref: '#/components/schemas/ResponseErrorDetail' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' x-stoplight: id: 71qsh4btgyhwx '/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 components: securitySchemes: BearerAuth: description: Token with permissions to access the endpoint type: http scheme: bearer requestBodies: AudienceSearchRequest: description: Request body for searching audience contacts required: true content: application/json: schema: $ref: '#/components/schemas/AudienceSearchRequestBody' AudienceScrollRequest: description: Request body for scrolling audience contacts required: true content: application/json: schema: $ref: '#/components/schemas/AudienceScrollRequestBody' AudienceAggregationsRequest: description: Request body for aggregating audience contacts required: true content: application/json: schema: $ref: '#/components/schemas/AudienceAggregationsRequestBody' EventSearchRequest: description: Request body for searching audience events required: true content: application/json: schema: $ref: '#/components/schemas/EventSearchRequestBody' EventScrollRequest: description: Request body for scrolling audience events required: true content: application/json: schema: $ref: '#/components/schemas/EventScrollRequestBody' EventAggregationsRequest: description: Request body for aggregating audience events required: true content: application/json: schema: $ref: '#/components/schemas/EventAggregationsRequestBody' StreamPushRequest: description: Request body for pushing data to stream (contacts or events) required: true content: application/json: schema: type: array items: type: object description: Contact or event data additionalProperties: true AudienceStreamActionRequest: description: Request body for direct Instasent stream actions required: true content: application/json: schema: $ref: '#/components/schemas/AudienceStreamActionRequestBody' DirectSmsRequest: description: Request body for creating direct SMS message required: true content: application/json: schema: $ref: '#/components/schemas/DirectSmsRequestBody' 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: ChannelConfig: type: object description: Per-channel configuration. Values cascade from channel → channelDefaults → hardcoded constants. properties: defaultCompliancePolicy: type: string nullable: true enum: [opt-in, opt-out, basic, none] description: Default compliance policy for this channel optInKeywords: type: array nullable: true items: type: string description: Keywords that trigger opt-in optOutKeywords: type: array nullable: true items: type: string description: Keywords that trigger opt-out autoMarketingOptInOnInbound: type: boolean nullable: true description: Whether to auto-set accepts_marketing=true on inbound messages autoCreateContactsOnInbounds: type: boolean nullable: true description: Whether to automatically create contacts on inbound messages autoCreateContactsOnOutbounds: type: boolean nullable: true description: Whether to automatically create contacts on outbound messages marketingOptOutScope: type: string nullable: true enum: [per_channel, global] description: Scope of marketing opt-out (per_channel or global across all channels) marketingOptInScope: type: string nullable: true enum: [per_channel, global] description: Scope of marketing opt-in (per_channel or global across all channels) ResponseMetadata: type: object properties: count: type: integer start: type: integer limit: type: integer x-stoplight: id: 2uyqyhidqntar AttributeSpec: type: object description: Project attribute specification properties: uid: type: string description: The attribute identifier (e.g., '_full_name', '_user_id') example: '_full_name' adhocUid: type: string nullable: true description: Ad-hoc attribute identifier (if applicable) displayLabel: type: string description: Human-readable label for the attribute example: 'Full name' description: type: string description: Localized description of the attribute example: 'User full name. Will be automatically generated from first name + last name if not mapped.' dataType: type: string description: The data type (e.g., 'string', 'number', 'boolean', 'date') example: 'string' visualType: type: string description: The visual representation type example: 'string' enabled: type: boolean description: Whether the attribute is enabled for use readonly: type: boolean description: Whether the attribute is read-only visible: type: boolean description: Whether the attribute is visible in the UI unique: type: boolean description: Whether the attribute is unique (used for merging contacts) custom: type: boolean description: Whether the attribute is custom (user-created) internal: type: boolean description: Whether the attribute is internal-only multivalue: type: integer description: Maximum number of values allowed (1 = single value) example: 1 mappeable: type: boolean description: Whether the attribute can be mapped from datasources eventBased: type: boolean description: Whether the attribute is derived from events important: type: boolean description: Whether the attribute is marked as important createdByDatasourceType: type: string nullable: true description: Type of datasource that created this attribute (if applicable) createdByDatasourceUid: type: string nullable: true description: UID of datasource that created this attribute (if applicable) createdAt: type: string format: date-time description: When the attribute was created example: '2025-02-25T18:13:48+01:00' updatedAt: type: string format: date-time description: When the attribute was last updated example: '2025-02-25T18:13:48+01:00' required: - uid - displayLabel - dataType - visualType - enabled - readonly - visible - unique - custom - internal - multivalue - mappeable - eventBased x-stoplight: id: attribute-spec EventSpec: type: object description: Event type specification properties: uid: type: string description: The event type identifier (e.g., 'appointment', 'ecommerce_order_create') example: 'appointment' name: type: string description: Human-readable name for the event type example: 'Appointment' description: type: string description: Description of what the event represents example: 'Event for appointments and reservations' category: type: string description: Event category (e.g., 'contact_behaviour', 'ecommerce') example: 'contact_behaviour' attribution: type: boolean description: Whether the event supports attribution tracking automation: type: boolean description: Whether the event can trigger automations important: type: boolean description: Whether the event is marked as important icon: type: string description: Icon identifier for the event type example: 'appointment' emoji: type: string description: Emoji representation of the event type example: '🏁' required: - uid - name - category - attribution - automation - important x-stoplight: id: event-spec EventParameterSpec: type: object description: Event parameter specification properties: parameter: type: string description: The parameter identifier (e.g., 'order-id', 'order-currency') example: 'order-id' title: type: string description: Human-readable title for the parameter example: 'Order Id' description: type: string description: Description of the parameter and its purpose example: 'Currency used for all amounts on the order. ISO4217 3 Uppercase letters (i.e. EUR, USD)' dataType: type: string description: The data type (e.g., 'keyword', 'number', 'date') example: 'keyword' visualType: type: string description: The visual representation type example: 'keyword' required: type: boolean description: Whether the parameter is required multiValue: type: integer description: Maximum number of values allowed (1 = single value) example: 1 maxLength: type: integer nullable: true description: Maximum length for string parameters (if applicable) example: 128 icon: type: string description: Icon identifier for the parameter type example: 'keyword' required: - parameter - title - dataType - visualType - required - multiValue x-stoplight: id: event-parameter-spec AudienceSearchRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Audience QueryFilter documentation for details additionalProperties: true limit: type: integer description: Number of contacts per page. Max 50. Default 50 minimum: 1 maximum: 50 offset: type: integer description: Ignored - always enforced to 0 for this endpoint additionalProperties: false x-stoplight: id: bmnxaw1w40obi AudienceScrollRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Audience QueryFilter documentation for details additionalProperties: true limit: type: integer description: Number of contacts per page. Max 100. Default 100 minimum: 1 maximum: 100 cursor: type: string nullable: true description: 'For pagination, pass the cursor returned in the previous response''s metadata' additionalProperties: false x-stoplight: id: kv81l0npr7nod AudienceAggregationsRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Audience QueryFilter documentation for details additionalProperties: true aggregations: type: object description: Object defining the aggregations to perform. Each key is an aggregation name, and the value defines the aggregation type and parameters additionalProperties: true example: countries: type: terms params: field: '@_country_code' size: 5 order: _count: desc required: - aggregations additionalProperties: false x-stoplight: id: audience-aggregations-request-body EventSearchRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Event QueryFilter documentation for details additionalProperties: true limit: type: integer description: Number of events per page. Max 50. Default 50 minimum: 1 maximum: 50 offset: type: integer description: Ignored - always enforced to 0 for this endpoint additionalProperties: false x-stoplight: id: 7yei3dlb1z6i8 EventScrollRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Event QueryFilter documentation for details additionalProperties: true limit: type: integer description: Number of events per page. Max 100. Default 100 minimum: 1 maximum: 100 cursor: type: string nullable: true description: 'For pagination, pass the cursor returned in the previous response''s metadata' additionalProperties: false x-stoplight: id: 3ap1cwbippxwe EventAggregationsRequestBody: type: object properties: root: type: object description: The QueryFilter root node with conditions. See Event QueryFilter documentation for details additionalProperties: true aggregations: type: object description: Object defining the aggregations to perform. Each key is an aggregation name, and the value defines the aggregation type and parameters additionalProperties: true example: eventsByDay: type: date_histogram params: field: '@created-at' calendar_interval: 1d format: yyyy-MM-dd time_zone: UTC required: - aggregations additionalProperties: false x-stoplight: id: event-aggregations-request-body AudienceStreamActionRequestBody: type: object properties: audienceId: type: string description: The audience contact ID (required for all actions) reason: type: string description: 'Reason for unsubscription (optional, for unsubscribe actions)' utm-source: type: string description: 'UTM source parameter for tracking (optional, for unsubscribe actions)' utm-medium: type: string description: 'UTM medium parameter for tracking (optional, for unsubscribe actions)' utm-campaign: type: string description: 'UTM campaign parameter for tracking (optional, for unsubscribe actions)' required: - audienceId additionalProperties: true x-stoplight: id: gt6sn00x78j6i DirectSmsRequestBody: type: object properties: text: type: string description: | The SMS message text (required). Supports template variables: - `{{short:url}}`: Shortens the URL and replaces it with a short link - `{{unsubscribe}}`: Adds an unsubscribe link example: 'This is a test message {{short:http://google.com}} {{unsubscribe}}' allowUnicode: type: boolean description: Whether to allow Unicode characters (e.g., emojis). Defaults to false default: false required: - text additionalProperties: true x-stoplight: id: 7qstfdgjrbhmg 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 ResponseDatasourceItem: type: object properties: id: type: string uid: type: string name: type: string description: type: string nullable: true token: type: object properties: id: type: string token: type: string title: type: string createdAt: type: string type: type: string integration: type: string nullable: true deleted: type: boolean priority: type: string locale: type: string timezone: type: string defaultCountry: type: string nullable: true createdAt: type: string updatedAt: type: string uniqueDsfield: type: string nullable: true description: The unique identifier field for this datasource (e.g., `_user_id`). sequenceDate: type: string format: date-time nullable: true description: When the current data sequence started (used for CSV batch imports). audienceTags: type: array items: type: string nullable: true projectAttributeMappings: type: array description: List of field mappings that define how datasource fields map to project attributes. items: $ref: '#/components/schemas/ProjectAttributeMapping' nullable: true required: - id - uid - name - type - integration - locale - timezone - defaultCountry - createdAt - audienceTags x-stoplight: id: 6u3xd6qilofef 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 nullable: true 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 ResponseAudienceItem: type: object properties: id: type: string createdAt: type: string updatedAt: type: string indexedAt: type: string deletedAt: type: string nullable: true attributesData: type: object properties: _user_id: type: string _first_name: type: string nullable: true _last_name: type: string nullable: true _full_name: type: string nullable: true _phone_mobile: type: string nullable: true _phone_other: type: string nullable: true _email: type: string nullable: true _date_imported: type: string _date_updated: type: string _date_registered: type: string _client_tags: oneOf: - type: string - type: array items: type: string _country_code: type: string nullable: true _gender: type: string nullable: true _ip: type: string nullable: true _username: type: string nullable: true _language_code: type: string nullable: true _state: type: string nullable: true _region: type: string nullable: true _city: type: string nullable: true _zipcode: type: string nullable: true _address: type: string nullable: true _user_vat: type: string nullable: true _user_ssn: type: string nullable: true _company: type: string nullable: true _branch: type: string nullable: true _company_vat: type: string nullable: true _url: type: string nullable: true _currency_code: type: string nullable: true _is_subscribed_email: type: boolean _accepts_marketing_email: type: boolean _is_subscribed_sms: type: boolean _accepts_marketing_sms: type: boolean _date_birthday: type: string nullable: true _geopoint: type: string nullable: true _row: type: string nullable: true _audience_ids: type: array items: type: string _datasources: type: array items: type: string _ds_contact_ids: type: array items: type: string required: - id - createdAt - updatedAt - indexedAt - deletedAt - attributesData x-stoplight: id: a500g0vorgcqx ResponseProjectItem: type: object description: Project entity properties: id: type: string description: Project internal ID example: '67bdfa983114d0062d732655' uid: type: string description: Project UID (used in API paths) example: 'my-empty-project' name: type: string description: Project name example: 'My empty project' description: type: string nullable: true description: Project description projectType: type: string description: Type of project (e.g., 'standard') example: 'standard' projectStatus: type: string description: Project status (e.g., 'active') example: 'active' locale: type: string description: Project locale (e.g., 'es_ES') example: 'es_ES' timezone: type: string description: Project timezone (e.g., 'Europe/Madrid') example: 'Europe/Madrid' defaultSmsSender: type: string nullable: true description: ID of the default SMS sender example: '68ad7ad14b8e760c1541f542' generalConfig: type: object description: General project configuration with per-channel settings and cascade defaults additionalProperties: true properties: channelDefaults: $ref: '#/components/schemas/ChannelConfig' description: Default channel configuration (cascade terminal for all channels) channelSms: $ref: '#/components/schemas/ChannelConfig' nullable: true description: SMS-specific channel configuration (overrides channelDefaults) channelEmail: $ref: '#/components/schemas/ChannelConfig' nullable: true description: Email-specific channel configuration (overrides channelDefaults) attributionConfig: type: object nullable: true description: Attribution tracking configuration (time windows for attribution) additionalProperties: true properties: hoursSmsCampaignSent: type: integer description: Hours window for SMS campaign attribution hoursOtherCampaignSent: type: integer description: Hours window for other campaign attribution hoursCampaignCta: type: integer description: Hours window for campaign CTA attribution hoursCampaignOpen: type: integer description: Hours window for campaign open attribution hoursFindOutboundSms: type: integer description: Hours window for outbound SMS attribution createdAt: type: string format: date-time description: When the project was created example: '2025-02-25T18:13:46+01:00' updatedAt: type: string format: date-time description: When the project was last updated example: '2025-09-09T17:27:23+02:00' required: - id - uid - name - projectType - projectStatus - locale - timezone - createdAt - updatedAt additionalProperties: true x-stoplight: id: m5p46cm804ius ResponseSegmentItem: type: object description: Segment entity additionalProperties: true x-stoplight: id: 1td95mbeye75x ResponseCampaignItem: type: object description: Campaign entity additionalProperties: true x-stoplight: id: gmopxu1q0oq40 ResponseAutomationItem: type: object description: Automation entity additionalProperties: true x-stoplight: id: pzzjyg73nrsz3 ResponseSenderItem: type: object description: Sender entity additionalProperties: true x-stoplight: id: 3ftgxdbzs3r9j ResponseSmsItem: type: object description: SMS message entity properties: id: type: string description: SMS message ID example: '6954234341ef67caa32a14c2' status: type: string description: Message status (e.g., 'enqueued', 'sent', 'delivered', 'failed') example: 'enqueued' statusCode: type: string nullable: true description: Status code from the SMS provider (if available) from: type: string description: Sender ID or phone number example: 'info' to: type: string description: Recipient phone number example: '+34670215553' normalizedTo: type: string description: Normalized recipient phone number example: '+34670215553' text: type: string description: Original message text (with template variables like {{short:url}} and {{unsubscribe}}) example: 'This is a test message: {{short:http://google.com}} {{unsubscribe}}' deliveredText: type: string nullable: true description: Final delivered text (with template variables resolved) example: 'This is a test message: 0003 https://inst.dev/6xQ6nMq STOP nosms.dev/2qrgdG2' charsCount: type: integer description: Character count of the message example: 77 messagesCount: type: integer description: Number of SMS parts (1 for single SMS, 2+ for concatenated messages) example: 1 encoding: type: string description: Message encoding (e.g., 'GSM_7BIT', 'UCS2') example: 'GSM_7BIT' unicode: type: boolean description: Whether the message contains Unicode characters allowUnicode: type: boolean description: Whether Unicode characters were allowed for this message charged: type: boolean description: Whether the message was charged pricePerSms: type: number nullable: true description: Price per SMS part example: 0.04 priceUser: type: number nullable: true description: Total price charged to user example: 0.04 sentAt: type: string format: date-time nullable: true description: When the message was sent (null if not yet sent) deliveredAt: type: string format: date-time nullable: true description: When the message was delivered (null if not yet delivered) scheduledAt: type: string format: date-time nullable: true description: When the message is scheduled to be sent (null for immediate sending) inbound: type: boolean description: Whether this is an inbound message (false for outbound) country: type: string nullable: true description: Country code of the recipient example: 'ES' audienceContact: type: object nullable: true description: Audience contact information additionalProperties: true properties: id: type: string description: Audience contact ID project: type: string description: Project ID metadata: type: object nullable: true description: Additional metadata about the message (organization, token, send entity) additionalProperties: true required: - id - status - from - to - normalizedTo - text - charsCount - messagesCount - encoding - unicode - allowUnicode - charged - inbound additionalProperties: true x-stoplight: id: htlexm05z2jyf ResponseEventItem: type: object description: Event entity additionalProperties: true x-stoplight: id: 1v800st0ivodb 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 ResponseErrorValidation: type: object properties: errors: type: object properties: fields: type: object properties: to: type: array items: type: string required: - fields required: - errors x-stoplight: id: 9sf9ijkeqwxhk responses: WrongRequestError: description: You request body is malformed or something went wrong with 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' NoFundsError: description: You're out of money content: application/json: schema: $ref: '#/components/schemas/ResponseErrorDetail' 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' ValidationError: description: Some field of your request body is not valid content: application/json: schema: $ref: '#/components/schemas/ResponseErrorValidation' RateLimitError: description: You reached your endpoint rate limit content: application/json: schema: $ref: '#/components/schemas/ResponseErrorMessage' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ResponseErrorMessage'