> ## 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 an activity

> Creates the activity with this `source` and `external_id`, or updates it. Returns it with `result`: created (201), updated or unchanged. 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 put /v1/activities
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:
    put:
      tags:
        - activities
      summary: Push an activity
      description: >-
        Creates the activity with this `source` and `external_id`, or updates
        it. Returns it with `result`: created (201), updated or unchanged.
        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_upsert
      requestBody:
        content:
          application/json:
            schema:
              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
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedActivity'
          description: Successful Response
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedActivity'
          description: Created
      security:
        - HTTPBearer: []
components:
  schemas:
    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
    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
  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.