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

# Block contacts or companies by ID

> Block contacts (`LEAD`) or companies (`COMPANY`) by their Enginy IDs. The server resolves each entity to its emails, LinkedIn URLs, and domains and creates blocklist entries for each. Use `blockTypes` to restrict which value kinds are extracted.

    > **Required scope:** `BLOCKLIST_WRITE`
    >
    > **Rate limit:** 30 requests per minute



## OpenAPI

````yaml https://openapi.enginy.ai/definitions.json post /v1/blocklist/add-entities
openapi: 3.1.0
info:
  title: Enginy API
  version: 1.0.0
  description: Public API for Enginy platform
servers:
  - url: https://openapi.enginy.ai
    description: Configured server
security: []
tags:
  - name: AI Variables
    description: >-
      Manage AI variables and discover the entity fields you can reference in
      prompts and entity requests.
  - name: Inbox
    description: >-
      Inbox endpoints for listing contact threads, reading thread messages,
      managing tags, and sending manual replies.
  - name: Workflows
    description: >-
      Build, validate, publish, run, and inspect advanced (graph) workflows,
      plus the block/condition catalog needed to author a workflow plan.
paths:
  /v1/blocklist/add-entities:
    post:
      tags:
        - Blocklist
      summary: Block contacts or companies by ID
      description: >-
        Block contacts (`LEAD`) or companies (`COMPANY`) by their Enginy IDs.
        The server resolves each entity to its emails, LinkedIn URLs, and
        domains and creates blocklist entries for each. Use `blockTypes` to
        restrict which value kinds are extracted.

            > **Required scope:** `BLOCKLIST_WRITE`
            >
            > **Rate limit:** 30 requests per minute
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entityType:
                  type: string
                  enum:
                    - COMPANY
                    - LEAD
                  description: >-
                    Whether the supplied IDs are contact (`LEAD`) IDs or company
                    (`COMPANY`) IDs.
                entityIds:
                  type: array
                  items:
                    type: integer
                    exclusiveMinimum: 0
                  minItems: 1
                  maxItems: 500
                  description: Entity IDs to resolve and block. Up to 500 per request.
                reason:
                  type: string
                  enum:
                    - NOT_INTERESTED
                    - COMPETITOR
                    - CUSTOMER
                    - NOT_TARGET
                    - OTHER
                    - CHURN
                  description: Reason classification applied to all created entries.
                blockTypes:
                  type: array
                  items:
                    type: string
                    enum:
                      - DOMAIN
                      - COMPANY_LINKEDIN_URL
                      - EMAIL
                      - LINKEDIN_URL
                  description: >-
                    Restrict which value kinds are extracted from the resolved
                    entities. For `COMPANY` entities, valid kinds are `DOMAIN`
                    and `COMPANY_LINKEDIN_URL`. For `LEAD` entities, valid kinds
                    are `EMAIL` and `LINKEDIN_URL`. Omit to block every
                    applicable value.
                fromLeads:
                  type: boolean
                  description: >-
                    Only used when `entityType` is `COMPANY`. If `true`, the
                    supplied IDs are interpreted as lead IDs and the leads'
                    parent companies are blocked instead. Defaults to `false`.
                periodDays:
                  type: integer
                  exclusiveMinimum: 0
                  description: >-
                    If provided, the entry expires `periodDays` days after
                    creation. Omit for a permanent entry.
              required:
                - entityType
                - entityIds
                - reason
            examples:
              contacts:
                summary: Block a batch of contacts (email + LinkedIn)
                value:
                  entityType: LEAD
                  entityIds:
                    - 101
                    - 102
                    - 103
                  reason: NOT_INTERESTED
              companiesDomainOnly:
                summary: Block companies by domain only
                value:
                  entityType: COMPANY
                  entityIds:
                    - 55
                    - 56
                  reason: COMPETITOR
                  blockTypes:
                    - DOMAIN
      responses:
        '200':
          description: Entities resolved and blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      added:
                        type: number
                        description: Number of blocklist rows created.
                      resolvedEntities:
                        type: number
                        description: Number of entities resolved from the supplied IDs.
                    required:
                      - added
                      - resolvedEntities
                required:
                  - status
                  - message
                  - data
        '400':
          description: Bad request - invalid blockTypes for entityType
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````