name_photo.set

POST /v1/commands/name_photo.set

Sets the iMessage line's own Name and Photo card — what every person the line writes to sees. It does not edit a vCard, and it does not change anyone else's contact.

Honours Idempotency-Key. While the line's sending is paused a set is refused at once, 503 upstream_unavailable with reason: outbound_paused, and nothing is queued.

Target

The line itself, as on name_photo.get.

Payload

At least one of these. A set naming nothing to change is 422 validation_failed at payload.

Each of these is 422 validation_failed before anything is sent:

• any other key, a blank or over-long name, or a link that is not https, at payload.<key>;
• a link that cannot be fetched, or a file that is not such an image or is over 8 MiB, at payload.photoUrl, its reason one of the link refusals a media send meets: media_fetch_refused, media_fetch_failed, media_too_large or unsupported_media_type;
• a target.lineId that is not a line of this project in the key's environment — a 403 line_not_allowed rather than a 422, with details.lineId naming the id sent.

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: card-set-2026-09-30" \
  -H "x-mapier-version: 2026-10-15" \
  -d '{
    "target": { "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d" },
    "payload": {
      "name": "Northwind Support",
      "photoUrl": "https://example.com/brand/avatar.png"
    }
  }'

Response

{
  "commandId": "cmd-6",
  "status": "queued",
  "disposition": "queued",
  "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
  "lineSelection": "named"
}

The set succeeded once the line read the change back, and its command frame carries the card as read: namePhoto, with name, firstName, lastName and hasPhoto, as on name_photo.get. The photo itself is never returned.

{
  "commandId": "cmd-6",
  "status": "succeeded",
  "type": "name_photo.set",
  "namePhoto": {
    "name": "Northwind Support",
    "firstName": null,
    "lastName": null,
    "hasPhoto": true
  },
  "failureClass": null
}

A set the line could not prove is ambiguous: the card may or may not have changed. Read it with name_photo.get before you set it again — and check a new photo on a phone, since hasPhoto is true for the old photo and the new one alike.

A line whose device does not carry the card settles failed with a capability errorCode, failureClass: capability, and nothing changes.

In test

The test line carries the set. Its card changes and the project's Sandbox page shows it once the set settles. A photo link is fetched and checked as a live line checks it, so a link live would refuse is the same 422 at payload.photoUrl; a link that passes is not kept, and no photo is drawn.

Errors

A command answers the one set of HTTP refusals POST /v1/commands/{type} publishes, so that table is the one to handle. What is particular to this type:

• 403 line_not_allowed for a target.lineId that is not a line of this project in the key's environment — details.reason: not_owned, details.lineId the id sent.
• 422 validation_failed at payload, payload.<key> or payload.photoUrl, as above.
• 404 unsupported_command with reason: not_on_channel on a line of any other channel.
• 503 line_unavailable for a paused or released line, and 503 upstream_unavailable with reason: outbound_paused while the line's sending is paused.

Related