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

# Bulk Update Contacts

> Apply a whitelisted update to up to 500 organization-owned contacts.



## OpenAPI

````yaml /api-reference/openapi.json post /contacts/bulk-update
openapi: 3.1.0
info:
  title: Truedy API
  description: >-
    Truedy Public API. Authenticate with **Authorization: Bearer
    <your-api-key>** only. Get your API key from the [Truedy
    Dashboard](https://app.truedy.ai). Base URL:
    https://api.truedy.ai/api/public/v1
  version: 1.0.0
servers:
  - url: https://api.truedy.ai/api/public/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create, configure, test, retrieve, and delete voice agents.
  - name: Calls
    description: >-
      Create and manage outbound calls, recordings, transcripts, and call
      metadata.
  - name: Tools
    description: Create and manage agent tools.
  - name: Knowledge Bases
    description: Legacy Ultravox-backed knowledge bases and sources.
  - name: Knowledge Spaces
    description: >-
      Truedy-native RAG knowledge spaces, sources, ingestion jobs, and
      retrieval.
  - name: Voices
    description: Browse, import, clone, synchronize, preview, and delete voices.
  - name: Telephony
    description: Search, purchase, import, assign, unassign, and release phone numbers.
  - name: Batch Calls
    description: Create and manage outbound batch calling campaigns and their contacts.
  - name: Contacts
    description: Manage contact folders, contacts, imports, and exports.
  - name: Calls
    description: Start browser-based Web Calls with an active agent.
  - name: Widgets
    description: Manage New Frontend widget configurations and embed sessions.
  - name: Agent Templates
    description: Read active agent templates available to the organization.
  - name: Call Explainability
    description: Retrieve redacted structured evidence for a call.
  - name: Webhooks
    description: Manage organization webhook endpoints and delivery history.
  - name: Analytics
    description: Read organization dashboard and conversation intelligence analytics.
  - name: Exports
    description: Export organization calls and campaigns as CSV.
  - name: Workspaces
    description: Create and manage workspaces with an account-scoped master API key.
paths:
  /contacts/bulk-update:
    post:
      tags:
        - Contacts
      summary: Bulk Update Contacts
      description: Apply a whitelisted update to up to 500 organization-owned contacts.
      operationId: bulk_update_contacts_api_public_v1_contacts_bulk_update_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicContactBulkAction'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactBulkActionResponse'
        '401':
          $ref: '#/components/responses/PublicUnauthorized'
        '403':
          $ref: '#/components/responses/PublicForbidden'
        '422':
          $ref: '#/components/responses/PublicValidationError'
        '429':
          $ref: '#/components/responses/PublicRateLimitExceeded'
        '500':
          $ref: '#/components/responses/PublicInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    PublicContactBulkAction:
      properties:
        contact_ids:
          items:
            type: string
          type: array
          title: Contact Ids
        updates:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Updates
      type: object
      required:
        - contact_ids
      title: PublicContactBulkAction
    PublicContactBulkActionResponse:
      properties:
        data:
          additionalProperties: true
          type: object
          title: Data
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      type: object
      required:
        - data
        - meta
      title: PublicContactBulkActionResponse
    ResponseMeta:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support and debugging
        ts:
          type: string
          format: date-time
          title: Ts
          description: Server timestamp when the response was generated
      type: object
      required:
        - request_id
        - ts
      title: ResponseMeta
      description: Metadata included in every API response.
    PublicApiErrorResponse:
      type: object
      required:
        - error
        - meta
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: >-
                Structured, endpoint-specific details. Never rely on
                undocumented provider fields.
              type:
                - object
                - array
                - 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Request correlation metadata.
      example:
        error:
          code: validation_error
          message: 'Missing required field: name'
          details:
            errors: []
        meta:
          request_id: req_01JEXAMPLE
          ts: '2026-08-21T00:00:00Z'
  responses:
    PublicUnauthorized:
      description: Missing, malformed, expired, inactive, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicForbidden:
      description: >-
        The API key is valid but the request is not permitted by its
        organization, IP allowlist, or scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicValidationError:
      description: The request is syntactically valid but fails endpoint validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicRateLimitExceeded:
      description: >-
        The API key or organization exceeded a configured request limit. Retry
        after the response headers/window indicate.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
          description: Seconds until retry is permitted, when available.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Configured request limit.
        X-RateLimit-Remaining:
          schema:
            type: integer
            minimum: 0
          description: Remaining requests in the current window.
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
          description: UTC time at which the current window resets.
    PublicInternalError:
      description: Unexpected server failure. Use meta.request_id when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Your API key. Send in the Authorization header as: Bearer <your-api-key>'

````