Instasent Contacts API

openapi: 3.2.0
info:
  title: Instasent - Ingest Contacts 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: Contacts
paths:
  /stream/contacts:
    post:
      summary: Create or update contacts
      description: Use this endpoint to load contacts into your data source. Up to 100 contacts can be sent per call (depending on your subscription plan). Any existing contact will be updated with the new information. Missing attributes will not be overwritten unless you explicitly send a null value for them.
      tags:
      - Contacts
      requestBody:
        $ref: '#/components/requestBodies/DatasourceStreamContactsCreateBody'
      responses:
        '202':
          description: Items accepted and queued. They are stored shortly after the response, usually within a few seconds. Rejected items are listed in `errors`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCreateDetail'
        '400':
          $ref: '#/components/responses/AllFailedError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/WrongRequestError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: postStreamContacts
      x-operation-id-source: derived
  /stream/contacts/{userId}:
    delete:
      summary: Delete single contact
      description: Use this endpoint to delete a contact from your data source. Contacts will be permanently destroyed and removed from your audience.
      tags:
      - Contacts
      parameters:
      - name: userId
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Contacts deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseCreateDetail'
        '400':
          $ref: '#/components/responses/AllFailedError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: deleteStreamContactsByUserId
      x-operation-id-source: derived
components:
  schemas:
    ContactData:
      type: object
      properties:
        _user_id:
          title: Unique user id
          description: Ensure to provide an unique user id for each contact. Contacts with the same user id will be merged automatically within your project, even if they belong to different datasources.
          type: string
          maximum: 40
        _first_name:
          title: First name
          type: string
          maximum: 40
        _last_name:
          title: Last name
          type: string
          maximum: 40
        _full_name:
          title: Full name
          description: Will be automatically generated from first name + last name if not sent.
          type: string
          maximum: 128
        _phone_mobile:
          title: Mobile phone
          description: Must include country code. It will be enforced to be a valid mobile phone and suitable for sending SMS campaings. If it's not a valid mobile phone, it will be automatically saved as _phone_other attribute.
          type: string
          maximum: 40
        _email:
          title: Email address
          type: string
          maximum: 128
        _client_tags:
          title: Tags
          description: Array of client provided tags to categorize the contact, each item must be a lowercase string without spaces.
          type: array
          items:
            type: string
        _date_registered:
          title: Registration date
          description: 'Date of customer registration within the datasource. Will default to import date if not set. Format ISO8601 i.e: 2022-11-14T14:21:07+02:00'
          type: string
          default: Current date
          example: '2022-11-14T14:21:07+02:00'
        _country_code:
          title: Country code
          description: 2 Letter ISO 3166-1 code, i.e. ES. In case you send a full country name it will be converted automatically.
          type: string
          maximum: 2
          example: US
        _gender:
          title: User gender
          description: Free format
          type: string
          maximum: 40
        _phone_other:
          title: Other phone
          description: 'Other phone: fixed line / landline, extension, phone without proper format...'
          type: string
          maximum: 40
        _ip:
          title: IP address
          description: IPv4 or IPv6 address
          type: string
          maximum: 40
        _username:
          title: Username
          description: If you set up this attribute as unique, contacts will the same value will be merged automatically.
          type: string
          maximum: 40
        _language_code:
          title: Language
          description: 2 Letter ISO 639-1 code. In case you send a full language name it will be converted automatically.
          type: string
          maximum: 40
          example: en
        _state:
          title: State
          description: User state / Level-1 subdivision. Not validated.
          type: string
          maximum: 40
        _region:
          title: Region
          description: User region / province / Level-2 subdivision. Not validated.
          type: string
          maximum: 40
        _city:
          title: City
          description: User city. Not validated.
          type: string
          maximum: 40
        _zipcode:
          title: Zipcode
          description: Postal / Zip code. Not validated.
          type: string
          maximum: 40
        _address:
          title: Address
          description: Postal address
          type: string
          maximum: 128
        _user_vat:
          title: User VAT
          description: User VAT number for invoices. No validations are made.
          type: string
          maximum: 40
        _user_ssn:
          title: ID/SSN
          description: Social security number or identification code. Country-dependant. Non validated.
          type: string
          maximum: 40
        _company:
          title: Company name
          description: User company name
          type: string
          maximum: 128
        _branch:
          title: Company branch
          description: Company branch, office, department, team...
          type: string
          maximum: 128
        _company_vat:
          title: Company VAT
          description: User company VAT / ID for invoicing.
          type: string
        _url:
          title: Website/Url
          description: Company or personal web page. Proper URL with schema (i.e. https://google.com)
          type: string
          maximum: 128
        _currency:
          title: Currency
          description: 'Currency code. 3 Letter ISO 4217 code (i.e: USD, EUR...)'
          example: USD
          type: string
          maximum: 3
        _date_accepts_marketing_email:
          title: Email mkt. accept date
          description: 'Date of Email marketing acceptance. Format ISO8601 i.e: 2022-11-14'
          example: '2022-11-14'
          type: string
        _accepts_marketing_email:
          title: Accepts mkt. emails?
          description: 'The contact''s marketing preference for email. `true` = accepted, `false` = declined, empty = no preference recorded (the default). Sends under the No opt-out and Opt-in policies respect it; Basic does not read it. Send `false` only when the contact actively declined: no data is no preference, never `false`. Instasent can also set it to `false` when the contact opts out from one of your messages.'
          type:
          - boolean
          - 'null'
        _is_subscribed_email:
          title: Subscribed to emails?
          description: 'Email suppression: a hard block managed by Instasent. `false` removes the contact from every email send, whatever the policy or the marketing preference. This API can write it deliberately: send `false` only for a hard block. To import ordinary opt-outs, use `_accepts_marketing_email` instead.'
          type: boolean
          default: true
        _date_accepts_marketing_sms:
          title: SMS mkt. accept date
          description: 'Date of SMS marketing acceptance. Format ISO8601 i.e: 2022-11-14'
          example: '2022-11-14'
          type: string
        _accepts_marketing_sms:
          title: Accepts mkt. SMS?
          description: 'The contact''s marketing preference for SMS, which RCS shares. `true` = accepted, `false` = declined, empty = no preference recorded (the default). Sends under the No opt-out and Opt-in policies respect it; Basic does not read it. Send `false` only when the contact actively declined: no data is no preference, never `false`. Instasent can also set it to `false` when the contact opts out from one of your messages.'
          type:
          - boolean
          - 'null'
        _is_subscribed_sms:
          title: Subscribed to SMS?
          description: 'SMS suppression, which RCS shares: a hard block managed by Instasent (repeated opt-outs, your team, the subscriptions API). `false` removes the contact from every SMS and RCS send, whatever the policy or the marketing preference. This API can write it deliberately: send `false` only for a hard block. To import ordinary opt-outs, use `_accepts_marketing_sms` instead.'
          type: boolean
          default: true
        _date_birthday:
          title: User birthday
          description: 'Format ISO8601 i.e: 2022-11-14'
          example: '2022-11-14'
          type: string
        _geolocation:
          title: Coordinates
          description: 'Geo coordinates string in GeoJSON Format: ''[lon, lat]'' brackets included. i.e ''[-3.70, 40.41]'''
          type: string
          example: '[-3.70, 40.41]'
        _row:
          title: Row number
          description: Row number / Position / Generic sequential integer number
          type: integer
        _is_deleted:
          title: Archived?
          description: Mark the contact as archived (soft delete, contacts can be unarchived)
          type: boolean
          default: false
    ResponseErrorDetail:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
      - title
      - status
      - detail
    ResponseRequestError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Why the request was rejected. When every item was rejected, the first item's message.
          example: '_user_id not found at item #0 (EV123): USER123 Contact with that id must be created prior sending any events'
        entitiesSuccess:
          type: integer
        entitiesFailures:
          type: integer
    ResponseErrorMessage:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
      required:
      - message
    ResponseCreateDetail:
      type: object
      properties:
        success:
          type: boolean
        status:
          type: integer
        errors:
          title: Rejected items
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
                description: Item index within the sent array
              error:
                type: string
                description: Error description
              item:
                type: object
                description: Item data you sent
        accepted:
          title: Accepted items
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
                description: Item index within the sent array
              item:
                type: object
                description: Accepted item data, queued to be stored
        streamId:
          type: string
        projectId:
          type: string
        projectUid:
          type: string
        datasourceId:
          type: string
        datasourceUid:
          type: string
        entitiesSuccess:
          type: integer
        entitiesFailures:
          type: integer
        stats:
          type: object
          properties:
            callsTotal:
              type: integer
            callsSuccess:
              type: integer
            callsFailures:
              type: integer
            entitiesSuccess:
              type: integer
            entitiesFailures:
              type: integer
  responses:
    InternalError:
      description: Internal server error
      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'
    AllFailedError:
      description: Every sent item was rejected, nothing has been queued. `error` carries the first item's message. When only some items are rejected the response is a `202` that lists them in `errors`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseRequestError'
    RateLimitError:
      description: You reached your endpoint rate limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    WrongRequestError:
      description: The request as a whole cannot be processed (the body is empty or holds more than 100 items). Nothing has been queued; the reason is in `error`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseRequestError'
  requestBodies:
    DatasourceStreamContactsCreateBody:
      description: 'An array of contacts to create or update. Up to 100 contacts per request.


        ### Contact data

        You should provide as much contact data as possible. Remember you can use all the contact data to create custom segments, track your customers and get detailed analytics about their behaviour.


        Please be noticed that these are all default contact attributes, which should fit almost any project type. You can add custom attributes to send additional information that suits your particular business logic.

        '
      required: true
      content:
        application/json:
          schema:
            type: array
            minItems: 1
            maxItems: 100
            items:
              $ref: '#/components/schemas/ContactData'
  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