Instasent Specifications API

openapi: 3.2.0
info:
  title: Instasent - Ingest Specifications API
  version: 1.0.3
  description: '!Ingest API Diagram


    ### Overview

    The Instasent Ingest API is a powerful tool to import **contacts** and **events** into your project. This API allows organizations to consolidate customer data and track interactions, enabling advanced audience segmentation and personalized marketing. #### What is the Ingest API? The Ingest API is a small subset of the Product API that enables you to **add or update contact data and record events** for each contact within your Instasent project. It functions as an independent Data Source within your project''s unified audience, having priority over other data sources when conflicts arise. This setup allows for seamless centralization of customer data, enhancing your understanding of customer behavior and engagement. - **Contacts**: Represent individuals in your audience, such as customers, leads, or other relevant profiles. - **Events**: Document interactions by these contacts, such as purchases, email opens, clicks, or other custom activities (e.g., "viewed product" or "made a reservation"). #### Why use the Ingest API? Using the Ingest API, businesses can:

    1. **Unify Customer Data**: Consolidate data from various sources into Instasent, creating a 360º view of each contact. Data from this API takes precedence over other sources in cases of overlapping information. 2. **Automate Data Updates**: Automatically sync new or updated data from external platforms (e.g., CRM, e-commerce). 3. **Enable Targeted Marketing**: Segment audiences based on attributes or recorded events to enable precise targeting in campaigns. 4. **Track Engagements**: Record customer interactions to measure engagement and improve marketing strategies. #### Key Functionalities

    1. **Create or Update Contacts**:

    - The `/stream/contacts` endpoint allows bulk uploading of contact data, handling up to 100 contacts per request. Existing contacts are updated unless fields are explicitly left blank or set to null. 2. **Delete Contacts**:

    - Use the `/stream/contacts/{userId}` endpoint to delete a contact, permanently removing their profile from your audience. 3. **Add Events**:

    - The `/stream/events` endpoint records contact interactions like purchases, views, or other actions. Note that events are immutable and cannot be updated once created. 4. **Get Stream Information**:

    - The `/stream` endpoint returns information about the stream, including organization, project, and datasource details along with usage statistics. 5. **Get Attributes and Events Specs**:

    - The `/stream/specs/attributes` and `/stream/specs/events` endpoints provide detailed information about the attributes and events supported by the Ingest API, including data types, validation rules, and other specifications. 6. **Get Event Parameters Specs**:

    - The `/stream/specs/event-parameters/{eventType}` endpoint provides detailed information about the parameters supported for a specific event type. #### Who Should Use This API? - **Marketers and CRM Managers**: Automate segmentation and targeting of contacts based on real-time data. - **Developers and Data Integrators**: Seamlessly connect Instasent with CRM, e-commerce, or other data systems for continuous updates and customer insights. #### Example Use Case

    Suppose a customer makes a purchase on your website. Your e-commerce system sends this purchase event to Instasent using the Ingest API. Instasent updates the contact''s profile and triggers any automations you have set up, such as a thank-you SMS. This event is stored in the contact''s timeline, helping your team understand the customer''s journey. #### Technical Notes

    - **API Token**: The Ingest API requires a unique token for secure access. Each data source has its own token. - **Rate Limits**: Requests are rate-limited according to your subscription plan. #### Useful Links

    1. **Instasent APIs Overview**: Check our diagram

    2. **Instasent API Docs**: Visit https://docs.instasent.com to discover all our available APIs

    3. **Ingest API Samples**: Check our repo'
  contact:
    email: dev@instasent.com
    url: https://instasent.com
    name: Instasent
servers:
- url: https://api.instasent.com/v1/project/{project}/datasource/{datasource}
  description: Instasent Webhooks - Ingest API
  variables:
    project:
      default: project
      description: Project identifier
    datasource:
      default: id
      description: Datasource identifier
