> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Push activities

> Up to 100 activities in one call, each as the single call does, with a result for each in request order: created, updated, unchanged, or failed with the error alone that touch would have had. One that fails leaves the rest written. Each counts against your rate limit. Pushes what another system (a marketing platform, a sequencer) did with a person, typed by its `channel` as Statisfy types its own: email is an email thread, linkedin a LinkedIn conversation, call and meeting a meeting, and webinar, form, web_visit, event and other a marketing event. Each shows its origin: `source` api on the activity, and `pushed.system` your system's name. It is identified by your `source` and `external_id`, so sending it again (a retry, a re-sync, an email later opened) updates it in place. A conversation is one activity with its `messages` (one email or LinkedIn message sent without `messages` is a thread of one): send it again with the whole thread or only the new messages, and they merge by each message's `external_id`; its date is its latest message, and GET /v1/activities/{activity_id}/content reads them back, oldest first. The person is matched by email, ignoring case, and created when Statisfy has none; an address on your own domains is a 422. The account is the one you name (`account`: an id, a CRM id or a domain, else a 404), else the person's, else their email's domain (on a CRM-connected workspace only a CRM account matches; a personal address such as gmail.com never does). With no account it stays on the person: send it again once the account exists to add it. It shows on the account's and the person's timelines, and agents read it; nothing summarizes it with AI, replies to it, or pushes it to your CRM, and it never counts as your team's own mail (an email awaiting a reply, a deal gone quiet). The person reaching out (an inbound touch, a message from them, or `outcome.replied_at`) counts as their engagement and moves the account's last activity date; a touch that only went out to them does neither.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/activities/batch/upsert
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/activities/batch/upsert:
    post:
      tags:
        - activities
      summary: Push activities
      description: >-
        Up to 100 activities in one call, each as the single call does, with a
        result for each in request order: created, updated, unchanged, or failed
        with the error alone that touch would have had. One that fails leaves
        the rest written. Each counts against your rate limit. Pushes what
        another system (a marketing platform, a sequencer) did with a person,
        typed by its `channel` as Statisfy types its own: email is an email
        thread, linkedin a LinkedIn conversation, call and meeting a meeting,
        and webinar, form, web_visit, event and other a marketing event. Each
        shows its origin: `source` api on the activity, and `pushed.system` your
        system's name. It is identified by your `source` and `external_id`, so
        sending it again (a retry, a re-sync, an email later opened) updates it
        in place. A conversation is one activity with its `messages` (one email
        or LinkedIn message sent without `messages` is a thread of one): send it
        again with the whole thread or only the new messages, and they merge by
        each message's `external_id`; its date is its latest message, and GET
        /v1/activities/{activity_id}/content reads them back, oldest first. The
        person is matched by email, ignoring case, and created when Statisfy has
        none; an address on your own domains is a 422. The account is the one
        you name (`account`: an id, a CRM id or a domain, else a 404), else the
        person's, else their email's domain (on a CRM-connected workspace only a
        CRM account matches; a personal address such as gmail.com never does).
        With no account it stays on the person: send it again once the account
        exists to add it. It shows on the account's and the person's timelines,
        and agents read it; nothing summarizes it with AI, replies to it, or
        pushes it to your CRM, and it never counts as your team's own mail (an
        email awaiting a reply, a deal gone quiet). The person reaching out (an
        inbound touch, a message from them, or `outcome.replied_at`) counts as
        their engagement and moves the account's last activity date; a touch
        that only went out to them does neither.
      operationId: activities_batch_upsert
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                items:
                  items:
                    $ref: '#/components/schemas/PushedActivityFields'
                  maxItems: 100
                  minItems: 1
                  title: Items
                  type: array
              required:
                - items
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpsertActivitiesResult'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    PushedActivityFields:
      additionalProperties: false
      properties:
        account:
          anyOf:
            - $ref: '#/components/schemas/TouchAccount'
            - type: 'null'
          default: null
          description: >-
            Its account; left out, the person's account, else their email's
            domain
        body_text:
          anyOf:
            - maxLength: 32768
              type: string
            - type: 'null'
          default: null
          description: >-
            What was written, in plain text. Left out with messages: a
            conversation's words are its messages
          title: Body Text
        channel:
          enum:
            - email
            - linkedin
            - call
            - meeting
            - webinar
            - form
            - web_visit
            - event
            - other
          title: Channel
          type: string
        direction:
          description: outbound (to the person) or inbound (from them)
          enum:
            - inbound
            - outbound
          title: Direction
          type: string
        external_id:
          description: Your id for this touch
          maxLength: 200
          minLength: 1
          title: External Id
          type: string
        messages:
          description: >-
            A conversation's messages (an email thread, a LinkedIn exchange):
            the whole thread or only its new messages, merged by each message's
            external_id. Left out for a single touch, and on any other channel
          items:
            $ref: '#/components/schemas/TouchMessage'
          maxItems: 500
          title: Messages
          type: array
        occurred_at:
          description: When it happened, ISO 8601 (UTC when no offset); not in the future
          format: date-time
          title: Occurred At
          type: string
        outcome:
          anyOf:
            - $ref: '#/components/schemas/TouchOutcome'
            - type: 'null'
          default: null
        person:
          $ref: '#/components/schemas/TouchPerson'
        sent_by:
          anyOf:
            - maxLength: 320
              type: string
            - type: 'null'
          default: null
          description: The email of the teammate who sent it, when one did
          title: Sent By
        source:
          description: >-
            Your system's name, as the app shows it (HubSpot). With external_id,
            it identifies the touch
          maxLength: 40
          minLength: 1
          title: Source
          type: string
        subject:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          default: null
          title: Subject
        url:
          anyOf:
            - maxLength: 2000
              type: string
            - type: 'null'
          default: null
          description: An https link to the touch in your system
          title: Url
      required:
        - source
        - external_id
        - channel
        - direction
        - occurred_at
        - person
      title: PushedActivityFields
      type: object
    BatchUpsertActivitiesResult:
      properties:
        items:
          description: In request order
          items:
            $ref: '#/components/schemas/BatchUpsertActivityItem'
          title: Items
          type: array
      required:
        - items
      title: BatchUpsertActivitiesResult
      type: object
    TouchAccount:
      additionalProperties: false
      description: 'The account the touch belongs to: exactly one of the three.'
      properties:
        crm_account_id:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          default: null
          description: The account's id in your CRM
          title: Crm Account Id
        domain:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          default: null
          description: The account's domain, such as acme.com
          title: Domain
        id:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          default: null
          description: A Statisfy account id
          title: Id
      title: TouchAccount
      type: object
    TouchMessage:
      additionalProperties: false
      properties:
        body_text:
          description: What it said, in plain text
          maxLength: 32768
          minLength: 1
          title: Body Text
          type: string
        direction:
          description: outbound (to the person) or inbound (from them)
          enum:
            - inbound
            - outbound
          title: Direction
          type: string
        external_id:
          description: >-
            Your id for this message; sending it again updates it rather than
            adding a copy
          maxLength: 200
          minLength: 1
          title: External Id
          type: string
        sent_at:
          description: ISO 8601 (UTC when no offset); not in the future
          format: date-time
          title: Sent At
          type: string
        sent_by:
          anyOf:
            - maxLength: 320
              type: string
            - type: 'null'
          default: null
          description: An outbound message's teammate, when not the touch's `sent_by`
          title: Sent By
        subject:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          default: null
          title: Subject
      required:
        - external_id
        - direction
        - sent_at
        - body_text
      title: TouchMessage
      type: object
    TouchOutcome:
      additionalProperties: false
      properties:
        attended:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: 'A meeting''s, webinar''s or event''s: whether they came'
          title: Attended
        clicked_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          default: null
          title: Clicked At
        duration_seconds:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          default: null
          description: A call's or meeting's length
          title: Duration Seconds
        opened_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          default: null
          title: Opened At
        replied_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          default: null
          title: Replied At
      title: TouchOutcome
      type: object
    TouchPerson:
      additionalProperties: false
      properties:
        email:
          description: Who the touch was with; matched to a person ignoring case
          maxLength: 320
          title: Email
          type: string
        first_name:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          default: null
          description: Used only when the person is created
          title: First Name
        last_name:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          default: null
          description: Used only when the person is created
          title: Last Name
        linkedin_url:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          default: null
          description: Their LinkedIn profile, kept on the touch (not used to match)
          title: Linkedin Url
        title:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          default: null
          description: Used only when the person is created
          title: Title
      required:
        - email
      title: TouchPerson
      type: object
    BatchUpsertActivityItem:
      properties:
        activity:
          anyOf:
            - $ref: '#/components/schemas/UpsertedActivity'
            - type: 'null'
          description: Set unless the touch failed
        error:
          anyOf:
            - $ref: '#/components/schemas/ItemError'
            - type: 'null'
          description: Set exactly when `status` is `failed`
        external_id:
          title: External Id
          type: string
        source:
          title: Source
          type: string
        status:
          enum:
            - created
            - updated
            - unchanged
            - failed
          title: Status
          type: string
      required:
        - source
        - external_id
        - status
      title: BatchUpsertActivityItem
      type: object
    UpsertedActivity:
      properties:
        accounts:
          description: The accounts whose timeline shows it; empty when none matched yet
          items:
            type: string
          title: Accounts
          type: array
        id:
          description: The activity's id at GET /v1/activities/{activity_id}
          title: Id
          type: string
        person_id:
          description: 'The person it is with: found by email, or created'
          title: Person Id
          type: string
        result:
          description: >-
            created; updated (a field changed, such as an email later opened);
            or unchanged (the same touch again: nothing was written)
          enum:
            - created
            - updated
            - unchanged
          title: Result
          type: string
      required:
        - id
        - result
        - person_id
        - accounts
      title: UpsertedActivity
      type: object
    ItemError:
      description: The error envelope a single request would have returned.
      properties:
        code:
          title: Code
          type: string
        details:
          items:
            additionalProperties: true
            type: object
          title: Details
          type: array
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: ItemError
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.