Block a handle

POST/v3/blocked_handles

Blocks a handle — an E.164 phone number, an email address (iMessage sender), an SMS short code (e.g. 262966), or an alphanumeric sender ID. Inbound messages from it are dropped and produce no webhooks, and direct sends to it are rejected with 403 (error code 2026); group sends that include unblocked members are not restricted. Blocking is idempotent — re-blocking an already blocked handle returns the existing entry.

Body ParametersJSONExpand Collapse

handle: string

The handle to block: an E.164 phone number, an email address, an SMS short code (3-8 digits), or an alphanumeric sender ID.

reason: optional string

Optional free-text note on why the handle was blocked

ReturnsExpand Collapse

blocked_handle: BlockedHandleEntry { blocked_at, handle, reason }

blocked_at: string

When the handle was blocked

formatdate-time

handle: string

The blocked handle, normalized (E.164 phone, lowercased email, short code, or sender ID)

reason: optional string

Optional note recorded when the handle was blocked

Block a handle

curl https://api.linqapp.com/api/partner/v3/blocked_handles \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -d '{
          "handle": "+12025551234",
          "reason": "spam"
        }'

{
  "blocked_handle": {
    "handle": "+12025551234",
    "reason": "spam",
    "blocked_at": "2026-07-30T16:42:00Z"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "blocked_handle": {
    "handle": "+12025551234",
    "reason": "spam",
    "blocked_at": "2026-07-30T16:42:00Z"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}