Link Generation

GET /v1/link/go

Returns a secure, signed Doorstep Go URL for a specified address. Doorstep Go is a web app that helps users navigate to the correct entrance, parking area, elevator, and can be launched from within your application.

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

note

/v1/link is a legacy alias for this endpoint and continues to work for existing integrations. New integrations should use /v1/link/go.

Request

Query Parameters

Parameter	Type	Required?	Description
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
entrance	string	No	Set to true to include entrance/parking data for the address in the response (entranceData).

Example Request

curl "https://api.core.doorstep.ai/v1/link/go?address=123 Main St, New York, NY 10001" \
  -H "Authorization: Bearer $API_KEY"

Example Request with Delivery ID

curl "https://api.core.doorstep.ai/v1/link/go?address=123 Main St, New York, NY 10001&deliveryID=order_456" \
  -H "Authorization: Bearer $API_KEY"

Response

200

A signed link for the requested address.

Response Body

Field	Type	Description
status	number	Status of the request.
message	string	A description of the result.
link	string	The generated link to the Doorstep Go application.
link_id	string	Unique identifier for the generated link.
expirationDateISO	string	When the link's token expires, in ISO 8601 format.
entranceData	object	The address's preferred entrance: _id, location (lat/lng), and primary (whether it's the building's main entry). Only present when entrance=true was passed in the request.

Example Response

{
  "status": 200,
  "message": "Link created successfully",
  "link": "https://go.doorstep.ai?address=123%20Main%20St&buildingID=abc123&link_id=3e6e4f2a-1c9d-4b3a-9f2e-9b6f7a2c8e10&token=eyJhbGc...",
  "link_id": "3e6e4f2a-1c9d-4b3a-9f2e-9b6f7a2c8e10",
  "expirationDateISO": "2026-05-21T14:30:00.000Z",
  "entranceData": {
    "_id": "e7fbbb63-0f48-4cb1-9371-918c7a83010b",
    "location": {
      "lat": 40.767606822432576,
      "lng": -73.99268101925855
    },
    "primary": true
  }
}

400

A required parameter is missing or invalid. For example, address was not provided.

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

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"
}

Link Structure

Generated links have the following structure:

https://go.doorstep.ai?[parameters]

You can append optional query parameters to control which waypoints, base map, and controls the Doorstep Go app displays. See Doorstep Go Link Parameters in the API reference for the full list.

Token Expiration

Generated tokens automatically expire after a configurable period. The expiration date is returned in the expirationDateISO field in ISO 8601 format. Generate a new link if the token has expired.