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

# Queue outbound SMS text message(s) from your Agent

> Queue SMS Tasks for one target and message or up to 10,000 targets. The endpoint accepts Task goals, retry policies, organization defaults, external correlation IDs, metadata, and Contact List enrollment. Submissions over 1,000 targets require Idempotency-Key and return 202. Use meta.contact for structured Contact data such as name, email, address and customFields. In a batch, put lead-specific metadata on each target object. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete metadata field reference.



## OpenAPI

````yaml post /api/v2/agent/outboundSms
openapi: 3.0.0
info:
  version: 2.0.0
  title: Vida API
  description: Vida API Documentation
servers:
  - url: https://api.vida.dev
    description: Vida Production
    variables:
      baseUrl:
        default: api.vida.dev
        description: Production API Root
security: []
tags:
  - name: Agents
  - name: Apps
    description: Install Vida apps and use their enabled integration functions.
  - name: Integrations
    description: Configure Vader integrations.
  - name: Inbound Email
    description: Control which senders may create inbound email work for an Agent.
  - name: Features
    description: Inspect capabilities available within an account hierarchy.
  - name: Conversation Logs
    description: Query conversation activity and calculate account-level metrics.
  - name: Computer Agents
    description: Set up, configure, inspect, and manage Vida Computer Agents.
  - name: Computer Agent Sessions
    description: View and reset Computer Agent sessions.
  - name: Accounts
  - name: Agent Templates
    description: Create, manage, and apply reusable Agent configurations.
paths:
  /api/v2/agent/outboundSms:
    post:
      tags:
        - Agents
      summary: Queue outbound SMS text message(s) from your Agent
      description: >-
        Queue SMS Tasks for one target and message or up to 10,000 targets. The
        endpoint accepts Task goals, retry policies, organization defaults,
        external correlation IDs, metadata, and Contact List enrollment.
        Submissions over 1,000 targets require Idempotency-Key and return 202.
        Use meta.contact for structured Contact data such as name, email,
        address and customFields. In a batch, put lead-specific metadata on each
        target object. See [Contact
        fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields)
        for the complete metadata field reference.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: object
            properties:
              type:
                type: string
                example: string
              maxLength:
                type: number
                example: 200
          description: >-
            Required for submissions over 1,000 targets. Repeating the same key
            and payload safely resumes or returns that submission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              oneOf:
                - type: object
                  required:
                    - target
                    - content
                  properties:
                    target:
                      type: string
                      description: Phone in E.164 or VIDA username
                      example: '+1234567890'
                    content:
                      type: string
                      description: Message body
                      example: Hello from Acme. Your appointment is tomorrow at 10am.
                    context:
                      type: string
                      description: Optional context for the agent handling the conversation
                    taskContext:
                      type: string
                      description: Task-specific context for this message
                    accountId:
                      type: integer
                      description: Optional agent account id override for the message
                    agentId:
                      type: integer
                      description: Optional campaign id override
                    scheduledFor:
                      type: integer
                      description: Unix seconds to schedule delivery
                    goal:
                      type: object
                      nullable: true
                      description: >-
                        Task-specific goal with completionCriteria. Omit or pass
                        null to use the organization default.
                    retryPolicy:
                      type: object
                      nullable: true
                      description: >-
                        Task-specific cadence using delaysSeconds or
                        mixed-channel steps, retryOn, and optional
                        responseTimeoutSeconds. Omit or pass null to use the
                        organization default.
                    meta:
                      type: object
                      additionalProperties: true
                      properties:
                        contact:
                          $ref: '#/components/schemas/TaskContactFields'
                      description: >-
                        Optional Task metadata. meta.contact fills missing
                        structured Contact fields at creation; existing values
                        are preserved. For multiple targets, set contact data in
                        meta.contact on each target object. Per-item meta
                        replaces the entire top-level meta object; it is not
                        deep-merged.
                    externalTaskId:
                      type: string
                      description: >-
                        Reusable customer correlation/grouping ID; not an
                        idempotency key
                    contactListName:
                      type: string
                      description: Optional Contact List to enroll the contact into
                - type: object
                  required:
                    - targets
                  properties:
                    targets:
                      description: Array of destinations or objects with per-item options
                      oneOf:
                        - type: array
                          items:
                            type: string
                            example: '+1234567890'
                        - type: array
                          items:
                            type: object
                            required:
                              - target
                            properties:
                              target:
                                type: string
                                example: '+1234567890'
                              content:
                                type: string
                                description: Per-item message body
                              context:
                                type: string
                              taskContext:
                                type: string
                              accountId:
                                type: integer
                              agentId:
                                type: integer
                              scheduledFor:
                                type: integer
                              goal:
                                type: object
                                description: Goal for this Task
                              retryPolicy:
                                type: object
                                description: >-
                                  Per-target retry override; null uses the
                                  organization default
                              meta:
                                type: object
                                additionalProperties: true
                                properties:
                                  contact:
                                    $ref: '#/components/schemas/TaskContactFields'
                                description: >-
                                  Optional Task metadata. meta.contact fills
                                  missing structured Contact fields at creation;
                                  existing values are preserved. For multiple
                                  targets, set contact data in meta.contact on
                                  each target object. Per-item meta replaces the
                                  entire top-level meta object; it is not
                                  deep-merged.
                              contactListName:
                                type: string
                              externalTaskId:
                                type: string
                                description: Identifier applied to this task
                    content:
                      type: string
                      description: >-
                        Message applied to all when targets is an array of
                        strings
                    context:
                      type: string
                      description: Context applied to all items when not provided per item
                    taskContext:
                      type: string
                      description: >-
                        Task-specific context applied to all items when not
                        provided per item
                    accountId:
                      type: integer
                      description: >-
                        Agent account id applied to all items when not provided
                        per item
                    agentId:
                      type: integer
                      description: Agent id applied to all items
                    scheduledFor:
                      type: integer
                      description: Schedule applied to all items
                    goal:
                      type: object
                      description: >-
                        Goal applied to each Task unless that item provides its
                        own
                    retryPolicy:
                      type: object
                      description: >-
                        Task-specific retry override applied to all items;
                        omitted or null values use the organization default
                    scheduleSpacingSec:
                      type: integer
                      description: >-
                        If provided, stagger scheduledFor by this many seconds
                        per index
                      example: 15
                    meta:
                      type: object
                      additionalProperties: true
                      properties:
                        contact:
                          $ref: '#/components/schemas/TaskContactFields'
                      description: >-
                        Optional Task metadata. meta.contact fills missing
                        structured Contact fields at creation; existing values
                        are preserved. For multiple targets, set contact data in
                        meta.contact on each target object. Per-item meta
                        replaces the entire top-level meta object; it is not
                        deep-merged.
                    externalTaskId:
                      type: string
                      description: >-
                        Reusable correlation/grouping ID applied to all created
                        Tasks
                    contactListName:
                      type: string
                      description: Contact List to enroll every contact into
            examples:
              single:
                summary: Single target
                value:
                  target: '+15551234567'
                  content: Hi, quick reminder for tomorrow at 10am.
                  context: Reminder campaign
                  meta:
                    contact:
                      name: Example Person
                      address:
                        state: LA
                      customFields:
                        vendorLeadCode: lead-123
              batchStrings:
                summary: Multiple string targets with shared content
                value:
                  targets:
                    - '+15551230001'
                    - '+15551230002'
                    - '+15551230003'
                  content: Thanks for signing up. Reply YES to confirm.
                  context: Onboarding nudge
                  scheduleSpacingSec: 10
              batchObjects:
                summary: Multiple object targets with per-item overrides
                value:
                  targets:
                    - target: '+15551230001'
                      content: VIP reminder 9am
                      context: VIP
                      scheduledFor: 1730000000
                    - target: '+15551230002'
                      content: Standard reminder 10am
                  agentId: 1234
      responses:
        '200':
          description: Queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Outbound SMS initiated.
                  inserted:
                    type: integer
                    example: 3
                  batchId:
                    type: string
                    example: f52b1e01-5cbc-483c-9939-3bf7d37e1426
                  tasks:
                    type: array
                    items:
                      type: object
        '202':
          description: Large SMS Task submission accepted for asynchronous creation
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '409':
          description: Idempotency conflict or overlapping active retryable Task
        '500':
          description: Server Error
      security:
        - apiKeyAuth: []
