Location

An iMessage line can ask a contact to share their location: a message.send whose payload is kind: "location_request" puts a card in their thread that reads, for example, "Mapier requested your location". The card has no buttons. If they tap it and pick how long to share (For One Hour, For Today, Always or Custom), their location arrives later as events, never on the send's own settlement.

Here is a request landing on the contact's iPhone, a text that says what to do with it, and the contact sharing their location for an hour:

{ "kind": "location_request" }

That is the whole payload. Any other key beside kind, a text included, is 422 validation_failed at that key before anything is written. To say why you are asking, send a text first.

Where a request can go

A location request travels on the line's conversation path alone: into a one-to-one conversation the transport has confirmed is with that one person, which it does the first time they write into it. A group, or a conversation not confirmed yet, is 422 validation_failed with reason: conversation_not_confirmed before anything is written. A request to a line on any other channel is 404 unsupported_command with reason: not_on_channel.

A reply is target.replyToMessageId, as on any send.

What succeeded means

succeeded means the card was sent — never that the person shared. Whether they share, and for how long, is theirs to decide in Messages, and nothing on the request's command frame changes when they do.

What the line's device can send is not known before a request is sent. A line whose device has not announced location requests — or replies on one, for a reply — is sent nothing: the command is accepted with a 202 and then settles failed with capability_constraint_violation (or capability_not_negotiated), failureClass: capability.

What comes back

A share reaches you as three event types, and only if you ask for them: location.share_started, location.updated with a new position about every 30 seconds, and location.share_ended. Open the stream with ?events=locations to get them as event: location frames, or subscribe a webhook endpoint to them by name — they are not in a new endpoint's default set. See Location events.

A location belongs to the contact on their one-to-one conversation with the line, never to a group, and is reported only once a message has passed between you: a person who shares before any message between you is not reported.

A worked request

curl https://api.mapier.ai/v1/commands/message.send \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pickup-4821-location-ask" \
  -H "x-mapier-version: 2026-10-15" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000001"
    },
    "payload": { "kind": "location_request" }
  }'

In test

On a test line the card is sent and delivered to the sandbox phone, and nobody shares back in answer to it. A location the sandbox phone shares arrives as a location event with simulated: true.

Related