security:
- BearerAuth: []
tags:
- name: specifications
paths:
  /stream:
    get:
      summary: Get stream information
      description: Returns information about the stream, including organization, project, and datasource details along with usage statistics. Use this one for auth validation.
      tags:
      - specifications
      responses:
        '200':
          description: Stream information and statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/OrganizationInfo'
                  stream:
                    $ref: '#/components/schemas/StreamInfo'
                  datasource:
                    $ref: '#/components/schemas/DatasourceInfo'
                  project:
                    $ref: '#/components/schemas/ProjectInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getStream
      x-operation-id-source: derived
  /stream/specs/attributes:
    get:
      summary: Get available contact attributes
      description: Returns the list of available attributes that contacts can have, including their data types and validation rules.
      tags:
      - specifications
      responses:
        '200':
          description: List of available attributes
          content:
            application/json:
              schema:
                type: object
                properties:
                  specs:
                    type: array
                    items:
                      $ref: '#/components/schemas/AttributeSpec'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getStreamSpecsAttributes
      x-operation-id-source: derived
  /stream/specs/events:
    get:
      summary: Get available event types
      description: Returns the list of available event types that can be tracked.
      tags:
      - specifications
      responses:
        '200':
          description: List of available event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  specs:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventTypeSpec'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getStreamSpecsEvents
      x-operation-id-source: derived
  /stream/specs/event-parameters/{eventType}:
    get:
      summary: Get parameters for event type
      description: Returns the list of available parameters for a specific event type.
      tags:
      - specifications
      parameters:
      - name: eventType
        in: path
        description: Event type identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of available parameters for the event type
          content:
            application/json:
              schema:
                type: object
                properties:
                  specs:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventParameterSpec'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getStreamSpecsEventParametersByEventType
      x-operation-id-source: derived
components:
  schemas:
    DatasourceInfo:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        uid:
          type: string
        type:
          type: string
        integration:
          type:
          - string
          - 'null'
        sequence:
          type: integer
        priority:
          type: integer
        locale:
          type: string
        timezone:
          type: string
        defaultCountry:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AttributeSpec:
      type: object
      properties:
        requiredInWebhook:
          type: boolean
        important:
          type: boolean
        uid:
          type: string
        adhocUid:
          type:
          - string
          - 'null'
        description:
          type: string
        dataType:
          type: string
        visualType:
          type: string
        readonly:
          type: boolean
        visible:
          type: boolean
        custom:
          type: boolean
        unique:
          type: boolean
        displayLabel:
          type: string
        multivalue:
          type: integer
        createdByDatasourceType:
          type:
          - string
          - 'null'
        createdByDatasourceUid:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ResponseErrorDetail:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
      - title
      - status
      - detail
    EventParameterSpec:
      type: object
      properties:
        parameter:
          type: string
        title:
          type: string
        description:
          type: string
        icon:
          type: string
        dataType:
          type: string
        visualType:
          type: string
        maxLength:
          type: integer
        required:
          type: boolean
        multiValue:
          type: integer
    ProjectInfo:
      type: object
      properties:
        locale:
          type: string
        timezone:
          type: string
        name:
          type: string
        id:
          type: string
        uid:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ResponseErrorMessage:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
      required:
      - message
    StreamInfo:
      type: object
      properties:
        exposed:
          type: boolean
        id:
          type: string
        type:
          type: string
        purpose:
          type:
          - string
          - 'null'
        callsTotal:
          type: integer
        callsSuccess:
          type: integer
        callsFailures:
          type: integer
        processedEntitiesSuccess:
          type: integer
        processedEntitiesFailures:
          type: integer
        lastSuccessTime:
          type:
          - string
          - 'null'
          format: date-time
        lastFailureTime:
          type:
          - string
          - 'null'
          format: date-time
        lastCallTime:
          type:
          - string
          - 'null'
          format: date-time
    EventTypeSpec:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
        attribution:
          type: boolean
        automation:
          type: boolean
        icon:
          type: string
        emoji:
          type: string
        important:
          type: boolean
    OrganizationInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        plan:
          type: string
        quality:
          type: integer
  responses:
    RateLimitError:
      description: You reached your endpoint rate limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    NotFound:
      description: Resource can't be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    UnauthorizedError:
      description: You are missing or using bad credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Ingest API token for the datasource. This token is specific for the datasource.
externalDocs:
  url: https://docs.instasent.com
  description: Access to external documentation