Skip to main content

Add Caller Relation

POST 
/v1/users/{userId}/relations

Adds a relationship rule for how calls from a specific phone number should be handled.

Relation Types​

  • Block: Automatically reject calls from this number (caller hears busy/unavailable)
  • Voicemail: Route calls directly to voicemail, bypassing screening
  • Allow: Transfer calls immediately without AI screening (trusted callers)

Behavior​

Relations take precedence over AI screening decisions. A number in the Allow list will never be screened, even if Hiya's reputation data indicates potential spam.

Use Cases​

  • Personal Blocklist: Block persistent telemarketers or unwanted callers
  • VIP Callers: Allow family, doctors, or important contacts through immediately
  • Voicemail Routing: Send specific callers (e.g., work after hours) directly to voicemail

Path Parameters​

    userId stringrequired

    UUID for the given user

Header Parameters​

    x-hiya-product-version string

    Product version. The standard "major.minor.patch" format is highly encouraged without any leading characters; "2.1.3" or "3.0.0" for example.

    x-hiya-account-user-id stringrequired

    The identifier of a logged-in user. Same identifier that is used for /users/{user_id}

Body

required

application/json

Responses​

OK

Response Body

application/json