name_photo.set

POST /v1/commands/name_photo.set

Sets this line's own Messages name and photo — the card name_photo.share offers and name_photo.get reads. It does not edit a vCard, and it does not set someone else's nickname.

The target is the line itself. Omit target, or send { "kind": "connector" }.

Honours Idempotency-Key. While outbound is paused the POST is 503 and nothing is queued — the command is not held for later.

Any authenticated caller for the account may post this. There is no second allow-list. Which Mac the write hits is the account's connector.

Payload

At least one of the following, after the strings are trimmed. An empty body, or a body that trims to nothing, is refused.

Wallpaper and poster cannot be set. Extra keys — wallpaper, poster, file, and anything else that is not in the table — are 422 at the door. No command is created.

A photo has to be JPEG, PNG, GIF, WEBP or HEIC, and at most 8 MiB. That check is this command, not POST /v1/media. Media also stages ordinary attachments, so it accepts types this command will refuse (TIFF, BMP, AVIF, SVG, and others). An oversized or unreadable avatar is 422 image_too_large or unreadable_image here.

The upload must have landed before you post the set, the same rule as an attachment send:

• 409 transfer_not_landed — staged, not on the Mac yet. No command is created. Post the same request again.
• 422 unknown_transfer — an id this account never staged, a typo, or another account's transfer. A foreign id is this error, not a description of the other line's file.

Request

curl https://api.mapier.ai/v1/commands/name_photo.set \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: name-photo-set-1" \
  -d '{
    "payload": { "name": "Ada Lovelace", "first": "Ada", "last": "Lovelace" }
  }'

Response

{ "commandId": "cmd-6", "status": "queued", "disposition": "queued" }

succeeded with outcome: "set" means a follow-up read matched the fields this command named. requested: true on the snapshot is not that proof. Sends and other verbs do not carry outcome: "set".

On a proved set, namePhoto on the command event is the read-back snapshot plus two fields:

The rest of the object is the same snapshot name_photo.get returns. wallpaper is always null.

A photo is proved by its fingerprint

When the payload includes transferId, outcome: "set" requires the image fingerprint to match, not merely hasAvatar: true.

The comparison is the MD5 of the photo bytes. The read-back imageHash must equal the set result's expectedImageHash — the hash of the card that was sent, not a hash the Mac happens to be showing. That match is what proves a replacement when the card already had an avatar. hasAvatar: true only means some avatar is there. When the card already had one, that flag was already true before your upload.

imageHash and expectedImageHash are that comparison. They are not fields on the namePhoto object you receive. You see the result as outcome.

A Mac whose build predates the fingerprint can prove a photo only when the card had no avatar before. Replacing an existing avatar there settles needs_reconcile with errorCode name_photo_set_unverified. Treat that as applied but unproven: the photo may be the new one, and the settlement will not say so.

The same settlement covers any set the line could not prove, including one that had already started (needs_reconcile / name_photo_set_unverified). Do not retry blindly — you may stack a second write on top of a write that landed. name_photo.get confirms the name fields, but not a replaced photo: hasAvatar is true for the old image and the new one, and the snapshot carries no image hash. Check a photo replacement by eye on a device before you post again. See needs_reconcile.

A Mac without the setter settles failed with a capability errorCode and changes nothing.

Errors

Related