name_photo.get

POST /v1/commands/name_photo.get

Reads the iMessage line's own Name and Photo card: the name and photo every person the line writes to sees. It is not a vCard, and it is not anyone else's contact. It messages nobody.

Honours Idempotency-Key. The 202 is followed by a command frame carrying the card as namePhoto.

Target

The line itself, never a conversation or a person.

Payload

None. Send {} or leave payload out. Any key in it is 422 validation_failed at payload.<key> before anything is sent. A photo link at payload.photoUrl, and a payload that names nothing to change, are name_photo.set's refusals, not this command's.

Request

curl https://api.mapier.ai/v1/commands/name_photo.get \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: card-read-1" \
  -H "x-mapier-version: 2026-10-15" \
  -d '{
    "target": { "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d" }
  }'

Response

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

Then, on the response stream, a succeeded frame with the card:

{
  "commandId": "cmd-5",
  "logicalActionId": "card-read-1",
  "status": "succeeded",
  "errorCode": null,
  "conversationId": null,
  "type": "name_photo.get",
  "messageId": null,
  "namePhoto": {
    "name": "Ada Lovelace",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "hasPhoto": true
  },
  "failureClass": null
}

The photo itself is not returned. There is no way to read it back: to change it, set a new one. namePhoto is null on every settlement but a succeeded get or set.

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 card. It starts as the line's own name, and a name_photo.set changes it. The project's Sandbox page shows the card as it stands.

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.<key> for any key.
• 404 unsupported_command with reason: not_on_channel on a line of any other channel.
• 503 line_unavailable for a paused or released line.

Related