Link Generation via SMS

POST /v1/link/go/sms

Generates a secure, signed Doorstep Go URL for a specified address and sends it as an SMS to a provided phone number.

Requires an API key sent as a Bearer token in the Authorization header.

note

The URL sent in the SMS is a shortened version of the generated link, since the full signed URL is too long to send comfortably in a text message. The full-length link is always returned in the API response.

Request

Request Body

Parameter	Type	Required?	Description
phone	string	Yes	Phone number to send the SMS to, in E.164 format. Example: +15551234567
address	string	Yes	Street address of delivery location. Example: 123 Main St, New York, NY 10001
deliveryID	string	No	Unique identifier for this delivery order. Used to track the delivery within Doorstep Go. Example: order_456

Example Request

curl -X POST "https://api.core.doorstep.ai/v1/link/go/sms" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15551234567", "address": "123 Main St, New York, NY 10001"}'

Example Request with Delivery ID

curl -X POST "https://api.core.doorstep.ai/v1/link/go/sms" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15551234567", "address": "123 Main St, New York, NY 10001", "deliveryID": "order_456"}'

Response

200

The link was generated and the SMS was sent successfully.

Response Body

Field	Type	Description
status	number	Status of the request.
message	string	A description of the result.
link	string	The full generated link to the Doorstep Go application. A shortened version of this link is what gets sent in the SMS.
expirationDateISO	string	When the link's token expires, in ISO 8601 format.

Example Response

{
  "status": 200,
  "message": "Link sent successfully",
  "link": "https://go.doorstep.ai?address=123%20Main%20St&buildingID=abc123&token=eyJhbGc...",
  "expirationDateISO": "2026-05-21T14:30:00.000Z"
}

The recipient receives a text message like this:

Doorstep delivery guide: tinyurl.com/yszpje2t

What the recipient receives

400

A required parameter is missing or invalid.

{
  "status": 400,
  "code": "bad_request",
  "message": "Missing required parameter: phone"
}

401

The API key is missing or invalid.

{
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized"
}

404

No valid destination was found for the requested address, or the address is not on the whitelist.

{
  "status": 404,
  "code": "not_found",
  "message": "A valid destination was not found with input: 123 Main St, San Francisco, CA 94105"
}

500

Something went wrong on our end. Try the request again later.

{
  "status": 500,
  "code": "internal_server_error",
  "message": "An unexpected error occurred"
}