User identities

Use id to identify a user, group, or bot. Phone numbers are separate, optional aliases.

Resource	ID format
User	`pmfa_lid_<id>`
Group	`pmfa_gid_<id>`
Bot	`pmfa_botid_<id>`

{
  "id": "pmfa_lid_100000011111111",
  "phoneNumber": "+15550001111",
  "username": "example"
}

Use id as your contact’s primary key. Update phoneNumber and username when present; a changed or hidden alias does not create a new user.

Resolve an alias

These reads require the contacts:read scope. Resolve a phone number or username before creating a local contact:

curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?phoneNumber=%2B15550001111" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"

curl "https://api.polymorfa.com/messaging/{session}/identities/resolve?username=example" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"

The response uses the same identity shape:

{
  "data": {
    "id": "pmfa_lid_100000011111111",
    "phoneNumber": "+15550001111",
    "username": "example"
  }
}

Some usernames require a four-digit key. A response with "keyRequired": true contains no guessed identity. Repeat the lookup with usernameKey=1234 after obtaining the key from the user. You can also pass an existing id to read its known aliases.

Verify a user’s encryption identity

Request WhatsApp’s identity verification code with the stable user ID:

curl "https://api.polymorfa.com/messaging/{session}/users/pmfa_lid_100000011111111/security-code" \
  -H "Authorization: Bearer $POLYMORFA_TOKEN"

{
  "data": {
    "id": "pmfa_lid_100000011111111",
    "phoneNumber": "+15550001111",
    "username": "example",
    "numericCode": "123456789012345678901234567890123456789012345678901234567890",
    "qrCode": "base64-encoded-display-payload"
  }
}

Compare numericCode with the code shown by the other user. To use qrCode, base64-decode it and render the resulting bytes as the QR content for comparison. A changed code means the account’s identity or linked-device set changed and must be verified again. The endpoint accepts only a pmfa_lid_ user ID; resolve phone numbers and usernames first. Polymorfa returns WhatsApp’s display payload and never exposes the underlying identity-key payload.

Hidden phone numbers

A missing phoneNumber does not mean the user is unresolved. Continue using their id. To ask a contact without a known phone number to share their phone number, send a consent request:

{
  "conversation": { "id": "pmfa_lid_100000011111111" },
  "content": { "requestPhoneNumber": {} }
}

The recipient can decline. If they accept, Polymorfa emits a message.received webhook with type: "phone_number_shared"; the sender’s id is unchanged and phoneNumber is added as an alias.

Upsert rule

For every contact, participant, sender, voter, presence source, and blocklist entry:

Upsert by id.
Update phoneNumber and username only when they are present.
Never create a second record because an alias appeared, changed, or disappeared.

This rule prevents one person from becoming separate phone-number, username, and ID records.

Linked devices

Device lookups return the user’s id or phoneNumber, plus a numeric device value. Together, they identify a linked device:

{
  "id": "pmfa_lid_100000011111111",
  "device": 4
}

Overview

Messaging API

Platform API

Graph API

Webhook events

Resolve an alias

Verify a user’s encryption identity

Hidden phone numbers

Upsert rule

Linked devices

​Resolve an alias

​Verify a user’s encryption identity

​Hidden phone numbers

​Upsert rule

​Linked devices

Resolve an alias

Verify a user’s encryption identity

Hidden phone numbers

Upsert rule

Linked devices