API Reference

Contacts

Get contact

Returns one contact in real time. A missing ordinary contact returns 404 contact_not_found. If the target conversation does not exist, this endpoint returns 422 contact_not_found with numeric_code 35000 and message Conversation not found.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts/info

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Prepare your parameters
account_id
Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account
contact_id
Provider-side contact identifier; pass it as an opaque string. whatsapp and whatsapp-protocol use LID (xxx@lid). whatsapp-protocol may return success even when contact profile fields are missing; rely on the fields actually returned.

WhatsApp Protocol: Contact details require an existing LID (xxx@lid). Reuse data.sender.id or data.conversation.id only if it already ends in @lid. Protocol has no contact-list lookup and this endpoint cannot derive an LID from a phone number. Without an LID, you cannot use this lookup. A successful response may omit profile fields.

Request parameters

Headers

X-Api-Key
stringrequired

Workspace API key. The workspace is resolved from this header.

Path parameters

account_id
stringrequired

Identifier used in the contacts route.

Query parameters

contact_id
stringrequired

Provider-side contact identifier; pass it as an opaque string. whatsapp and whatsapp-protocol use LID (xxx@lid). whatsapp-protocol may return success even when contact profile fields are missing; rely on the fields actually returned.

Request body

This endpoint does not require a JSON request body.

Understand the result

Use only the profile fields actually returned. Treat contact identifiers as opaque; a missing profile field is not proof that the contact does not exist.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "user_example",
    "conversation_id": "peer_example",
    "display_name": "Alice",
    "avatar_url": "",
    "provider_user_id": "user_example",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

Response body

id
string

Contact identifier.

conversation_id
string

Conversation identifier for this contact; use it to send messages or locate the chat.

display_name
string

Contact display name, or an empty string when missing.

avatar_url
string

Contact avatar URL, or an empty string when missing.

provider_user_id
string

Channel-side user identifier for the contact.

is_blocked
boolean

Whether the contact is blocked by the connected account.

extra
object

Provider-specific extra fields, such as phone.

phone
string

WhatsApp phone JID 中解析出的纯手机号。

first_name
string

当前账号通讯录中保存的联系人简称或名字部分。

full_name
string

当前账号通讯录中保存的完整联系人名称。

push_name
string

联系人自行在 WhatsApp 设置的个人名称。

business_name
string

WhatsApp Business 账号的商业或认证名称。

redacted_phone
string

Provider 仅返回部分号码时的遮蔽手机号。

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

404

Not Found

The requested provider resource could not be found.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

422

Unprocessable Entity

The request is valid, but the target provider conversation could not be resolved.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400
Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401
Check X-Api-Key and whether the workspace is active.