components:
  schemas:
    TaskContactFields:
      type: object
      additionalProperties: false
      description: >-
        Optional Contact fields for call, text and email Task creation,
        including outboundCall, outboundSms and outboundEmail. Fills missing
        fields on the target Contact in the Task organization before scheduling.
        Nested objects fill missing leaves; existing nonblank values, false,
        zero and nonempty arrays are preserved. Strings are trimmed; null, blank
        strings and empty objects/arrays are ignored. New Contacts use the
        supplied name instead of a global-profile default. Existing target
        phone/email defaults remain canonical. Does not change the Task target,
        global user profile or outbound caller ID. Task updates do not apply
        Contact changes; use the Contact API to replace or clear existing
        values. Identity and ownership fields are not accepted. See [Contact
        fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields)
        for the full field reference.
      properties:
        name:
          type: string
          nullable: true
          example: Example Person
        title:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          example: lead@example.com
        phone:
          type: string
          nullable: true
          example: '+15551234567'
        cnam:
          type: string
          nullable: true
          description: >-
            Organization Contact display data only; does not change outbound
            caller ID.
        mobile:
          type: string
          nullable: true
        birthday:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        image:
          type: string
          nullable: true
        address:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            street:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            zip:
              type: string
              nullable: true
              example: '07101'
            country:
              type: string
              nullable: true
        company:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            name:
              type: string
              nullable: true
            industry:
              type: string
              nullable: true
            position:
              type: string
              nullable: true
            website:
              type: string
              nullable: true
            address:
              type: string
              nullable: true
        preferredContactMethod:
          type: string
          nullable: true
        marketingOptIn:
          type: boolean
          nullable: true
        contactSource:
          type: string
          nullable: true
        socialMedia:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            linkedin:
              type: string
              nullable: true
            twitter:
              type: string
              nullable: true
            facebook:
              type: string
              nullable: true
            instagram:
              type: string
              nullable: true
        leadSource:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        tags:
          type: array
          nullable: true
          items:
            type: string
        notes:
          type: string
          nullable: true
        agentContext:
          type: string
          nullable: true
        customFields:
          type: object
          nullable: true
          additionalProperties: true
          maxProperties: 20
          description: >-
            Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON
            bytes, including existing values after merge.
          example:
            vendorLeadCode: lead-123
            source: website
        lastTask:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            taskId:
              oneOf:
                - type: string
                - type: number
              nullable: true
            listId:
              oneOf:
                - type: string
                - type: number
              nullable: true
            timestamp:
              type: number
              nullable: true
            success:
              type: boolean
              nullable: true
        lists:
          type: array
          nullable: true
          items:
            type: object
            required:
              - label
            properties:
              label:
                type: string
              timestamp:
                type: number
        appointments:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: token
      description: Vida API Token

````