errand_save_address

Saves the address the user picked (optionally with a door-number detail) to the delivery-errand address book, so it can be reused directly by address_id next time without searching again. You can save a contact name and phone at the same time, so the order doesn’t need to ask for them again; the phone is only ever returned masked. An address counts as the same entry only when the address, door-number detail, and contact are all identical: an existing match is returned as-is instead of creating a duplicate. The same place saved with a different door number or a different contact is stored as a separate entry.

Address flow: search for a place with errand_search_addresses to get its coordinates, then save it with errand_save_address. Afterward, view it with errand_list_addresses, edit it with errand_update_address, or remove it with errand_delete_address.

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix), from `errand_verify_user_bind`
`address`	string	Yes	—	Address (name + full address)
`lat`	number	Yes	—	Latitude (GCJ-02), from `errand_search_addresses`
`lng`	number	Yes	—	Longitude (GCJ-02), from `errand_search_addresses`
`contact_name`	string	No	—	Contact name
`contact_phone`	string	No	—	Contact phone; saved once, so future orders don’t need to repeat it. Stored encrypted, always returned masked
`detail`	string	No	—	Door number / extra detail (e.g. “Building 3, Room 303”); automatically appended to the address at order time, returned as-is when the address book is queried
`tag`	string	No	—	Label (e.g. “Home”, “Office”)

Returns

The saved address object; id has a plat_ prefix.

Field	Type	Description
`id`	string	Address ID (`plat_` prefix); use directly as `address_id`
`contact_name`	string	Contact name (may be empty)
`contact_phone_masked`	string	Masked contact phone (e.g. `138****5678`); empty string if no phone was saved
`address`	string	Address
`detail`	string	Door number / extra detail (e.g. “Building 3, Room 303”); empty string if never set
`lat`	number	Latitude (GCJ-02)
`lng`	number	Longitude (GCJ-02)
`tag`	string	Label
`source`	string	Address origin; always `errand` for addresses saved through this capability
`last_used_at`	string \| null	Last-used timestamp
`use_count`	integer	Number of times used

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing consent grant (no `consent_grant_id`)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CONSENT_GRANT_WRONG_CAP`	Consent grant belongs to a different capability; the delivery-errand capability needs its own grant
`CAP_NOT_BOUND`	The delivery-errand capability is not enabled for this agent
`ADDRESS_INCOMPLETE`	The address or coordinates are missing
`ADDRESS_FIELD_TOO_LONG`	Address / contact / detail / tag / phone exceeds the length limit

See Error Handling for the full list.

Call Example

{
  "name": "errand_save_address",
  "arguments": {
    "consent_grant_id": "<consent_grant_id>",
    "address": "五一广场 黄兴中路88号",
    "lat": 28.1965,
    "lng": 112.9773,
    "detail": "东门",
    "tag": "公司"
  }
}

Overview

Authorization

Addresses

Quote & order

Order management

Callbacks & reference

errand_save_address